jBASE

Programmers Reference Manual

Part No: 42-M-JAPRM-20.1

Copyright 1991 - 1997 James Anthony Computing. All rights reserved.

Copyright
All rights to this documentation are reserved. This document contains proprietary information that is protected
by copyright. No part of this document may be reproduced, transmitted, or made available directly or indirectly
to a third party without the express written agreement of James Anthony Computing.
While every effort has been made to ensure a complete and accurate document, no responsibility is expressed or
implied for problems arising from any inaccuracy contained herein. Additionally James Anthony Computing
reserves the right to make changes to this document and the software described herein at any time and without
notice.

Acknowledgements
jBASE, jBC, jED, jSHELL, jLP, jEDI, jCL, jQL, j1, j2 and j3 are trademarks of James Anthony Computing.
UNIX is a registered trademark of X/Open Co. Ltd.
REALITY is a trademark of MDIS plc.
PICK is a trademark of Pick Systems Inc.
All other trademarks are acknowledged.

ii

Table of Contents
Copyright....................................................................................................................i
Acknowledgements..............................................................................................ii
Table of Contents .................................................................................................... iii
Using the Manual .................................................................................................. xiii
Summary of Chapters....................................................................................... xiii
Notation Conventions .......................................................................................xiv
Errata and Comments ..............................................................................................xv
Chapter 1 : Introduction to jBASE.................................................................... 1-1
Introduction to jBASE........................................................................................... 1-1
Run-Time Components .................................................................................... 1-1
Development Components............................................................................... 1-1
Administrative Components............................................................................. 1-1
Requirements for Running jBASE................................................................... 1-1
Chapter 2 : jBC ................................................................................................... 2-1
jBC Language Overview ....................................................................................... 2-1
Features of jBC ................................................................................................ 2-2
Benefits of Using jBC...................................................................................... 2-2
jBC Environment ............................................................................................. 2-3
jBC Programming ............................................................................................ 2-3
jBC Comparisons............................................................................................. 2-3
File and Directory Organisation....................................................................... 2-4
jBC Libraries ................................................................................................... 2-5
jBC Compiler and Runtime.............................................................................. 2-6
General Programming Advice.......................................................................... 2-6
jBC Compiler ...................................................................................................... 2-10
Cataloging and Running your Programs.............................................................. 2-11
CATALOG Command ................................................................................... 2-11
DECATALOG and DELETE-CATALOG Commands ................................. 2-12
RUN Command ............................................................................................. 2-12
jBC Debugger...................................................................................................... 2-13
Entering the Debugger ................................................................................... 2-13
Debug Arguments at Run-time....................................................................... 2-14
Debugger Commands..................................................................................... 2-15
Explanation of Complex Commands ............................................................. 2-22
Debugger Symbol Tables............................................................................... 2-26
jBC Language Reference..................................................................................... 2-27
Syntactical Elements...................................................................................... 2-27
Data Records.................................................................................................. 2-28
Assigning Variables ....................................................................................... 2-28
Reserved Words............................................................................................. 2-29
Arithmetic Expressions .................................................................................. 2-30
Strings and String Operations ........................................................................ 2-32
Relational Expressions................................................................................... 2-33
Program Layout ............................................................................................. 2-33
Statements and Statement Labels................................................................... 2-34
Program Files................................................................................................. 2-35
Formatting Data for Input or Display............................................................. 2-35
Pattern Matching............................................................................................ 2-35
Conversion Codes for Data............................................................................ 2-36
Program Flow ................................................................................................ 2-36
Looping Constructs........................................................................................ 2-37
Subroutines .................................................................................................... 2-38
C Functions.................................................................................................... 2-38
Handling Arrays and Data Files..................................................................... 2-39

iii

Dimensioned Arrays .......................................................................................2-39

Dynamic Arrays..............................................................................................2-40
File Handling..................................................................................................2-41
Locking Mechanisms......................................................................................2-41
jBC Statements.....................................................................................................2-43
@(Col, Row) ..................................................................................................2-43
@(ScreenCode) ..............................................................................................2-43
ABORT ..........................................................................................................2-44
ABS( ) ............................................................................................................2-45
ALPHA( ).......................................................................................................2-45
ASCII( )..........................................................................................................2-46
ASSIGNED( ) ................................................................................................2-46
BITCHANGE.................................................................................................2-47
BITCHECK....................................................................................................2-47
BITLOAD ......................................................................................................2-48
BITRESET .....................................................................................................2-48
BITSET ..........................................................................................................2-49
BREAK ..........................................................................................................2-49
CALL .............................................................................................................2-50
CASE..............................................................................................................2-51
CHAIN ...........................................................................................................2-51
CHANGE .......................................................................................................2-52
CHAR( ) .........................................................................................................2-52
CHDIR( )........................................................................................................2-53
CHECKSUM ( ) .............................................................................................2-53
CLEAR...........................................................................................................2-53
CLEARFILE ..................................................................................................2-54
CLOSE ...........................................................................................................2-54
COMMON .....................................................................................................2-55
COL1( ) & COL2( )........................................................................................2-55
COLLECTDATA...........................................................................................2-55
CONTINUE ...................................................................................................2-56
CONVERT .....................................................................................................2-56
CONVERT( ) .................................................................................................2-57
COS( ) ............................................................................................................2-57
COUNT( ) ......................................................................................................2-58
CRT ................................................................................................................2-58
DATA.............................................................................................................2-58
DATE( ) .........................................................................................................2-59
DCOUNT( ) ...................................................................................................2-59
DEBUG ..........................................................................................................2-60
DEFC..............................................................................................................2-60
DEL................................................................................................................2-61
DELETE.........................................................................................................2-61
DELETELIST ................................................................................................2-62
DIMENSION .................................................................................................2-62
DTX( )............................................................................................................2-63
EBCDIC( ) .....................................................................................................2-63
ECHO.............................................................................................................2-63
ENTER...........................................................................................................2-64
EQUATE........................................................................................................2-64
EXECUTE......................................................................................................2-65
EXIT( )...........................................................................................................2-66
EXP( ) ............................................................................................................2-67
EXTRACT .....................................................................................................2-67
FIELD( ).........................................................................................................2-67
FIND ..............................................................................................................2-68
FINDSTR .......................................................................................................2-69

iv

FOOTING...................................................................................................... 2-69
FOR ............................................................................................................... 2-70
GETCWD( ) .................................................................................................. 2-71
GETENV( ) ................................................................................................... 2-71
GETLIST ....................................................................................................... 2-71
GOSUB.......................................................................................................... 2-72
GO{TO} ........................................................................................................ 2-73
GROUP( ) ...................................................................................................... 2-73
HEADING ..................................................................................................... 2-74
ICONV( )....................................................................................................... 2-74
IF.................................................................................................................... 2-75
IN................................................................................................................... 2-75
INDEX( ) ....................................................................................................... 2-76
INPUT ........................................................................................................... 2-76
INPUTNULL................................................................................................. 2-77
INS................................................................................................................. 2-78
INSERT ......................................................................................................... 2-78
INT( )............................................................................................................. 2-79
LEN( )............................................................................................................ 2-79
LN( ) .............................................................................................................. 2-80
LOCATE ....................................................................................................... 2-80
LOCK ............................................................................................................ 2-81
LOOP............................................................................................................. 2-81
MAT .............................................................................................................. 2-82
MATCH{ES} ................................................................................................ 2-82
MATBUILD .................................................................................................. 2-83
MATPARSE .................................................................................................. 2-84
MATREAD.................................................................................................... 2-84
MATREADU................................................................................................. 2-85
MATWRITE.................................................................................................. 2-86
MATWRITEU............................................................................................... 2-87
MOD( ) and REM( ) ...................................................................................... 2-87
NOT( ) ........................................................................................................... 2-88
NULL............................................................................................................. 2-88
NUM( ) .......................................................................................................... 2-88
OCONV( ) ..................................................................................................... 2-89
ON...GOSUB, ON...GOTO ........................................................................... 2-90
OPEN............................................................................................................. 2-91
OUT ............................................................................................................... 2-91
PAGE............................................................................................................. 2-92
PERFORM..................................................................................................... 2-92
PRECISION................................................................................................... 2-92
PRINT............................................................................................................ 2-93
PRINTER ON|OFF|CLOSE........................................................................... 2-93
PRINTERR.................................................................................................... 2-94
PROCREAD .................................................................................................. 2-94
PROCWRITE ................................................................................................ 2-94
PROGRAM.................................................................................................... 2-95
PROMPT ....................................................................................................... 2-95
PUTENV ....................................................................................................... 2-95
PWR( )........................................................................................................... 2-96
READ ............................................................................................................ 2-96
READLIST .................................................................................................... 2-97
READNEXT.................................................................................................. 2-98
READT .......................................................................................................... 2-98
READU ......................................................................................................... 2-99
READV ....................................................................................................... 2-100
READVU..................................................................................................... 2-101
REGEXP...................................................................................................... 2-102

RELEASE ....................................................................................................2-102
REMOVE.....................................................................................................2-103
REPLACE ....................................................................................................2-104
RETURN......................................................................................................2-104
REWIND......................................................................................................2-105
RND .............................................................................................................2-105
RQM.............................................................................................................2-105
RTNDATA...................................................................................................2-105
SELECT .......................................................................................................2-106
SENTENCE .................................................................................................2-106
SEQ( ) ..........................................................................................................2-107
SIN( )............................................................................................................2-107
SLEEP ..........................................................................................................2-108
SORT( )........................................................................................................2-108
SOUNDEX( ) ...............................................................................................2-109
SPACE( )......................................................................................................2-109
SQRT ...........................................................................................................2-109
STOP ............................................................................................................2-110
STR( )...........................................................................................................2-110
SUBROUTINE ............................................................................................2-110
SYSTEM ......................................................................................................2-111
TAN( )..........................................................................................................2-113
TIME( ) ........................................................................................................2-113
TIMEDATE( )..............................................................................................2-113
TRANSABORT ...........................................................................................2-114
TRANSEND.................................................................................................2-114
TRANSQUERY ...........................................................................................2-114
TRANSTART ..............................................................................................2-115
TRIM( ) ........................................................................................................2-115
TRIMB( ) .....................................................................................................2-116
TRIMF( )......................................................................................................2-116
UNASSIGNED ............................................................................................2-116
UNLOCK .....................................................................................................2-116
WEOF ..........................................................................................................2-116
WRITE .........................................................................................................2-117
WRITELIST.................................................................................................2-118
WRITET.......................................................................................................2-118
WRITEU ......................................................................................................2-119
WRITEV ......................................................................................................2-119
WRITEVU ...................................................................................................2-120
XTD( )..........................................................................................................2-121
Chapter 3 : jCL ....................................................................................................3-1
Introduction............................................................................................................3-1
jCL Program Structure ...........................................................................................3-2
Executing jCL Programs ........................................................................................3-3
Login jCL Programs...............................................................................................3-4
Internal Data Storage .............................................................................................3-5
Primary Input Buffer ........................................................................................3-5
Secondary Input Buffer ....................................................................................3-5
Primary Output Buffer......................................................................................3-5
Secondary Output Buffer..................................................................................3-6
Active Input Buffer...........................................................................................3-6
Active Output Buffer........................................................................................3-6
Buffer Data and Pointers ..................................................................................3-6
File Buffers.......................................................................................................3-7
Select Registers ................................................................................................3-7
Buffer References.............................................................................................3-8

vi

Hints and Tips ....................................................................................................... 3-9

Branching......................................................................................................... 3-9
Grouping Commands ....................................................................................... 3-9
Readability....................................................................................................... 3-9
TIME and DATE ............................................................................................. 3-9
Validating Date and Time.............................................................................. 3-10
Long Statements............................................................................................. 3-10
Concatenation ................................................................................................ 3-10
Spooler Hold File Numbers ........................................................................... 3-10
jCL Commands.................................................................................................... 3-11
Input Buffer Commands................................................................................. 3-11
Output Buffer Commands .............................................................................. 3-11
Data Movement Commands........................................................................... 3-11
Input/Output Buffer Operations ..................................................................... 3-11
Jump and Branch Operations ......................................................................... 3-11
Conditional Operations .................................................................................. 3-12
File Operations............................................................................................... 3-12
Arithmetic Operators ..................................................................................... 3-12
Processing...................................................................................................... 3-12
Terminal and Printer Output .......................................................................... 3-12
Debugging...................................................................................................... 3-13
Exiting ........................................................................................................... 3-13
jCL Command Syntax ......................................................................................... 3-14
( ) ................................................................................................................... 3-14
[ ] ................................................................................................................... 3-15
+..................................................................................................................... 3-15
-...................................................................................................................... 3-16
A .................................................................................................................... 3-17
B .................................................................................................................... 3-18
BO.................................................................................................................. 3-19
C .................................................................................................................... 3-19
D .................................................................................................................... 3-20
DE.................................................................................................................. 3-20
DEBUG ......................................................................................................... 3-21
F..................................................................................................................... 3-21
F;.................................................................................................................... 3-21
F-CLEAR....................................................................................................... 3-22
F-DELETE..................................................................................................... 3-23
F-FREE .......................................................................................................... 3-23
F-KLOSE....................................................................................................... 3-24
F-OPEN ......................................................................................................... 3-24
F-READ......................................................................................................... 3-25
F-UREAD ...................................................................................................... 3-26
F-WRITE ....................................................................................................... 3-26
FB .................................................................................................................. 3-27
G, GO or GOTO ............................................................................................ 3-28
GO B.............................................................................................................. 3-29
GO F .............................................................................................................. 3-30
GOSUB.......................................................................................................... 3-30
H .................................................................................................................... 3-31
IBH ................................................................................................................ 3-32
IBN ................................................................................................................ 3-33
IBP................................................................................................................. 3-34
IF.................................................................................................................... 3-35
IF (Multivalued)............................................................................................. 3-36
IF (with Mask) ............................................................................................... 3-37
IF E ................................................................................................................ 3-39
IF S ................................................................................................................ 3-39
IFN................................................................................................................. 3-40

vii

IH ...................................................................................................................3-41
IN ...................................................................................................................3-43
IP ....................................................................................................................3-43
IT....................................................................................................................3-44
L .....................................................................................................................3-45
M ....................................................................................................................3-46
MS..................................................................................................................3-46
MV .................................................................................................................3-47
MVA ..............................................................................................................3-49
MVD ..............................................................................................................3-49
O.....................................................................................................................3-50
P .....................................................................................................................3-50
RI....................................................................................................................3-51
RO ..................................................................................................................3-52
RSUB .............................................................................................................3-53
RTN................................................................................................................3-53
S .....................................................................................................................3-54
STOFF............................................................................................................3-55
STON .............................................................................................................3-55
T .....................................................................................................................3-55
TR...................................................................................................................3-57
U.....................................................................................................................3-58
X.....................................................................................................................3-59
List Processing Commands ..................................................................................3-60
PQ-RESELECT..............................................................................................3-60
PQ-SELECT...................................................................................................3-60
PQ and PQN Differences .....................................................................................3-62
Delimiters .......................................................................................................3-62
Buffers............................................................................................................3-62
Commands......................................................................................................3-62
Chapter 4 : jQL....................................................................................................4-1
Introduction............................................................................................................4-1
jQL Command Sentence Construction...................................................................4-2
Command Syntax .............................................................................................4-2
Reserved Words and Symbols..........................................................................4-2
Entering a jQL Command Sentence .................................................................4-3
Default Data Definition Records ......................................................................4-3
jQL Output (Reports) .......................................................................................4-4
jQL Commands ................................................................................................4-4
Throwaway Connectives ..................................................................................4-5
File Specifiers...................................................................................................4-5
Record List Clause ...........................................................................................4-5
Selection Criteria Clause ..................................................................................4-7
Sort Criteria Clause ........................................................................................4-10
Using Clause...................................................................................................4-11
Output Specification Clause ...........................................................................4-11
Format Specification Clause...........................................................................4-13
USING Clause................................................................................................4-15
Command Options..........................................................................................4-15
Macros............................................................................................................4-16
jQL Commands ....................................................................................................4-18
BSELECT Command .....................................................................................4-18
COUNT Command.........................................................................................4-18
EDELETE Command.....................................................................................4-19
ESEARCH Command ....................................................................................4-19
LIST Command ..............................................................................................4-20
LIST-LABEL Command ................................................................................4-21

viii

LISTDICT Command .................................................................................... 4-22

REFORMAT Command ................................................................................ 4-22
SELECT Command ....................................................................................... 4-23
SORT Command............................................................................................ 4-24
SORT-LABEL Command.............................................................................. 4-25
SREFORMAT Command .............................................................................. 4-26
SSELECT Command ..................................................................................... 4-27
File Definition Records ....................................................................................... 4-29
Record Structure ............................................................................................ 4-29
Sublists - V Code ........................................................................................... 4-29
Data Definition Records ...................................................................................... 4-31
Record Layout ............................................................................................... 4-31
Special Field-mark Counts............................................................................. 4-32
Default Output Specification ......................................................................... 4-32
Predefined Data Definition Records .............................................................. 4-33
Conversion Codes................................................................................................ 4-34
Field 8 Codes (Pre-process)........................................................................... 4-34
Field 7 Codes (Output) .................................................................................. 4-34
Field 7 Codes (Input) ..................................................................................... 4-35
Processing Code Summary ............................................................................ 4-35
Multiple Conversion Codes ........................................................................... 4-36
Print Limiter Clause....................................................................................... 4-36
Controlling and Dependent Fields ................................................................. 4-36
Selections....................................................................................................... 4-36
Sorts............................................................................................................... 4-36
TOTAL Connectives...................................................................................... 4-36
BREAK-ON Connectives .............................................................................. 4-37
A Code - Algebraic Functions ............................................................................. 4-38
Syntax Summary ............................................................................................ 4-38
Summary of Operands ................................................................................... 4-39
Summary of Operators ................................................................................... 4-40
Field Number (FMC) Operand ...................................................................... 4-40
N (Field Name) Operand ............................................................................... 4-41
Literal Operand.............................................................................................. 4-42
System Parameter Operands .......................................................................... 4-43
Special Operands ........................................................................................... 4-43
Format Codes................................................................................................. 4-44
Operators ....................................................................................................... 4-45
B Code - Subroutine Call .................................................................................... 4-47
C Code - Concatenation....................................................................................... 4-48
CALL Code - Subroutine Call............................................................................. 4-49
D Code - Date Conversion .................................................................................. 4-51
D1 / D2 Codes - Controlling and Dependent Fields ............................................ 4-53
F Code - Mathematical Functions........................................................................ 4-54
Syntax Summary ............................................................................................ 4-54
Push Operators............................................................................................... 4-55
Arithmetic Operators ..................................................................................... 4-56
Miscellaneous Operators................................................................................ 4-56
Relational Operators ...................................................................................... 4-57
Logical Operators .......................................................................................... 4-57
Multivalues .................................................................................................... 4-57
Format Codes................................................................................................. 4-58
G Code - Group Extraction.................................................................................. 4-59
L Code - Length................................................................................................... 4-60
MC Codes - Mask Character ............................................................................... 4-61
Summary........................................................................................................ 4-61
Changing Case ............................................................................................... 4-62
Extracting Characters..................................................................................... 4-62
Replacing Characters ..................................................................................... 4-63

ix

Converting Characters ....................................................................................4-63

Converting Numeric Values ...........................................................................4-64
MD Code - Mask Decimal without Justification..................................................4-66
MK Code - Mask Metric......................................................................................4-67
ML/MR Codes - Mask Decimal with Justification...............................................4-68
MP Code - Masked Packed Decimal ...................................................................4-70
MS Code - Mask Sequence ..................................................................................4-71
MT Code - Mask Time ........................................................................................4-72
P Code - Pattern Matching ...................................................................................4-73
R Code - Range Check.........................................................................................4-74
S Code - Substitute...............................................................................................4-75
T Code - Text Extraction .....................................................................................4-76
Tfile Code - Translation.......................................................................................4-77
U Code - User Exit...............................................................................................4-79
Chapter 5 : List Processing .................................................................................5-1
Introduction............................................................................................................5-1
Command Level List Processing............................................................................5-2
COPY-LIST .....................................................................................................5-2
DELETE-LIST .................................................................................................5-3
EDIT-LIST.......................................................................................................5-3
FORM-LIST.....................................................................................................5-4
GET-LIST ........................................................................................................5-4
LIST-LISTS .....................................................................................................5-5
NEW-GET-LIST..............................................................................................5-5
NEW-SAVE-LIST ...........................................................................................5-5
NEW-SORT-LIST ...........................................................................................5-6
QSELECT ........................................................................................................5-6
SAVE-LIST......................................................................................................5-7
SEARCH Command.........................................................................................5-7
SORT-LIST......................................................................................................5-8
XSELECT ........................................................................................................5-8
jBC List Processing..............................................................................................5-10
jCL List Processing..............................................................................................5-11
jQL List Processing..............................................................................................5-12
Chapter 6 : jBASE Editors..................................................................................6-1
jBASE Editors........................................................................................................6-1
jED Editor..............................................................................................................6-2
Editor Screen....................................................................................................6-2
Invoking jED ....................................................................................................6-2
Using the jED Editor ........................................................................................6-4
Keyboard Personalisation.................................................................................6-4
Command Line Operations...............................................................................6-6
Leaving the Editor ............................................................................................6-6
Locating Strings ...............................................................................................6-7
Replacing Strings .............................................................................................6-8
Copying, Pasting and Cutting Blocks of Text ..................................................6-9
jBC Line Indentation ......................................................................................6-10
Miscellaneous Commands ..............................................................................6-10
Changing jED Command Keys.......................................................................6-11
ED Editor .............................................................................................................6-13
Chapter 7 : jBASE Commands ...........................................................................7-1
jBASE Commands .................................................................................................7-1
Account Management.......................................................................................7-1
Editing ..............................................................................................................7-1
File Management and Searching ......................................................................7-1

General............................................................................................................. 7-1
Internationalisation .......................................................................................... 7-1
jBC................................................................................................................... 7-1
jBTP................................................................................................................. 7-1
jCL................................................................................................................... 7-2
jQL................................................................................................................... 7-2
jLP Spooler ...................................................................................................... 7-2
List Processing................................................................................................. 7-2
Migration ......................................................................................................... 7-2
System Housekeeping and Tuning................................................................... 7-3
Tape Operation ................................................................................................ 7-3
Chapter 8 : Environment Variables................................................................... 8-1
Introduction ........................................................................................................... 8-1
Variable: JBASETMP ..................................................................................... 8-1
Variable: JBC_ENDRESTART....................................................................... 8-1
Variable: JBC_TCLRESTART ....................................................................... 8-1
Variable: JBCDEFDICTS ............................................................................... 8-2
Variable: JBCEMULATE................................................................................ 8-2
Variable: JBCERRFILE .................................................................................. 8-2
Variable: JBCGLOBALDIR............................................................................ 8-2
Variable: JBCIDLEN....................................................................................... 8-3
Variable: JBCLOGNAME............................................................................... 8-3
Variable: JBCOBJECTLIST ........................................................................... 8-3
Variable: JBCPORTNO................................................................................... 8-3
Variable: JBCPRINTER_DEPTH ................................................................... 8-4
Variable: JBCPRINTER_WIDTH................................................................... 8-4
Variable: JBCRELEASEDIR .......................................................................... 8-4
Variable: JBCSCREEN_DEPTH .................................................................... 8-4
Variable: JBCSCREEN_WIDTH .................................................................... 8-4
Variable: JBCSPOOLDIR ............................................................................... 8-5
Variable: JBCTTYNAME ............................................................................... 8-5
Variable: JEDIFILENAME_MD..................................................................... 8-5
Variable: JEDIFILENAME_SYSTEM ........................................................... 8-5
Variable: JEDIFILEPATH .............................................................................. 8-6
Variable: LIBPATH......................................................................................... 8-6
Variable: LD_LIBRARY_PATH .................................................................... 8-6
Variable: PATH ............................................................................................... 8-6
Variable: TERM .............................................................................................. 8-6
Chapter 9 : Migrating to jBASE........................................................................ 9-1
Overview ............................................................................................................... 9-1
Compiling Using your Existing Methodology ................................................. 9-1
Importing Accounts ............................................................................................... 9-3
Moving BASIC to jBC .......................................................................................... 9-4
Migrating BASIC Source Code Files............................................................... 9-4
The totalmake Command ................................................................................. 9-4
Portbas ............................................................................................................. 9-4
Building Makefiles .......................................................................................... 9-5
Maintaining Makefiles ..................................................................................... 9-6
Importing jCL Programs........................................................................................ 9-7
Directory Layouts.................................................................................................. 9-8
Development and Live Environments ................................................................... 9-9
Release Mechanisms to Live and Test Environments ...................................... 9-9
Account Vs User.............................................................................................. 9-9
User Port Numbers ........................................................................................ 9-10
Index .........................................................................................................................1

xi

xii

Using the Manual

Summary of Chapters
1
2

Introduction
jBC

jCL

jQL

List Processing

jBASE Editors

jBASE Commands

Environment Variables

Migrating to jBASE

gives an overview of jBASE.

details the functionality and benefits derived from working with jBC.
Describes the file and directory organisation and outlines the library of
functions available to the application programmer. Also offers some
advice to the jBC programmer that should help you to produce efficient
code.
describes the components of the jCL language and lists the syntax and
usage for each command.
describes the components of the jQL language and lists the syntax and
usage for each command.
describes the list processing capabilities of jBASE and lists the syntax
and usage for each command.
describes the features and functionality of the jED and ED editors.
Particularly useful for programmers.
lists the jBASE commands and indicates where they are documented.
describes the various environment variables that are used with jBASE and
gives details of their usage.
gives details of how to convert applications written in other dialects of
BASIC to jBC and the Open Systems environment.

xiii

Notation Conventions
The manual uses the following conventions when describing command syntax :
BOLD TEXT

Text in this format represents required user input. The exact characters as shown
should be entered at the keyboard.

Italic text

In a syntax specification, italics show parameters that must be entered and supplied by
the user.
Within descriptive text, italics are used to add emphasis, or to show a term that has been
defined elsewhere.

CAPITALS

CAPITALS indicate keywords, file names or constants.

{}

Braces are used to surround optional parameters within command specifications.

...

The use of ellipses indicates a command parameter that can be repeated as many times
as required.

<ENTER>

Capitals surrounded by angled brackets refer to actual keys on the keyboard. A series
of keys inside angled brackets such as <CTRL A>, indicate that the combination of
keys should be pressed simultaneously.

arg | arg

A vertical line separating arguments means that at least one, if not both arguments
must be provided.

code or variable

This style of text represents code or variables.

xiv

Errata and Comments

If you have any comments regarding this manual or wish to report any errors in the documentation, please
document them and send them to the address below:

Technical Publications Department

JAC
599 Maxted Raod
Hemel Hempstead
Hertfordshire HP2 7DX
England
Tel:

+44 (0)1442 235 515

Fax: +44 (0)1442 233 515

email:

[email protected]
[email protected]

Please include your name, company, address, phone and fax numbers, and your email address if
applicable.

xv

Chapter 1: Introduction to jBASE

Introduction to jBASE
jBASE is an application development and database management system that enhances and extends the UNIX
Operating System. jBASE also allows existing applications to be easily migrated from other DBMSs, including
PICK and REALITY.
jBASE was designed to be, and is, Database Independent. jBASE offers built-in Client/Server abilities,
embedded SQL functionality, an easy-to-use Spooler, and an easy-to-use enquiry language. The Application
Language, jBC is a super-set of Dartmouth BASIC and is ideal for developing business applications. The
compiler can optionally produce C or C++ Source code from the original jBC (BASIC) Sources.

Run-Time Components
The run-time components are designed for freedom of choice, efficiency and ease of use.
They consist of:
The jBASE External Device Interface (jEDI), which provides database independence and distributed
processing capabilities;
jBASEs own family of NF2 file systems, namely j1 and j2 files;
The jBASE query language (jQL).

Development Components
The development tools are designed for highly productive development, simple migration and run-time
efficiency of resulting software.
They consist of:
A set of tools for easy migration to jBASE from existing environments;
The jBC Programming Language, which is a compiled language and a superset of Dartmouth BASIC
allowing structured programming. Note that the jbc compiler can be directed to produce C or C++
source code too;
A set of development editors and debugging tools;
The jBASE job control language (jCL).

Administrative Components
Being an enhancement and extension of the UNIX and the Windows family of Operating Systems, jBASE takes
advantage of all the administrative functionality of the host environment. However, there are some extra facilities
provided over and above those of the host environment.
They include:
The jBASE Spooler (jLP)
Utility programs such as jbackup and jrestore

Requirements for Running jBASE

The basic requirement for jBASE is a standard UNIX system running on any hardware. This makes jBASE a
truly Open Systems application development tool, with the resultant code being easily ported across many UNIX
platforms.
jBC applications will run in a UNIX SVR3.2 or later environment without difficulty.
jBASE allows a user to take full advantage of the capabilities of UNIX System V Release 4 environment
(SVR4.x). This offers many advantages over previous versions of the UNIX system. However, it is important to
understand that jBC will produce applications of equal complexity in both environments.

Programmers Reference Manual

1-1

Introduction

The jBASE system has been successfully implemented on Intel, HP, DG, IBM, Digital, Sun, Sequoia and
Motorola 88K UNIX based platforms. Other systems (including Windows) are either in development or will be
implemented as they are required.

Introduction

1-2

Programmers Reference Manual

Chapter 2: jBC

jBC Language Overview

jBC is a UNIX resident programming language supported by the jBASE Database Independent
Management Engine;

jBC can access database files of any UNIX resident, Open Systems database;

jBC is aimed primarily at writing business applications, and contains all the constructs needed to access
and modify files and their data efficiently;

jBC is a sophisticated superset of Dartmouth BASIC supporting structured programming techniques;

jBC is a flexible and user extendible language;

jBC contains the functionality needed to write efficient UNIX applications. It can spawn child processes,
access environment variables and interface to other UNIX programs;

jBC programs can call external functions written in C or jBC. C programs can be made to call functions
written in jBC;

jBC programs can mixed with embedded SQL statements written allowing queries and updates on any
SQL Database;

jBC object code is link compatible with C and so a programmer has the tools of both available to him to
produce the most efficient code for his application;

jBC allows the application programmer working in a UNIX environment to write code without needing
to consider memory management, variable typing or floating point arithmetic corrections: all of which
need to be dealt with when using 'C';

jBC has other advantages over C such as the in-built debugger and easy file i/o;

jBC programs may declare external functions, which are linked into the application by the UNIX linkerloader. This means that jBC offers access to specialised functions written in C or any language that is
link compatible with C;

Programmers Reference Manual

2-1

jBC

Features of jBC

Optional statement labels;

Multiple statements on one line;

Local subroutine calls;

Branching on result of complex value testing;

String handling with variable lengths;

External calls to 'C' libraries;

External subroutine calls;

Direct and indirect calls;

Magnetic tape input and output;

String, number, and date data conversion capability;

File access and update capability for any UNIX resident file, such as j-files or C-ISAM);

File and record level locking capability;

Pattern matching capability;

Capability of processing file records in any format;

Sophisticated jBC debugger;

Ability to EXECUTE any jBASE system or database enquiry command;

The standard UNIX command set is available to manage code libraries;

Support for networking and inter-process communication.

Benefits of Using jBC

jBC

Applications are running on an Open Systems platform;

Applications are very efficient as the execution speed of jBC code is close to that of hand crafted 'C';

Applications are portable between any binary compatible UNIX environment. Changes to the jBC source
code are not required when porting applications to new versions of UNIX, as any UNIX specific code
will have already been implemented by JAC;

Applications integrate easily with other UNIX systems;

Applications benefit from the steady improvements made in compiler optimisation.

Use of jBC offers tremendous productivity improvements over 'C';

The close compatibility with UNIX allows the jBC developer to produce libraries of standard
subroutines or function calls which can be used by any program;

The standard UNIX command set is available to manage code libraries;

Database access is provided to applications through generic read/write/lock statements that divorce the
application from the database itself. Locks are maintained across remote systems and communication
links thus allowing the application programmer to concentrate on the application not the database or its
location;

jBC will import and compile BASIC code from Open Systems RDBMS systems with little or no
modification;

Applications ported from PICK or Reality run as 'C' applications with all the related performance and
seamless inter-operability advantages over running on an emulation type implementation written in C;

Investments in existing BASIC applications and development and programming skills in BASIC are
fully retained;

2-2

Programmers Reference Manual

No need for costly retraining of programmers to 'C'. However, 'C' can also be freely used within the
application system, thus allowing more flexibility;

jBC provides connection to external devices and external databases in a manner that is transparent to
existing applications;

jBC Environment

jBC will run on any standard UNIX system and with any standard shell or editor. An easy to use
jSHELL is also provided.

jBC allows the programmer to choose his working environment to suit. It works equally with the Bourne,
C or Korn shell. Kernel configuration is not required to use the jBC programming environment.

jBC programs can be written using any UNIX editor. A context sensitive screen editor (jED) is provided
that is designed specifically for jBC programmers and jBASE users.

Utilities are supplied to access database files created under jBASE.

The final size of executable code is minimised, and duplication avoided, by sharing external object
libraries between all application programs.

A file or directory may be specified to hold all the jBC source. The finished executables may be held in a
different file or directory if required.

A global user library may be used to hold globally accessible user routines.

jBC Programming

jBC source code may be written using any system editor. Users unfamiliar with UNIX editors may wish
to use the jED editor;

The jBC compiler can be used to produce intermediate object code or a UNIX executable file;

Makefiles can be used to simplify the compilation process, especially if many files are involved. Their
use will also make upgrading and software maintenance an easier task;

If the system allows, use should be made of linked libraries when calling subroutines and functions. This
will reduce the size of the compiled code that would otherwise be produced;

Applications accessing jBASE files should make use of the existing routines held in the /usr/jbc/lib
directory.

jBC Comparisons
With BASIC

Both jBC and BASIC languages are derived from Dartmouth Basic;

jBC is an enhanced variant of BASIC. It contains all the commands and constructs necessary for
compatibility with other versions of BASIC. It also provides full interaction with UNIX system and
database files;

jBC can be quickly modified to retain compatibility with any future enhancements to the BASIC
language or its derivatives;

On a UNIX system, the jBC compiler will produce code that will run many times faster than the same
BASIC code compiled and run on any other UNIX based RDBMS environment;

jBC can access jBASE, C-ISAM, and UNIX files as well as records and files of other databases;

jBC debug facilities are greatly superior to those provided with other versions of BASIC.

With 'C'

The jBC compiler uses all the features of the cc compiler;

The jBC compiler can compile 'C' source and object files, as well as jBC source code;

Programmers Reference Manual

2-3

jBC

Source compilation can be halted at any stage, and the resultant code examined;

External 'C', and jBASE library access is available;

The executables produced by the jBC compiler and cc are identical;

jBC has a sophisticated debugger available as standard;

jBC is able to provide full and easy access to UNIX or any third party database files;

jBC has the tools to provide sophisticated string handling;

jBC handles system signals and events automatically.

File and Directory Organisation

To allow jBC to run on a UNIX system, several directories and files have been set up which ensure the smooth
and efficient use of the jBC programming environment.
All the jBC files are held under the UNIX /usr/jbc directory.
The main body of the jBC program and library files are held in the /usr/jbc directory. This contains all the runtime code, error and library files, as well as default system and terminal set-up limit.
jBC include files are held in the general UNIX directory for these, the /usr/jbc/include directory.
Note that the /usr/jbc directory may be suffixed with a release number on some systems subsequent to release
1.0. However the latest release of the system will always reside in /usr/jbc.
The jBC programming environment is organised as sets of executable programs, libraries and look-up files
allowing the programmer to compile, run and debug jBC applications.
By default, the jBC libraries are held under the /usr directory - as shown below:

/usr
/jbc

/bin

/config /dev

jbcmessages

Fig. 2

/include /lib

/src

/tmp

jBASE Directory Structure

/bin

Contains all the binary executables that make up the jBASE system including the compilers. On
a runtime only system various components (such as the compilers) are missing from here.

/config

This file contains various configuration files for systems such as background processing and the
j-file(s)lock daemon.

/dev

All external devices on the current system are described here.

jbcmessages

This file contains all jBC error messages and may be edited by the user.

/include

Various include files required at compile time are stored here. This directory is not present on a
runtime only system.

/lib

This directory contains all the libraries required for linking executing jBC compiled programs.
Shared or Dynamic libraries are also stored here.

/src

This directory contains any source code files that are distributed with the current jBASE release.
It contains extended user exit support, templates for Makefiles and jEDI interface code.

/tmp

This is a general purpose temporary directory for runtime use.

jBC

2-4

Programmers Reference Manual

jBC Libraries
Shared Libraries
Shared libraries contain code for jBC or C functions that is not linked (joined) to the users jBC program until
runtime. A single system will only ever load this library into memory once and any executing jBC programs will
share it between them.
SVR3.2 Libraries
Under SVR3.2 shared libraries must be constructed with extreme care with all function addresses defined to the
system before their compilation. All jBC libraries on this version of UNIX have been defined as shared (unless
the particular flavour of UNIX does not support shared libraries). However libraries produced by the
programmer to store callable jBC subroutines cannot be defined as shared and each program calling a subroutine
will contain a copy of the subroutine code. This can make for large executable programs on such systems.
SVR4 Libraries
Under SVR4 shared libraries are more commonly referred to as Dynamic Libraries and are at the same time both
simpler to use and more sophisticated. Dynamic Libraries are very easy to produce and information concerning
addressing need not be supplied to the compiler. Hence not only are jBC libraries Dynamic but libraries
produced to hold jBC subroutines will be as well. Large applications sharing many subroutines benefit greatly by
executing on SVR4 systems.
Other Dynamic/Shared Libraries
There are a number of versions of shared and dynamic linking concepts. Where any form of shared library exists
it has been used in the jBASE port to the particular flavour of UNIX.

Programmers Reference Manual

2-5

jBC

jBC Compiler and Runtime

The jbc command will normally produce an executable UNIX file with all stages in between transparent
to the developer;

It is a sophisticated optimising compiler written with UNIX tools designed specifically to write
compilers. The lexical analyser for jBC is written using lex and the parser is written using yacc;

Symbol table management and other supporting functions are written in C, as are the libraries that
support the compiled application. This ensures that the whole system, including any application
produced using jBC, is portable and very efficient;

The jBC compiler is an optimising compiler that minimises the use of memory and temporary
workspace. Unlike some compilers the code produced is neither interpreted or stack based;

The jBC compiler first produces C code, which is then optimised to reduce the number of steps taken to
execute jBC statements. This is then passed through the optimising C compiler. The result is code that is
optimised twice, once in terms of the general application and once at pure assembler level;

The optimised object code produced by the jBC compiler is linked with the jBASE libraries and the
standard C libraries before it finally ends up as an Executable UNIX file;

The application specific code and the jBASE libraries are all written around the concept of shared text
space on UNIX;

jBC runtime code is treated in the same way as any other UNIX executable or C object file.

General Programming Advice

The advice given here is provided as a guide for jBC programmers. Every programming department will have its
own view of procedures and standards but we do recommend that you should read this section, even if you then
decide against the advice given here.
Formatting
The jED editor and the jfb formatting tool contain formatting algorithms that most developers will find
acceptable. Two different formatting methods are available where the CASE construct is concerned as there are
two equally valid formats for this statement.
The default indentation will use four spaces as the indent level and start each line that is not a label at indentation
level 2 (Column 8). However, this may be changed should the internal standards of a particular organisation
differ from this. Labels are formatted to start in the first column of the source line. This gives the general
appearance shown here:
Label:
CRT "The first main line"
IF Variable = 10 THEN
CRT "Variable = 10"
END ELSE
BEGIN CASE
CASE A = 9
CRT "A = 9"
CASE 1
CRT "A is something else"
END CASE
END
LOOP
A = 10
WHILE A DO
A-REPEAT
FOR I = 1 TO 5
CRT I
NEXT I

jBC

2-6

Programmers Reference Manual

The jED editor and the jfb command will also align comments sensibly at a particular column providing that the
source code does not encroach upon this set column.
We recommend that all jBC programs are created and edited via the jED editor. Executing jED with the {b}
option or by entering BION command within jED will automatically turn on context sensitive editing. This
feature will cause automatic indentation of the source code as the programmer types it in. However programmers
may wish to adopt UNIX indentation methods, which rely on tab stops, by using a sophisticated editor such as vi
or emacs. The compiler will accept any ASCII file as input, allowing the programmer to use almost any editor
they wish.

Programmers Reference Manual

2-7

jBC

jfb - jBC Source Code Formatting

The jfb command is used to produce source code listings in a standard format for listing to the terminal or
printer. The format of the command is as follows:
jfb {options} file {file...} {(options)}
or
jfb {options} {DICT} filename {[* | recordkey...]} {(options)}
Each instance of file should be the path and file name of an existing jBC source file including the .b extension.
The various options available are:
Option

Explanation

-A
or (A

Alternate indenting of CASE statements. If A is specified, the

CASE statement will not be indented in relation to the BEGIN
CASE statement.

-C
or (C

Indent comments with the source code rather than placing them
in column 1 of the listing.

-Lnn{,m}
or
(Lnn{,m}

Set the indentation level to nn spaces (default 4), with the initial
indentation level for non labelled code to be m*n spaces (default
m=2).

-Mnn
or(Mnn

Set maximum number of indentations to nn. The default is 10

indentations.

-N or (N

Do wait for keyboard input between pages.

-P or (P

Send output to the current printer queue. (Assumes -N).

-Snn or
(Snn

Set the percentage split of code to comments to nn%. If nn is 60

and the output width is 100 then comments will be aligned at
column 60 on the output device.

-V or (V

Place a + character vertically at each indent level to view indents

more easily.

Options can also be specified after the file list by delimiting with a parenthesis mark in the format jfb file (A,P
For example, to list the file batch.b in sub-directory source to the printer, indenting by four spaces per level and
starting non-labelled code at 8 spaces from the left margin:
jfb -L4,2 -V source/batch.b
Structured Coding
The use of structured code is widely recognised to improve readability and maintenance of code. The jBC code
contains many structured statements that allow the programmer to avoid producing "spaghetti" code. In
particular the LOOP and FOR statements coupled with BREAK and CONTINUE, will avoid the need for the
GOTO statement within a looping construct. The use of CASE statements is also recommended.
The GOTO statement should be avoided at all costs, although there are some valid instances when it may be
useful such as branching to error routines that will never return.
Naming Conventions
The jBC compiler is a case sensitive compiler. All keywords within the language MUST be specified in upper
case. Identifier names, may however be specified in any combination of upper and lower case characters. Over
time we have found that the use of capitalised variable names greatly improves the readability of the code. Thus
we have adopted this as a standard technique. The term capitalisation refers to naming identifiers like this:
FileName; RecordName; StopFlag.

jBC

2-8

Programmers Reference Manual

You will also find that the compiler will not recognise variable names that are reserved words. Therefore the
statement:
CRT = 0
is not allowed. The compiler will point out the usage of keywords as identifiers at compile time. The migration
tools supplied with the system will spot this usage and convert the names to their capitalised form. The above
statement will become:
Crt = 0
Limits and Limitations
jBASE has been designed to avoid imposing arbitrary limits upon the developer or user. Therefore the only
limitations are imposed upon the system by the particular version of UNIX you are using.
For instance the SVR3.2 version of Motorola UNIX does not support the shared library model, meaning that any
executable must contain its own copy of the jBASE functions it calls.
Certain compilers may not be able to optimise very large programs or subroutines and may abort with a message
such as "Optimiser failed, too many labels, -O ignored for program". This is merely a warning and can be
ignored by the application developer.
j1 and j2 files are limited in size to 2GB although there are ways in which this limit can be overcome as far as a
jBC program is concerned. The j3 file system will overcome this limitation.
There are no limits on record size other than that proscribed by the file size. You will find however, that UNIX
imposes limits on the amount of system resources an individual process can control (although these are
configurable by the system administrator). Performance degradation will be seen when handling very large
records in jBC variables. However, very large in this case means of the order of 15MB or more and it is unlikely
that you will wish to manipulate many records of this size.
Some SVR3.2 systems are poor at manipulating archive libraries above a certain size. The chapter Migrating to
jBASE explains some ways to cater for this but in general it is wise to keep archive libraries small (less than
3MB) rather than large, and to split large libraries into smaller ones.

Programmers Reference Manual

2-9

jBC

jBC Compiler
Before starting to compile basic source files, any include items required by the basic source code should be
located. If include files are located in other directories, links should be created.
For example, MAINPROG is a basic source code item with an include statement:
INCLUDE IncludeFile StandardEquates
The IncludeFile is located in a general purpose account, now a directory, called anotherdir.
A link should be created in the application directory to reference the IncludeFile file in the anotherdir
directory. The shell command to create this link is as follows.
ln /home/anotherdir/IncludeFile IncludeFile
This will create a link in the home directory, IncludeFile, to the file, IncludeFile, in the directory, anotherdir.
Alternatively, a Q Pointer in the MD can be used to specify Includefile.
Once all include files references have been processed, the program is ready for compilation. The jBASE
command BASIC should be used to compile the basic source code programs. The BASIC command should only
be executed from the application directory - NOT from an alternate directory making use of the link file. The
application id should also be used when using the BASIC command. The reasons for using the application id and
directory is that the .profile script will have set up the necessary environment variables for the compilation
process and all the permissions will be correct, whereas attempting to compile from another user id or directory
may cause later very confusing problems due to incorrect permissions or pathname assignments. The format of
the BASIC command is detailed below.
BASIC SourceFilename Itemlist (options
The BASIC command uses a sophisticated set of compilation tools to compile and link jBC source code into C
object code. The BASIC command will produce a dollar item, an item with the same name as the source item
prefixed by a $. The dollar item will be placed in the same file as the original source item. The BASIC command
is a front end to the jbc compiler proper which is described in detail in the jBC Compiler and Makefiles chapter
of the Advanced Programmers Reference Manual.

jBC

2-10

Programmers Reference Manual

Cataloging and Running your Programs

The jBASE CATALOG command is used to create UNIX executables and shared libraries from the application
source code. Once you have cataloged your programs, you can run them like any other command on the system.
The RUN command which is sometimes used to execute compiled jBC programs without cataloging them can
still be used but is really only maintained for compatibility. Whenever possible, you should catalog your
programs rather than RUN them.

CATALOG Command
The jBASE CATALOG command should be executed from the application directory rather than using link
names and the application id should be used. The reasons for executing the CATALOG command from the
application directory and application id are that the .profile script will have set up the required environment
variables correctly and that the correct file permission will be used when creating and deleting UNIX
executables and directories. The format of the jBASE CATALOG command is as follows.
CATALOG SourceFilename Itemlist
When first invoked the CATALOG command will create a $HOME/bin directory into which the UNIX
executables will be placed. A $HOME/lib directory will also be created into which any subroutines will be
placed. The lib directory contains a jLibDefinition file, which describes how to build the subroutines into shared
libraries. The entries in the jLibDefinition file are described below:
libname

naming convention for shared object files.

exportname export list of shared objects. Used as cross reference to find subroutine functions.
maxsize

maximum size of a shared object library before creating another.

When the maximum size of a shared library object is reached then a new shared library object will be created by
the CATALOG command. The new shared library objects are named according to the definition of libname and
are numbered sequentially. For example:
libname=lib%a%n.so
where
%a = account or directory name
%n = number in sequence.
If subroutines were cataloged in the user account name, fred then the shared object libraries produced would be
named, libfred0.so libfred1.so libfred2.so and so on.
Note: To guard against libraries being cataloged incorrectly, perhaps under the wrong user account
name, the definition of libname should be changed to libfred%n.so. This will ensure that any shared
objects are created using the proper user account name.
The shared library objects, .so files, contain the UNIX executables for subroutine source code. The shared
library objects are linked at runtime by the jBASE call function, which utilises the dynamic linker programming
interface. The dynamic linker will link shared libraries at the start of program execution time, or when requested
by the jBASE call function. For example, each executable created using the jBASE compiler will be linked with
the jBASE jEDI library functions, libjedi.so, at compilation time. This shared library enables database record
retrieval and update and will be loaded into memory by the dynamic linker when an application executable starts
execution. However the shared library containing any subroutines required by the executing program will only
be loaded into memory when initially requested by the subroutine call. Only one copy of any shared library is
required in memory at any time, thus reducing program memory requirements.
The $HOME/lib directory also contains a directory where all the subroutine objects, .o files, are held. These are
required for making the shared library, .so files.
The $HOME/lib directory also contains an export list, .el file, built by the CATALOG command, which is used
as a cross reference when dynamically linking shared objects at run time.
The main application program executables are placed into the $HOME/bin directory.

Programmers Reference Manual

2-11

jBC

To enable the application executables to be found the $HOME/bin path should be added to the PATH
environment variable.
To enable the executing application to call the correct application subroutines the JBCOBJECTLIST or
LD_LIBRARY_PATH environment variable should be assigned to the application shared library path,
$HOME/lib. If the main application program or any subroutine programs make calls to subroutines in other
directories then the path of the shared library directories should also be added to the JBCOBJECTLIST or
LD_LIBRARY_PATH environment variable.
It is recommended that executables or subroutines of the same name are not available from different directories.
This can make application execution very confusing and is reliant on assigning the lib or bin directories to the
environment variable in the correct sequence. The assignment of the environment variables should be included
and exported in the .profile script file.
Executables and shared library objects can be removed from the bin and lib directories by using the
DECATALOG command.

DECATALOG and DELETE-CATALOG Commands

The DECATALOG and DELETE-CATALOG commands are used to remove the run-time versions of cataloged
jBC programs.
The format of the DECATALOG command is:
DECATALOG SourceFilename ProgramName
The format of the DELETE-CATALOG command is:
DECATALOG ProgramName

RUN Command
The RUN command is used to execute compiled but uncataloged jBC programs. Whenever possible, you should
catalog your programs rather than RUN them - the RUN command is only maintained for compatibility with
older systems.
The format of the RUN command is as follows.
RUN SourceFilename ProgramName (options

jBC

2-12

Programmers Reference Manual

jBC Debugger
The jBC debugger is a fully featured, interactive diagnostic utility that gives the programmer full access to the
program variables and files. It will allow examination of source code, save and restore of debug settings and full
access to system commands from within the debug shell. As such it is a powerful tool for detecting and fixing
errors within jBC source programs. The main features of the debugger are:

Set and delete breakpoints to halt program execution. These can be simple line number breaks or based
upon the result of an evaluated expression.

Set and delete the tracking and display of variable contents.

Display any number of lines from within the current source.

Locate text in the current source.

Examine and set breakpoints in source files other than the current one.

Display and modify the contents of any variable.

Execute a chosen number of source program lines before re-entering debug.

Redirect debugger interaction to another device or terminal.

Save debugger status to a file and execute debugger commands held in a file.

Execute system commands and return to debug.

Entering the Debugger

The jBC debugger will be entered a number of ways:

after invoking a program with the -Jd or -JD options.

after the detection of a run-time error.

after the user sends the intr signal to the program from the terminal.

after the application is sent a kill -16 signal by another process.

after the execution of a DEBUG statement in the jBC code.

after coming to a debug breakpoint previously entered from debug.

Once the debugger is entered, an identification message is displayed and the debug shell prompt is displayed.
The message gives the reason for the program entering into debug, the line number about to be executed, and the
source file name. The final line is the debug prompt, after which the user is expected to enter a debug command.
The following examples show the display after entering the debugger in various ways.
Using the -Jd Option at Runtime
/usr/home/progs > stx -Jd
Option -Jd seen on command line
Source
ST.XFER.b,Line 1, Level 2
jBASE debugger>
A DEBUG Statement in the Program
/usr/home/progs > stx
DEBUG statement seen
Source
ST.XFER.b, Line 39,
jBASE debugger>

Level 2

Using <intr> Key from the User Terminal

Signal 2 seen from signal handler
Line 157, Source ST.XFER.b

Programmers Reference Manual

2-13

jBC

jBASE debugger >

Receiving a kill -16 Command from another Terminal
Signal 16 seen from signal handler
Line 73, Source ST.XFER.b
jBASE debugger >
Run Time Error
For example, when a variable containing a string is used as if it contained a number, the following is seen:
Non-numeric value -- ZERO USED ,
Variable 'XFER.ID', Line 78, Source
jBASE debugger >

ST.XFER.b

Debug Arguments at Run-time

When a jBC source program is executed, there are a number of command arguments that can be passed to the
run-time libraries, some of which relate to the operation of jBC debug. These are as follows:
-Jd

The debugger is entered at the start of the program, immediately prior to executing the first
jBC command.

-JD

The debugger is entered at the start of the program, immediately prior to executing the first
jBC command. The debug session remains active, even if a new program is EXECUTEd or
CHAINed to.

-Jp{:Path...}

This specifies to the debugger where it can find the necessary sources it needs at run time. Path
can comprise multiple jBC filenames or jBC filenames, as long as they are each delimited by a
colon. When the debugger attempts to open the source, it will start looking in the leftmost
filename specified. If this argument is not given, the default is the current directory. This
option can be overridden from the debug prompt using the p command.

-JrDeviceName The debugger output is redirected to device DeviceName rather than standard output. This
allows debug to send its output to a file, pipe or a terminal other than the current one in use by
the program. For example, -Jr/dev/tty8b will redirect output to device tty8b
Note: If the application performs a CHDIR() function, and the debugger needs to access a file in the
'current' directory by default, then it will attempt to access it in the directory specified by the CHDIR()
function and not the one from which the program was executed.
Other debug features are available through the JBCDEBUGGER environment variable. See the Environment
Variables chapter for more details.
Examples
menu -Jd
This command will start up the menu program and enter the debugger before executing the first command with a
message similar to:
Option -Jd seen on command line
Source
MENU.PROCESSOR.b, Line 1, Level 2
jBASE debugger>
Normal debugging operations can now be carried out.
menu -Jd -Jp./invoices:./inv.routines:../src/mainlib
This command executes the menu program and enters debug. Any debug commands requiring reference to the
source, such as w, will then look for it in a directory other than the current one.

jBC

2-14

Programmers Reference Manual

The directories searched are listed after the -Jp option, and they are searched in order starting from the leftmost
directory given. If a required source for the main program or an external subroutine is not in the ./invoices
directory, then the directories ./inv.routines followed by ../src/mainlib will be searched in turn. If the source file
is not found, an error message is returned specifying the source required.
As the executable code and libraries are usually held in separate directories from the original sources, this is a
very useful option.

Debugger Commands
This section details all the commands available to the user from the jBC debug prompt.
References in the Command column to expr refer to an evaluated expression. Expressions are detailed after the
command table. The current file name and current line number are internal debugger variables. On entry to the
debugger these are set at the current program file name and line number about to be executed.
Many of the commands detailed here are not available when a program has been compiled with the limited
debugger. The limited debugger is linked to the program when the -J04 argument is used on the jbc command
line. The -JO4 options is normally only used on production release applications. The ? command will list all
commands available. All commands are available when the full debugger is in use.
Restrictions.
If you have a Command Level or Break/End Restart feature in effect, or the break key is disabled, the available
options are restricted to:
a
q
c
end
o

Abort program
Quit program
Continue (may be allowed, depends on reason debug was entered)
Terminate debugger.
Log off.

Note that there are several ways in which the break key can be disabled. You can use commands such as
INHIBIT-BREAK-KEY or BREAK-KEY-OFF. In these cases, the debugger is never entered. Another way is to
execute a BREAK OFF statement within the program. In this case, the debugger will still be invoked if a runtime error occurs - such as trying to read a record from a non-file variable.
Command List
?
Display a help screen showing all available debug commands and the program status.
>filename
Open and truncate the file filename and send it the current breakpoints and trace table entries. This can be used
in future to replicate the current environment by the use of the < command. Note that you may write debugger
scripts yourself with an editor rather than use the > command.
<filename
Open the file filename, then read and execute each line as if it has been entered at the keyboard. Any current
trace or breakpoint table entries are deleted then replaced by those recorded in filename.
!command
Spawn another process and execute the UNIX or jBASE command. The previous command thus used can also
be recalled and executed by the !! command.
<CTRL D>
Display the next 11 lines of source in the current file.

Programmers Reference Manual

2-15

jBC

nn
Set the current display line to line nn in the current file and then display the line. Note that the program
execution counter remains unchanged, it is only the display pointer that is changed. A command such as s (see
later) will correctly execute the next line in the programmed sequence, not the newly displayed line.
#text
Ignored, and so can be used as a comment line in debugger scripts later executed with the < command.
a{-nn} {mm}
Kills the jBC program and any parent process or program that called it. The program aborts with an exit code of
203, and the kill signal is sent to any parent process. The nn value is used to change the exit code, whilst the mm
value changes the signal number sent with the kill command. Operation of this command can be altered by
setting the Command Level Restart option - see the Systems Housekeeping chapter of the System Administrators
Reference Manual for more details.
b
Display all currently active breakpoints.
b {-t} nn{,file}
Set a breakpoint at line nn in the current file or that specified by the file modifier. If the -t option is specified
then the breakpoint will cause a display of all the trace variables rather than halting the program.
b {-t} varname
This form of the b command will cause the debugger to be entered whenever the contents of the specified
variable are changed.
b {-t} ex1 op ex2 {AND|OR .....}
Set a breakpoint at the line whose value is obtained by performing the operation op on expressions ex1 and ex2.
The operator can be one of eq, !=, <=, LE, and so on. A new operator AE meaning approximately equal is also
available. See later for a full description of expressions. The -t option will cause the debugger to display all the
trace points rather than halting program execution.
c
Continue execution of the program.
d {-tbed} {*nn}
Delete breakpoint and/or trace table entries, and will normally prompt for confirmation. The t and b switches
refer to trace and breakpoints respectively. The * switch deletes all of the specified entries without prompting.
The nn switch deletes the entry nn in the given trace or breakpoint table, also without prompting. The d and e
switches respectively disable or enable the given entry without removing it from the table.
e name
Edit the file specified by name. This file is then the file used by other debug commands such as <CTRL>+D.
end
Synonym for 'quit''.

jBC

2-16

Programmers Reference Manual

g {-g}
The g command displays a complete history of both GOSUB and external subroutine calls. When issued without
options the command will only display information about the current program or subroutine. The -g (global)
option will show a breakdown of the entire application.
f {on|off}
A debug breakpoint is set for a filename change. This break can be set to on or off. If the program is continued
(C command) the debugger will be entered the next time the source file changes.
h {-rs{n}} {nn|on|off }
Displays a history of the source lines executed, and current status of the debugger commands used. The on and
off switches toggle the recording of lines executed, and when on, the nn value gives the number of executed lines
to display (1024 maximum). The -r switch displays in reverse order, and -s{n} shows n source lines.

l {-acf{nn}} text
Locate the string text in the current file. The switches used are: a to look for every occurrence; c to make the
search case insensitive; nn to limit the search to the next nn lines; f to start the search from the start of the file.
The command l/ will execute the previous locate.
m
Displays the current memory status. Shows space allocated by the function malloc().
n {nn}
Displays the next nn lines of source from the current file, which is automatically loaded by the debugger if the p
command has been used or it resides in the current working directory.
off
Enter o or off to log off. If you enter off (or OFF), the effect is immediate. If you enter o (or O), you will be
prompted for confirmation. The same restrictions apply as for the OFF command; if there are non-jBASE
programs active, OFF will only terminate jBASE programs until it encounters the first non-jBASE program probably the login shell..
p {pathlist}
Defines the list of directories and pathnames (delimited by :) that the debugger will then search to find source
codes. p without a pathlist displays the current Path.
q {nn}
Quit the program. nn is the termination status returned to any calling program.
r device
The debugger will take all input from, and send all output to, the specified device. Note that if the device is
another terminal (or Xterm shell), that you will need to prevent the target shell from interfering with the input
stream by issuing the sleep command to it. A large value should be used or the sleep should be issued
repeatedly in a loop.
s {-t{m}d} {nn}
Continue execution of jBC code in single line steps before returning to debug. The value nn changes the number
of lines executed before returning to debug. The -t switch is used to display the trace table after every line
executed, rather than wait for entry to debug. The d switch sets a delay before executing each line of code. m is
used to set the delay in seconds (default is 5 deci-seconds).

Programmers Reference Manual

2-17

jBC

t
Display the current trace table.
t {-fg} expr
Add the value specified by expr to the trace table. When debug is entered, all the values in the table are
displayed. The f switch is used to fully evaluate expr, whilst the g switch extends the display of expr to all levels.

v {-gmsrv} {expr}
Evaluate expr and display the result. The effects of the switches are: g to extend the display of expr to all data
areas. m to allow variable modification within expr. When a variable is modified with the m option binary
characters may be entered using the octal sequence \nnn. The sequence \010 would therefore be replaced by
CHAR(8) in the modified variable. The sequence \\ evaluates to the single character \ and a sequence such as \x
evaluates to the single character x (i.e. the \ will be lost).
w nn
Display a window of source code. The default is 9 lines with 3 before and after the current one. The value nn is
used to change this parameter.
Debugger Redirection and Pipes
The debugger provides the ability to redirect the results of its internal command set to a UNIX file or through a
pipe to a UNIX command. This is a very powerful feature of the debugger. This is done in the standard UNIX
manner.
The following commands allow this feature:
v

Display Variable(s)

Display History Trace

Display Breakpoints

Display Trace Table

Here are some examples of this feature:

v | pg

# Pipe through the pg filter

v X<3> | hd

# Show field 3 in hex mode

t Varx >> VarxTrace

s -t 999

# Set trace for Varx (redirect saved)

# Assuming trace above, each step will
# display the value of Varx and append
# the output to file VarxTrace

t > tracetable

# redirect trace points output to file

v Record > file

# Display variable contents to a file

A short practice session with this feature will show you the enormous power of this feature.
Simple Command Examples
Example 1
jBASE debugger> t NEXT.ID
t 1 :
NEXT.ID
The variable NEXT.ID has been put into the trace table and the debugger has verified the entry. Whenever the
program goes into debug during this session, the variable contents will be displayed.

jBC

2-18

Programmers Reference Manual

Example 2
jBASE debugger> w1
Source changed to /usr/jim/BP/ST.XFER.b
0001 * STOCK TRANSFER PROGRAM *
The source code window is set to show just one line of code. The current program line is highlighted.
Example 3
jBASE debugger> s 5
Single step count exhausted
Source ST.XFER.b ,Line 5, Level 2
NEXT.ID
:
(NULL)
This command executes the next five program lines before re-entering debug to display a status message and the
traced variable contents. If any instruction is encountered that prints to the terminal screen, then this will do so
as normal, and the above debug output is then written on the following line.
Example 4
jBASE debugger> b 40
0040
20
* MAIN INPUT
b 0 : 40, ST.XFER.b

SCREEN

A breakpoint is set so that program execution halts and debug is entered at line 40. The debugger displays the
line in the source and shows the number of the breakpoint set; in this case breakpoint zero.
Example 5
jBASE debugger> d
t0 : s2 - delete (Y/N)
n
t1 : NEXT.ID - delete (Y/N)
n
b0 : 40 , ST.XFER.b
- delete (Y/N)

This command is used to delete trace and breakpoint table entries. When used in the simplest form as shown, the
debugger lists each trace table and breakpoint table entry in turn, and prompts for deletion. If the response
entered is no as above, then the next entry is displayed. If the response is Y to delete, then the debugger responds
with a message similar to:
t1 : \NEXT.ID - deleted
before presenting the next entry for deletion.
jBASE debugger>d -b 0
b0 : 40 , ST.XFER.b
- deleted
The command used in this form has deleted the breakpoint b0 from the table. Note that no prompt is given
before deletion.
jBASE debugger>d*
The trace table and breakpoint table are deleted, without the user being further prompted.
Example 6
jBASE debugger>>stxfermb.dbg
The current trace table and breakpoint table entries together with the execution count set, and any comments are
written to the stxfermb.dbg file in the current directory. The file is created if it doesn't exist but if it does, the
previous contents are overwritten.

Programmers Reference Manual

2-19

jBC

Example 7
jBASE debugger>! cat stxfermb.dbg
d *
p .
t s2
t NEXT.ID
b 40 , ST.XFER.b
h OFF
jBASE debugger>
The command above spawns a shell command to list the contents of the stxfermb.dbg file, which was created in
the previous example. When completed, control is passed back to the debugger.
Example 8
jBASE debugger>d -tb*
t0 : s2
- deleted
b1 : NEXT.ID
- deleted
b0 : 40 , ST.XFER.b
- deleted
jBASE debugger>b
jBASE debugger>t
jBASE debugger>
The command deletes the trace table entries (t) and the breakpoint entries (b). The * option denotes that all
entries are to be deleted and no prompt is given.
The following b and t commands just return the debug prompt to show that the breakpoint and trace tables are
empty.
Example 9
jBASE debugger>< stxfermb.dbg
d *
p .
Source path :.
t s2
t0 : s2
t NEXT.ID
t1 : NEXT.ID
b 40 , ST.XFER.b
0040
20
* MAIN INPUT SCREEN
b0 : 40 , ST.XFER.b
h OFF
History trace turned OFF
jBASE debugger>

The above command takes the contents of the stxfermb.dbg file and executes each debug command on screen
one after the other displaying the result. The final outcome is that all of the trace and breakpoint entries
previously saved to the file are reinstated.
Example 10
jBASE debugger> b
b0 : 40 , ST.XFER.b
jBASE debugger> t
t0 :
s2
t1 : NEXT.ID
The b and t commands display the trace and breakpoint table contents.

jBC

2-20

Programmers Reference Manual

Example 11
jBASE debugger> d -tb*
t0 : s2
- deleted
t1 : NEXT.ID
- deleted
b0 : 40 , ST.XFER.b
- deleted
jBASE debugger> t FORM
t1 : FORM
jBASE debugger> b RECORDCODE = 10
b0 : RECORDCODE = 10
In the above example the trace and breakpoint tables are cleared using the d -tb* command. The variable FORM
is then set as a traced variable and a breakpoint is set, which will trap to debug when the variable
RECORDCODE has a value of 10.
Example 12
jBASE debugger> s
008 IF A = 45 THEN
009
FORM = "A string"
010
VAR2 = "Another string"
FORM
: (NULL)
The command is given to execute one line of the program before re-entering debug. The variable FORM is in the
trace table, so its contents are automatically displayed on re-entry. The line number given is the position of the
counter and shows the program line number following the one just executed.
Example 13
jBASE debugger> s
Source ST.XFER.b , Line 10 ,
FORM
: A String

Level 2

Another line of code has just been executed, this time it was line 9 and the program execution counter is now
pointing to line 10.
Example 14
jBASE debugger> m
Memory utilisation
Free space : Small blocks 10400,
Ordinary blocks 6796,
Total 17196
Used space : Small blocks 400,
Ordinary blocks 44168,
Total 44568
The system memory allocation is displayed on screen.
Example 15
jBASE debugger> a -9 111
Signal 9 sent to parent process
73
jBASE debugger termination , exit code = 111
Program

'stx'

hangup

line dropped

Welcome to UNIX
login
:
The a command is used to halt program execution with an error code of 111. In addition, signal 9 is sent to the
parent process. This could be the calling menu driver program, but in this case, as the program was started
directly from the shell, the effect is to log the user off.

Programmers Reference Manual

2-21

jBC

Explanation of Complex Commands

Modifying Trace and Breakpoint Tables
d {-bdet} {nn|*}
-b
refers the command to the breakpoint table only
-d
disable or un-set the table entry referred to
-e
re-enable the table entry referred to
-t
refers the command to the trace-variable table only
nn
the trace or breakpoint entry number to delete, enable or disable
*
refers to all the trace or breakpoint entries
This command is used to delete entries in the variable trace table and the breakpoint table. Unless the * switch is
used, table entries can only be deleted one at a time.
Used on its own, this command lists each variable in the trace table and each entry in the breakpoint table in
turn, and prompts the user for deletion.
d -t
The command deletes all the entries in the variable trace table. This is done immediately without asking for
confirmation.
d -b
The command deletes all the entries in the breakpoint table. This is done immediately without asking for
confirmation.
d -bd
The d switch is used to disable the entries referred to. In this case, all of the breakpoints are disabled. As a result
the execution of the code will continue as if there were no breakpoints set. The complementary e switch can be
used to re-enable the entries.
d *
This deletes all trace and breakpoint table entries without asking for confirmation. Care should be taken with
this, as the system generated t0 entry is also deleted.
d -t 4
This command deletes the fourth entry, t4, in the variable trace table. No confirmation is asked for, and the later
entries do not shuffle up the table, i.e. entry t5 will remain as t5.
d -b 2
This deletes the second entry in the breakpoint table. No confirmation is asked for.
d -b *
This will delete all the breakpoint table entries without asking for confirmation.
Execution History
h {-rs{n}}{nn|on|off}
-r
display lines in reverse order
-s{n}
display n lines of source (default is 1).
nn
limit the history buffer to nn lines of source
on|off toggle the saving of source lines executed
This command keeps track of the source command lines executed during a debug session. The last 1024 lines
are held in a circular buffer, and when full, the most recent command line displaces the oldest. It can be toggled
on or off, and it is normally switched off by default. The command and switches have no effect unless activated
by switching on.
Commands executed from subroutines and CHAINed programs will also be displayed.
h on
This will switch on the command line audit, and every line of code subsequently executed during the debug
session will be logged for reference, until the command is switched off or the debug session ends. The following
commands assume the command line history is switched on.

jBC

2-22

Programmers Reference Manual

h 20
This sets the number of lines of code to display at 20 lines. The default, and maximum value is 1024.
h
Used in its simplest form, the command displays all the entries in the buffer to the maximum number set.
h -s3
This displays the last three lines of code executed.
h -rs10
The last 10 lines of code executed are displayed in reverse order, i.e. the command last executed is shown first.
h off
This switches off the history trace.
Locating Strings
l{-acf}{nn}text
-a show all occurrences (defaults to the first occurrence)
-c ignore the case of any text
-f start the search from the first line of the source
-nn limit the search to the next nn lines of source
text

text to locate

This command locates text in the source file currently being executed and displays the line or lines of code
containing it. The file to be searched may be changed by using other debug commands such as e.
l Heading
Used in its simplest form, the command will search the source from the current line position, to the end of the
file, for the first occurrence of the text "Heading". If an exact match is found, then the line is displayed.
l -c Heading
The -c switch is used to ignore the case of the text. In this case, the first line found with the "Heading" text in any
variety of upper and lower case letters will be displayed.
l -a NAME
The -a switch is used to locate and display ALL the source lines containing the text "NAME" in upper case
letters only.
l -ac name
This command will display all lines of source code that contain the text name, with the characters being in any
combination of upper or lower case letters.
l -a22 NAME
The characters NAME will be searched for, and if located in the next 22 lines starting from the current one, each
line where it is found will be displayed.
l -f /usr/tutor/BP/INVOICE.b NAME
The -f switch is used to search from the beginning and display the first line found containing the characters
NAME from the file INVOICE.b held in the /usr/tutor/BP directory.
l -acf ./PAYMENTS.b money
The most complex form of the command as shown will search the PAYMENTS.b source, held in the current
directory, and display every line from it that has the text money in any variation of upper or lower case letters.

Programmers Reference Manual

2-23

jBC

Execution - Single Stepping

s{-tcgd{n}}{nn}
-t

display trace table after each source line executed

-c

only count the lines of source in the same CALL level

-g

only count the lines of source in the same GOSUB level

-d{n} enter a delay in increments of 100 milliseconds between executing lines of source. This is incremented
by the n value entered.
nn

execute the next nn lines of source before re-entering debug

This command is used to execute the program in steps and to re-enter debug after the execution of a given
number of lines of code. Traced variables are displayed after debug is re-entered, and any screen display within
the executed code is shown as normal.
s
The simplest form of the command executes the next line of the code and then re-enters debug.
s -t
The next line of code is executed and the contents of all entries in the trace table are shown.
s -t4
The next four lines of code are executed displaying the trace table entries before re-entering debug.
s 20
This command executes the next 20 lines of code before re-entering debug.
s -td5 200
The command executes the next 200 lines of code. The -d switch sets a delay in increments of 100 milliseconds
between each line executed. The 5 denotes that a 500 millisecond, or half second delay is set before executing
the next line. The default value is 1, or 100 milliseconds. The -t switch ensures that the trace commands are
shown after the execution of every line.
While this process is continuing, debug can be entered by breaking into the program as normal. This is a very
useful command to use when a run-time error occurs in a program, and the area of code responsible needs to be
found quickly.
With the -d switch set, it is also possible to speed up or slow down the execution of the code if the initial value
chosen is too fast or slow. This is done by entering a number from the keyboard in the range 0-9, which alters the
delay to the given number of 100 milliseconds increments.
s -d3t 500
The command will execute the next 500 lines of code with a delay factor of 300 milliseconds between each line.
This speed of execution can be increased or decreased by pressing the numbers 0-9 on the keyboard during
execution. In addition to this, the -t switch means that the contents of the variables trace table will be displayed
after EVERY line of code executed.
Display Variable
V{-gvmrs}
V ANS
The simplest form of the command will display the contents of the variable next to the variable name, in this case
ANS. This will only produce a display if the source is at level 1, or in the home directory. If the variable has not
been assigned, the value (NULL) is displayed. If the value assigned happens to be null, however, then a blank
(null) will be displayed next to the variable name.

jBC

2-24

Programmers Reference Manual

v -g ANS
If the variable in question resides in a different data area to the local level (COMMON or NAMED COMMON),
then the -g switch should be used to display the variable contents. This extends the display of the variable to data
levels, and is particularly useful when executing a subroutine in a sub-directory or library.
v -m ANS
The -m switch displays the variable and contents, but in addition allows the user to modify the contents. An
equal sign is shown after the variable contents, and any characters or numbers entered followed by a carriage
return are taken to be the new value of the variable. Entering a carriage return leaves the variable contents
unchanged. The character sequence \nnn is replaced by the binary character defined by the octal number nnn.
Therefore the sequence \376 would be replaced by a field mark.
v -gv ANS
This command displays the value held in variable ANS no matter what the current level of the source. In
addition, the -v switch shows the type of variable (string or numeric), its memory location, and size.
v -r NAME
This command displays the contents of the variable NAME at the start of the next line. The -r switch provides a
raw character view of the variable name and value.
v -s NAME
The -s switch shows a short view of the variable being the first 128 bytes.
The * and ? characters can also be used within the variable name as wild card characters. The ? denoting a single
occurrence of any character, and the * denoting any number of occurrences of any character.
Examples:
v A*

displays all variables beginning with the letter A.

v A???

displays all four letter variables beginning with the letter A.

v *-INV

displays all variables ending with the characters -INV.

v *ENP*

displays all variables with the characters ENP within their name.

v LIS(2,*) displays every element in the second row of the dimensioned array LIS.
v RCD(*,*) displays every element of the two dimensional array RCD.

Programmers Reference Manual

2-25

jBC

Debugger Symbol Tables

The jBC compiler produces debugging symbol tables for use by the debugger at runtime. These symbol tables
are produced for each data area in the program. Issuing the command v -g will display the value of every symbol
at every data level within the program. There are three types of data area within a jBC program:
Local Data Areas
Local data areas have scope only within the current source file you are debugging. This will either be the
variables used within the main (calling) program or the variables assigned in the current subroutine. By default
the v command will only operate on the current local data area. The g option will cause the scope of the v
command to be extended across all known data areas.
Global Common Area
The Global Common area contains all the variables that were declared to the compiler using the COMMON
statement without naming the common area.
Named Common Areas
There may be many instances of Named Common Data areas within a single executable. Each area maps directly
to the named common definitions within your programs. Therefore a statement such as:
COMMON /JIM/ A,B,C
will produce a named common data area called JIM for the debugger to use.
Note: If your program contains the same variable name in both local and global common areas the
debugger will operate on each instance of the name in turn.

jBC

2-26

Programmers Reference Manual

jBC Language Reference

This section details all the commands and functions available in the jBC language, together with their command
syntax.
It starts with a description of the language constructs, and how to make use of the features to build an
application. This is followed by detailed descriptions of the jBC commands and functions in alphabetical order.
If you are new to jBC, BASIC or related languages, you should study the language constructs first, before
attempting to write any code. If you are an experienced programmer, you may still find the descriptions of the
language constructs useful. They will certainly help you to identify any elements of the language that may differ
from the other versions of BASIC with which you are familiar.
The jBC commands topic is designed to enable you to look up command syntax quickly. Examples are also
provided to illustrate the usage of each command.

Syntactical Elements
argument

A value or variable passed to a procedure or function at the

time of execution.

constant

A value that does not change throughout the program.

expression

A component part of a program that defines the computation

of a value.

function

A function is a program unit in the C or jBC language. It is a

section of code that can be passed values and may return a
value.

identifier

A string of characters used to identify or name a program

element that can be a variable, function statement or a higher
level unit of the program.

label

A numeric or alphanumeric identifier associated with a line or

statement in the program, and used to refer to it from another
section of the program.

operand

A quantity on which a mathematical or logical operation is

performed.

operator

An entity that can be applied to one or more

operands to generate a result or resultant.

parameter

This refers to data passed to a function, subroutine or

procedure.

resultant

The value output as a result of the action of a function,

operator, expression or procedure upon given data.

statement

A unit with which a program is constructed.

subroutine

A self enclosed set of program statements that are not part of

the main program flow. Program execution control is
transferred to it and only on completion does control pass
back to the main program body.

value

A string of numeric, alphabetic or alphanumeric characters

representing a quantity, data or information.

variable

A string of characters used to identify a changeable value

stored within the computer.

Programmers Reference Manual

2-27

values or

jBC

Data Records
Data is the form in which information is stored on a computer. The data stored, with its correct context, will
provide the user with a particular piece of information.
Variables
A variable is a representation of data. The data stored in a variable can be either a string or a numeric, which can
change dynamically during a program.
Strings can be of any size including the NULL string of 0 bytes in length.
In many systems variables are "typed", I.E. It can only hold a certain type of data. The jBC language uses
"typeless" variables, allowing any kind of data to be stored within them. In addition, there are no limitations on
what may be stored in a byte within a variable. The full range of 8 bit values 0x00 to 0xFF may stored within
variables.
There is no limit to the number of variables that can exist within a jBC program.
A variable name identifies the variable and can be contain almost any sequence of ASCII characters, starting
with an alphabetic, apart from spaces, commas, underscores, hyphens and mathematical operators.
A jBC reserved word cannot be used as a variable name and the compiler will signal an error condition if it
detects the illegal use of a keyword.
Constants
A constant is similar to a variable except that it holds a value that remains unchanged throughout the execution
of a program.
The value of a constant may be either of a numeric or a literal string enclosed in quotation marks.
A string constant must be enclosed in single or double quotation marks, aString or the '/' , /aString/character.
Any of the delimiters will be included as part of the constant if the whole constant is enclosed between a
different delimiter.
Examples
EQUATE PI TO 3.14159265359
Sets the value of PI to 3.14159265359

Assigning Variables
An assignment statement is used to allocate a value to a variable. The value assigned can be a number, literal
string or any valid expression.
Syntax
variable = expression
variable is the reference that will be used within the program to access the expression assigned to it. The value
of expression is stored in memory and will be accessed directly whenever variable is referenced.
If during the execution of a jBC program, a variable is encountered which has not been properly assigned, then a
default value of zero is assigned to it, the debugger is entered, and an error message is displayed on the terminal:
Invalid or un-initialised variable -- ZERO used
VAR varname, Line lineno, Source filename
Examples
1.

Number = 250
assigns the value 250 to variable Number.

2. Sum = 27 + 31 + 19

jBC

2-28

Programmers Reference Manual

will evaluate the expression 27+31+19 and assign it to the variable Sum. The same result could be
obtained
by
the
statement:
Sum = 77, and in fact the compiler will evaluate this at compile time.
3. Percent = (Number / Sum) * 100
shows that other variables can be part of the expression to be evaluated.
4. Name = "Jim"
assigns the string Jim to the variable Name.

Reserved Words
Reserved words are words that cannot be used within a jBC program as an identifier, variable name, subroutine
labels or statement labels. The use of a reserved word will be shown when the program is compiled, and
compilation will fail.
jBC reserved words are :
ABORT
ABS
ALPHA
AND
ASCII
ASSIGNED
AT
BEGIN
BITCHANGE
BITCHECK
BITLOAD
BITRESET
BITSET
BREAK
BY
CALL
CAPTURING
CASE
CHAIN
CHANGE
CHAR
CHDIR
CHECKSUM
CLEAR
CLEARFILE
CLOSE
COL1
COL2
COLLECTDATA

COMMON
CONTINUE
CONVERT
COS
COUNT

CRT
DATA
DATE
DCOUNT
DEBUG
DEFC
DEL
DELETE
DELETELIST
DIM
DIR
DO
DTX
EBCDIC
ECHO
ELSE
END
ENTER
EQ
EQU
EQUATE
EXECUTE
EXIT
EXP
EXTRACT
FIELD
FIND
FINDSTR
FLOAT
FOOTING
FOR
FROM
FUNCTION
GE

Programmers Reference Manual

GETCWD
GETENV
GETLIST
GO
GOSUB
GOTO
GROUP
GT
HEADING
ICONV
IF
IN
INDEX
INPUT
INPUTCLEAR
INPUTERR
INPUTNULL
INPUTTRAP
INSERT
INT
IOCTL
LE
LEN
LN
LOCATE
LOCK
LOCKED
LOOP
LT
MAT
MATBUILD
MATCHES
MATPARSE
MATREAD

MATREADU
MATVAR
MATWRITE
MATWRITEU
MOD
NE
NEXT
NOT
NULL
NUM
OCONV
OFF
ON
OPEN
OR
OUT
PAGE
PASSDATA
PASSLIST
PERFORM
PERROR
PRECISION
PRINT
PRINTER
PRINTERR
PROCREAD
PROCWRITE
PROGRAM
PROMPT
PUTENV
PWR
READ
READLIST
READNEXT

READP
READPU
READT
READU
READV
READVU
REGEXP
RELEASE
REM
REMOVE
REPEAT
REPLACE
RETURN
REWIND
RND
RQM
RTNDATA
RTNLIST
SELECT
SENTENCE
SEQ
SETTING
SIN
SLEEP
SORT
SOUNDEX
SPACE
SQRT
STEP
STOP
STR
SUB
SUBROUTINE
SYNC

2-29

SYSTEM
TAN
THEN
TIME
TIMEDATE
TO
TRANSABORT
TRANSEND
TRANSQUERY
TRANSTART
TRIM
TRIMB
TRIMF
UNASSIGNED
UNLOCK
UNTIL
USING
VAR
WEOF
WHILE
WITH
WRITE
WRITELIST
WRITEP
WRITEPU
WRITET
WRITEU
WRITEV
WRITEVU
XTD

jBC

Arithmetic Expressions
An arithmetic expression consists of one or more numeric variables, constants or intrinsic functions operated
upon by arithmetic operators.
Arithmetic Operator Precedence
Operator precedence describes to the compiler what order a complex expression should be evaluated in. For
instance multiplication is performed before addition in a statement such as: Var = 8 + 8 * 2
When an operator is left associative its arguments are in the same order as the standard addition operator. This
means its arguments are picked from the left towards the right. A right associative operator takes its arguments
reading right to left. An example of a right associative operator is ++, which increments the variable to its right
in the statement Var = A++. The entire precedence of jBC operators is shown below. The highest precedence
is 1.
Operator

Operation

Precedence

()

Expression in parentheses

left

++ --

Increment and Decrement

right

Exponential

left

*/

Multiplication and division

left

+-

Addition and subtraction

left

A "L#2"

Format string

*1

Concatenation

left

><

Relational operators

left

=#

Equivalence

left

AND

Logical AND

10

left

OR

Logical OR

11

left

+= -=

Assignment

12

right

Expression Evaluation
Expressions are evaluated according to the precedence of their operators but if an expression contains two
operands with the same precedence the expression to the left is evaluated first.
Expressions enclosed in parentheses are evaluated first and then treated as a single expression. Within the
parentheses, normal operator precedence applies.
Where parentheses are nested, then evaluation begins with the innermost parenthesised expression, followed by
the others in turn.
Examples
12+4+16/4+36/9

evaluates to

24

6*8/12-3*2^4+"7"

evaluates to

-37

(2^3+1)/(27/(9/3))

evaluates to

String formatting does not have an operator as such but is implied by its context. This rather unsatisfactory situation is forced upon jBC in order to maintain compatibility with older dialects of the
language. It is a non associative operator, which means it may not be combined with itself.

jBC

2-30

Programmers Reference Manual

Numeric Strings
A string can be used as part of an arithmetic expression as long as it only contains numeric characters, and is not
null. If a variable is used as part of an expression but at run time it contains data that cannot be converted into a
number, then the program will drop into the debugger and issue an error message.
Logical Operators
Logical operators are used to perform Boolean tests on relational or arithmetical expressions.
The logical operators available in jBC are:
AND &

are used to perform a logical AND

OR

are used to perform a logical OR

A logical expression operates on the outcome result being TRUE or FALSE.

An expression that evaluates to be zero or NULL is considered FALSE, whilst all other outcomes are considered
to be TRUE.
Logical operators have lowest precedence in any expression, and so any relational or arithmetic operation is
performed first when used in a logical expression.
The result of a logical operation can be summarised:
Operation
X AND Y

X OR Y

Result
TRUE

if X is true and Y is true.

FALSE

if X is false, or Y is false.

TRUE

if X is true or Y is true.

FALSE

if both X and Y are false.

The NOT function can be used to invert the result of the expression.
Pre and Post Increment Operators
jBASE allows the use of pre and post increment operators with variables in a similar manner to the C language.
This allows the use of a statement such as:
Var++
This will increment Var by one. The operator -- decrements a variable by one.
The ++ and -- operators may also be used within expressions, where they perform slightly different operations
dependant on where the are placed in relation to the variable. If the ++ (or --) operator is placed before the
variable the variable will be incremented (decremented) before its value is used in the expression. If the operator
is placed after the variable then value of the variable will be used in the expression and incremented or
decremented only AFTER this.
So:
A= 5; CRT ++A

Will display 6

A= 5; CRT A++

Will display 5

This can simplify the coding of iterative loops considerably.

Programmers Reference Manual

2-31

jBC

Strings and String Operations

A string is a set of characters that may be numeric, alphabetic or alphanumeric (a mixture of numeric and
alphabetic).
String Expressions
Strings may be referred to or built up as a string expression, which could be one of:
variable:

A = "abcd1234"

constant:

"ABCD1234"

Concatenation:

"ABCD":"1234"

substring:

A [5,4] (evaluates to 1234)

String Concatenation
Data strings are concatenated by using the CAT operator. The CAT and ':' operators are functionality equivalent.
Concatenation of two strings appends the second string to the first. Concatenation of a series of strings is done in
order from left to right, and parentheses may be used to make a particular operation take precedence.
Substring Extraction and Assignment
Substring extraction takes out part of a string and assignment allocates that part to a variable or expression or as
a value.
The original string can be a variable, dynamic array or dimensioned array, and the syntax used differs
accordingly.
General String
S[start#,extract#] = expression
S is the original string variable, and start# gives the starting character position, whilst extract# gives the number
of characters to extract from the string.
E.g.

A="abcdef" ;

X=A[3,2] assigns characters cd to X

Dynamic Array
S{<{field#{,value#{,subval#}}}>}{[start#,extract#]}=expr
S is the original dynamic array. If referenced, field#, value# and subval# refer to the array's field, value and
subvalue position respectively, whilst start# gives the starting character position in the array element, and
extract# gives the number of characters to extract from it.
E.g. D001<2,3>[3,2] will extract the third and fourth characters from the third value in the second field of the
file record D001. If D001 holds 'GE123^F]123]ABCDEF^29' then the characters CD will be extracted and
assigned.
Dimensioned Array
S(row#{,col#}){<{field#{,value#{,subval#}}}>}
{[start#,extract#]}=expr
S is the original dimensioned array. If referenced, row#, and col# refer to the array's row and column position
respectively. If referenced, field#, value# and subval# refer to the array's field, value and subvalue position
respectively, whilst start# gives the starting character position in the array element, and extract# gives the
number of characters to extract from it.

jBC

2-32

Programmers Reference Manual

Using Negative Numbers

Negative numbers can be used as either the start or extract values in the expression. Specifying a negative
number for the start of the substring will start the extraction those many characters from the end of the string.
Therefore S[-1, 1] will return the last character in the string. Specifying a negative number for the extract value
will extract up to and INCLUDING that number of characters from the end of the string. The following
examples illustrate this:
With

S="1234567890"

CRT S[-1, 1]

displays

"0"

CRT S[-3, 2]

displays

"89"

CRT S[ 2,-2]

displays

"23456789"

CRT S[-3,-2]

displays

"89"

Relational Expressions
A relational expression compares values or expression resultants to provide an outcome of true (1) or false (0). It
consists of a relational operator applied to a pair of literal or arithmetic expressions.
RELATIONAL OPERATORS
Symbol

Operation

=
EQ
>
GT
<
LT
>=
GE
<=
LE
# < > NE
MATCH(ES)

Equal to
Greater than
Less than
Greater than or equal to
Less than or equal to
Not equal to
To use pattern matching

Relational operators have a lower precedence than arithmetic and string operators, and so are performed after
these within a complex expression.
An arithmetic relational expression consists of two numerics or numeric expressions separated by a relational
operator.
All other combinations of a pair of string or numerics within a relational expression are treated as a string
relational expression. In this case, numerics are treated as string values.
The null string as part of a relational expression is treated as being less than zero.

Program Layout
Blank Lines
A blank line within the jBC source code is one where no characters appear apart from the carriage-return,
linefeed continuation characters.
Whitespace
Whitespace characters are used to separate words, commands and statements on a program line. It can be entered
using the SPACE BAR or TAB KEY.
Presentation
The presentation of source code can greatly improve the appearance and readability of a program.
Recommended programming style is shown in the Programming Advice section of the jBC Language Overview
chapter of this manual.
Blank lines in the source program are ignored by the jBC compiler.
Spaces on a source program line are also ignored by the compiler unless they are part of a literal string.

Programmers Reference Manual

2-33

jBC

This means that blank lines and spaces can be used to freely format the source code, making it more presentable.
Example
! Example of formatted code
CrtJim:

;* CRT subroutine

CRT "Hello Jim"

IF

;* Display the message

Day = 14 AND Month = 7

CRT "Happy Birthday!"
CRT "29 Again!"

END
RETURN

THEN ;* Special?
;* Greetings
;* Hmmm!

;* To caller

Comments and Comment Lines

A comment or comment line has no effect upon the execution of a jBC program, and may appear anywhere
within it.
Comments may (and should) be used freely in a program to clarify an operation or to identify a particular part of
the code.
Execution
A comment should start with one of the following tokens:
REM !

The comment character should be placed at the start of a line or statement and is ignored by the jBC compiler.
The special comment line !! is used in conjunction with the jfb listing program. When the program is listed
using jfb the !! comment will cause a page throw to be inserted in the listing. This can be useful for hard copy
listings as it enhances the presentation of the code.
Example
REM This part of the code is to overcome
*
the problem we have with different terminal
*
types.
!

START OF MAIN PROCESSING

NAME = RECORD<4,2>

;* Get name from record

Line Continuation
It is possible to continue jBC statement sequences or comments over more than one line.
This is done by using the \ character or the ... ellipsis sequence at the end of a line. The line is then seen as one
continuous line by the compiler. This is useful for formatting code lines that are hard to read on a single line.

Statements and Statement Labels

A jBC statement is an entity or command that can be sequenced with other statements to build up an application
program.
Statements normally refer to a single operation and so are usually kept on a single line.
Several statements, however, may be placed on the same line, and where this is done, each statement must be
separated from the next by a semicolon character.
jBC statements or program lines can begin with an optional label. This is used to allow the statement or line to
be referenced from another part of the program.

jBC

2-34

Programmers Reference Manual

Labels may be numeric or alphanumeric, but an alphanumeric label at the start of a line must end with a colon so
that the system will recognise it. Reference to an alphanumeric label within the program does not use the colon
as part of the label.

Program Files
Applications written with the jBC language would generally be composed of three distinct parts:
Source Code
Run-time Executable Code
Libraries containing common functions and subroutines

Formatting Data for Input or Display

Variable Formatting
Numeric values in variable assignments, expressions or CRT, PRINT and INPUT@ statements can be formatted
using format strings. This will produce a formatted output display of the raw data string.
Multiple format strings can be applied to a variable expression, and if used, will be applied from left to right.
The syntax of this construct is as follows:
Syntax
VARIABLE "{f}{}{,}{d}{fieldwidth}"
f

This character specifies the field justification. L

specifies left, and R specifies right justified within the
field.

The character appends a character to the front of

the field and takes up one position in the specified field
width. The actual character output will depend on your
locale setting - see the Internationalisation chapter in
the System Administrators Manual.

This puts in a , as a separator for thousands. It takes up

one position in the specified field width.

This is a single digit giving the number of decimal

places to display.

fieldwidth

Gives the width of the field in which the value is held,

and can be padded out by:
#... or #n
%... or %n
*... or *n

fill with spaces given

fill with zeroes given
fill with asterisks given

Pattern Matching
Pattern matching functionality is provided allowing comparisons between string variable contents. This
compares the string contents to a specified pattern or patterns, with the outcome being 1 (true) if the patterns
match, or 0 (false) if the patterns are different.
Pattern matching is performed by using the MATCHES or MATCH operators.
The specified pattern for matching can contain any combination of the following within quotes:
{n}A

n is an integer that gives the number of alphabetic characters in

the pattern.

{n}N

n gives the number of numeric characters in the pattern.

Programmers Reference Manual

2-35

jBC

{n}X

n gives the number of alphabetic or numeric characters in the

pattern.

The use of 0 as the value of n implies any number of the specified character, including a null
value.

Conversion Codes for Data

One of the efficiency aspects of jBC and jBASE is that no matter what the format of data displayed on the
terminal, only the raw data need be actually held on disk. This means that decimal points, signs, and other
format incidentals are not saved, thus giving a saving on file storage capacity.
Raw data is subject to special conversion routines that enable their display in a meaningful format.
Similarly, previously formatted data can be stripped of its format and display characters before writing the
record to disk.
jBC uses a set of conversion codes to perform output display formatting. These can also be used to deformat data
before saving it in its raw or internal format.
Date Conversions
Dates are generally required in differing formats, and so an internal date format is used to store them on disk. As
this is simply a number, a conversion code is required to format it to the required output display. The codes are
also used to format strings.
Date conversion codes available are:
Code
D{y}{d}

Effect
The y value is the single digit 0 - 4 and
specifies the number of digits in the year
field. Default value is 4.
The d value is a single non-numeric
character used to delimit the day, month and
year fields. If omitted, the month is given in
alpha character format, otherwise the month
is in two digit numeric format.

DI

This is the opposite of the above conversion,

and when used to format a date output, will
convert a date to internal format.

DD, DJ, DM, DMA,

DQ, DW, DWA, DY
DAY

These codes convert the day, month and year

components of dates to and from internal
formats.

The conversions can be used with the ICONV and OCONV functions (see later). The OCONV function converts
internal formats to output formats. The ICONV statement converts external (Output) formats to internal form.

Program Flow
The following commands and constructs, are used to change the execution path of the linear program flow by
branching to another part of the current or even another program. The branches can be unconditional as with the
GOTO and GOSUB statements, or conditional on the result of an expression as with the IF statement.
GOSUB
The GOSUB command is used to branch to a local subroutine, which is identified by the line label used. When a
RETURN statement is encountered in the subroutine, the program is transferred back, and execution continues at
the line following the GOSUB.

jBC

2-36

Programmers Reference Manual

Care should be taken to structure the usage of GOSUB, and not to exit a subroutine other than with the
RETURN command. RETURN always returns to the statement following the last executed GOSUB.
The GOSUB is generally used to perform ancillary processing outside the main program flow, such as error
handling or logical separate functions of the program.
A similar command is GOTO, which unconditionally branches to the line beginning with the specified label.
Where possible the GOTO statement should not be used as it makes code difficult to read and maintain. As the
jBC compiler is an optimising compiler, there is no performance penalty in using structured statements such as
the LOOP or CASE constructs.
ON .... GOSUB
This construct is used to conditionally branch to one of a list of local subroutines depending upon the value of a
variable or expression. The variable or expression resultant must be an integer in the range 1 to n, where the
value n specifies the number of subroutines. Execution control passes to the nth subroutine in the list provided
with the construct.
IF ... THEN
This construct allows the conditional execution of a sequence of statements. The conditional expression is
evaluated and if the resultant value is 1 or true, then the sequence of statements following the THEN command
are executed. If the value is 0 or false, the statements following the ELSE command (if any) are executed.
It is possible to perform actions based on complex testing of parameters by nesting, or successively repeating an
IF ...THEN clause as part of another.
CASE
This construct allows the conditional execution of a sequence of statements and is used in a similar manner to the
IF ... THEN construct. It differs in that the conditional expressions are examined one at a time, and so makes the
program much more modular and easier to follow.

Looping Constructs
A loop is a series of statements that are executed repeatedly for a specified number of repetitions, or until
specified conditions are met.
To repeat a procedure a set number of times, jBC provides the FOR ... NEXT loop. This allows the programmer
to set a counter that is used to monitor the number of times the loop has been repeated. The repeat of the
procedure can also be made dependent upon specified conditions.
The LOOP statement is used where the number of times a process needs to be repeated is not known, but
depends upon the value of a particular parameter. The loop is repeated while a variable holds a given value, or
until it contains a given value.
Loop constructs may be nested. This means that statements forming a complete loop may be enclosed within
another loop. This in turn can be completely enclosed in another. Loops may be nested to any number of levels.
The BREAK (or EXIT) and CONTINUE statements can be used within loops to cause premature termination of
a loop or to immediately begin the next iteration of the loop. They act upon the innermost loop in the program
structure. BREAK or EXIT will cause the immediate termination of the innermost loop. CONTINUE will
abandon the current iteration of the loop and immediately begin the next iteration of the loop.
Example
FOR I = 1 TO 10 UNTIL I = A
CRT I
A += C
IF A = 5 THEN BREAK

;* End when A is 5

NEXT I

Programmers Reference Manual

2-37

jBC

Subroutines
A subroutine is a self contained piece of code that may be located outside the program itself. The code generally
deals with a routine or procedure that is outside the mainstream processing line, such as error handling or
functionally separate logic. On completion of the subroutine statements, execution of the program continues at
the next statement after the subroutine call.
External subroutines are used to store commonly used routines utilised by many programs. A collection of
external subroutines held in a file or directory is often referred to as a library.
A subroutine that is a part of the main program is accessed by the GOSUB statement, and a RETURN statement
as the last subroutine command passes control back to the main body of the program, and execution continues on
the line after the GOSUB statement.
A subroutine that is external to the program is accessed by the CALL statement. Such an external subroutine
must always reside in its own source file and has the SUBROUTINE command as its first statement. A
RETURN statement as the final statement returns execution control to the line following the CALL statement in
the originating program.
Argument Passing
One or more arguments separated by commas may optionally be passed to an external subroutine as an argument
list. An argument can be a variable, constant, array or expression representing a value.
When an argument list is passed to the subroutine, the SUBROUTINE statement must also contain an argument
list with the same number of arguments as is being passed to it. Values passed in this way can be modified by the
subroutine, and when the RETURN statement is encountered, the modified values are returned to the calling
program.
COMMON and INCLUDE
The COMMON statement can also be used to pass values between programs. This has the advantage that this
statement forces the variables to be stored in memory in the order in which they are presented.
Where the number of arguments to be passed is large, and where this may need to include common sections of
code, then the use of the INCLUDE statement is recommended.
The INCLUDE statement allows common code to be stored outside the main body of the source program. The
advantage is that changes to this code can quickly be made and have an immediate global effect on the source
code, as well as maintaining a consistent and more efficient interface.

C Functions
C functions may be freely mixed with jBC programs and data may be passed to them and received from them.
One or more C function is defined in its own .c file and is specified to the jBC compiler in exactly the same
manner as a jBC .b file. C functions referenced in a jBC program must be declared to the compiler using the
DEFC statement (see later).
Example
PROG.b
001 DEFC INT Cfunc(INT)
002 Number = 45
003 CRT Cfunc(Number)
004 BigNo = Cfunc(1000)
005 CRT BigNo

;* C func returns integer

func.c
int Cfunc(Num)
int Num; /* Integer parameter
*/
{
return
Num*1000; /* Multiply and return */
}

jBC

2-38

Programmers Reference Manual

The programs are combined with jbc PROG.b func.c -o PROG. Note that the function is declared
specifying the data types it expects but that the jBC compiler will resolve all type conversions for you. It is also
possible to pass jBC variables to C functions allowing the programmer to map C structures to jBC variables and
vice versa.

Handling Arrays and Data Files

Arrays
An array is a variable where related data is held together as separate entities. Each entity is referred to as an
element of the array. An array takes the form of an ordered set of data and each element can be addressed
separately.
jBC allows the use of two types of array :

Dimensioned arrays for holding data in the form of lists or tables.

Related data is held using a single variable name, and indicating the number of separate elements
involved. More details are available in the section on Dimensioned arrays later in the chapter.

Dynamic arrays for holding file data and lists of unknown length.
Data kept as records on the system may be accessed in the form of a dynamic array rather than in list or
tabular format. Data held as a dynamic array reflects its structure as held on the physical disk. More
details are available in the section on Dynamic arrays later in the chapter.

Dimensioned Arrays
A dimensioned array is a variable that has more than one piece of data stored within it. All the data within the
array is usually related in an ordered fashion, and each separate entity is called an element of the array.
Dimensioned arrays generally take the form of a vector (list), or a matrix (table).
Vectors
ADDR(4)

6, New Road, Oldtown, OL8 7MB

The above one-dimensioned array is also referred to as a vector. The first element has a value of 6, the second a
value of New Road, and so on. The first element is referenced by the variable ADDR(1), the second by variable
ADDR(2) and so on.
Matrices
array MULT(3,5)
1

row1

10

row2

14

21

28

35

row3

18

27

36

45

column

The above two-dimensional array or matrix holds part of a multiplication table. It consists of rows and columns,
which are specified when referencing the element.
Setting up an Array
Before an array can be used in jBC, it must be set up using the DIM, DIMENSION or COMMON statements.
The separate elements of the array can then be assigned values by reference to the variable in the normal way, or
they can be read into the array from a file using the MATREAD or MATREADU statements.

Programmers Reference Manual

2-39

jBC

Accessing Array Elements

Element of a dimensioned array can be referenced by giving its position within the array. Numbering positions
always begin with 1. In the vector ADDR above, ADDR(3) holds the value Oldtown. In the matrix MULT
above, the first element, 2, is referenced by variable MULT(row,column) i.e. MULT(1,1). The number 21 in the
matrix is accessed by variable MULT(2,3).

Dynamic Arrays
A dynamic array is a vector in which the data corresponds to the fields of a jBASE file record.
A jBASE record is divided into fields, values, and subvalues. The delimiter used for each is displayed using ^
(carat), ] (right bracket), and \ (backslash) respectively. These same delimiters are used to separate the different
elements of the dynamic array, and can be obtained with the keyboard by using the control key with the character
key in the jED editor.
Examples of dynamic arrays are:
1.

MAIN Joe Smith^26^Male^Analyst

This is a dynamic array made up of four fields which give the name, age, sex and job of the person
referenced.

2.

PERS Joe Smith^26]2.4.68^Male]Married\3children

The details in the array have been extended to include values and sub-values. The second field holds
two values for age and date of birth. The third field holds two values for sex and status. The status value
is further split into sub-values for marital status and children.

Setting up a Dynamic Array

A dynamic array can be created by the concatenation of several variables together with the relevant field, value
and sub-value delimiter characters.
A dynamic array is also obtained when a jBASE file record is read into a program using READ or READU
statements. The elements of the array are automatically read from disk including the delimiters. This is because
the dynamic array format is identical to the data storage format of jBASE files. (Note that databases not
conforming to this structure can also be accessed in this manner by mapping the structure in the jEDI library).
Additionally, a value within a record can be read into a dynamic array variable by the READV and READVU
statements.
Accessing Elements of a Dynamic Array
A dynamic array is referenced by the array name. Any of its component parts down to sub-value level can also
be referenced by giving its position within the record:
DYN.ARRAY<field#, value#, sub-value#>
where field#, value# and sub-value# give the numeric position of the element for each entity.
Example
Using the above examples:
MAIN

holds Joe Smith^26^Male^Analyst

PERS

holds Joe Smith^26]2.4.68^Male]Married\3children

MAIN<3>

holds Male

PERS<1>

holds Joe Smith

PERS<2>

holds 26]2.4.68

PERS<2,1> holds 2.4.68

PERS<3,2,1> holds Married

jBC

2-40

Programmers Reference Manual

PERS<3,2,2> holds 3children

File Handling
jBC is able to access data held in any file format with a file variable. A file variable is created when the OPEN
command is executed.
Once a file is OPENed, the file variable is used by input/output statements to access file records. File records
may be held in either of two formats - a dimensioned array or a dynamic array.
Record Access
DYNAMIC ARRAYS give a fast method of data access from disc as the system simply strips off the record key
and places the rest of the record into the file.variable space. By specifying a single variable, a full record can
quickly be read or written away.
Reading records into a DIMENSIONED ARRAY is less efficient as the system has to assign each field into a
separate element of the array. Writing records to file is also less efficient as the data needs to be reassembled
from the array.
File Data Manipulation
DYNAMIC ARRAYS access fields and values by scanning the array from the start. Where the record has a large
number of fields, and access is needed for those towards the end of the record, this will be inefficient as the
system will scan through from the start. The same happens when inserting, deleting or adding data. The jBC
compiler does however, optimise the access to dimensioned arrays and traversing them in any direction is very
fast. jBASE handles dynamic arrays much more efficiently than traditional implementations of the language.
With DIMENSIONED ARRAYS, each field is accessed as an individual variable. Within jBC this means that a
field will be obtained as fast whether it be at the start or end of the record. This makes it more efficient where
data needs to be accessed from large records. Again the jBC compiler optimises access to Dimensioned arrays
making it far more efficient than older implementations of the language.
Guidelines
Use dynamic arrays to read or write data to or from a file. If a dynamic array record field or value is to be used
several times, or needs to be string searched or manipulated, then assigning it to a variable first can improve
performance. However, the optimisation within the jBC compiler may actually do this for you.
Use dimensioned arrays where much work needs to be done on multiple record fields - e.g. to construct new
records or to continually update many fields within large records.

Locking Mechanisms
The jBC data record locking mechanism is available to application programmers for maintaining data integrity.
Any file record accessed by the application can have an update lock set, which will not allow other system users
to concurrently update the same record.
Two types of locks are available.
Execution Locks
An execution lock is used to prevent several different jBC programs from simultaneously executing a defined
process.
For example, a jBC archive application can set an execution lock that prevents other jBC applications from
running a section of code until it is finished or the lock released.
An execution lock may be set by use of the LOCK statement, and are cleared with the UNLOCK statement or
termination of the program.
Individual Record Locks
A record lock is used to prevent a file record from being updated by more than one process at the same time.
This includes the jED editor as well as other jBC programs.

Programmers Reference Manual

2-41

jBC

Record locking is an efficient way of maintaining data integrity as access is only stopped to a single record rather
than to a whole file. Other users are not prevented from updating other records in the same file.
A record lock is set by using the READU, READVU or MATREADU statements, and they are released when
the program terminates or by use of the WRITE, WRITEV, MATWRITE or RELEASE statements.
It is also possible to update a file record that is locked and to keep the lock set by using the WRITEU,
WRITEVU or MATWRITEU statements.
Applications employing record locks can be made more efficient by making use of LOCKED clauses to continue
productive processing whenever a record lock is encountered.

jBC

2-42

Programmers Reference Manual

jBC Statements
This following pages show the syntax of every statement and function in the language together with examples of
their use.

@(Col, Row)
The @ function is used to position the cursor to a specific point on the terminal screen.
Command Syntax
@(col{, row})
Syntax Elements
col and row can be any expression that evaluates to a numeric value. Col specifies which column on the screen
the cursor should be moved to. Row specifies which row (line) on the screen to position the cursor. Col may be
specified on its own, which will cause the cursor to the required column on whichever row it currently occupies.
Notes
When values are specified that exceed either of the physical limits of current terminal, then unpredictable results
will occur.
The terminal is always addressed starting from (0,0), being the top left hand corner of the screen.
Cursor addressing will not normally work when directed at a printer. If you wish to build printer independence
into your programs you may achieve this by accessing the terminfo database through the SYSTEM( ) function
(see later).
Examples
FOR I = 1 TO 5
CRT @(5, I):"*":
NEXT I
Home = @(0,0)
;* Remember the cursor home position
CRT Home:"Hi honey, I'm HOME!":

@(ScreenCode)
The @(ScreenCode) function is also used to output control sequences according to the capabilities of the
terminal.
Command Syntax
@(ScreenCode)
Syntax Elements
Control sequences for special capabilities of the terminal are achieved by passing a negative number as its
argument. ScreenCode is therefore any expression that evaluates to a negative argument.
Notes
jBASE has been designed to import code from many older systems. As these systems have traditionally not coordinated the development of this function they expect different functionality in many instances. In the following
table you should note that different settings of the JBCEMULATE environment variable (see earlier) will elicit
different functionality from this function. Where the emulate code is printed with strikethrough it indicates that
the functionality is denied to this emulation.
Emulate
All
All

Programmers Reference Manual

Code
-1
-2

Function
Clear the screen and home the cursor
Home the cursor

2-43

jBC

All
All
ROS
ROS
ROS
ROS
All
All
ROS
ROS
ROS
ROS
ROS
ROS
ROS
ROS
ROS
ROS
ROS
ROS
All
All
ROS
Emulate
ROS
ROS

-3
-4
-5
-6
-7
-8
-9
-10
-11
-11
-12
-12
-13
-13
-14
-14
-15
-15
-16
-16
-17
-18
-19
Code
-19
-20

Clear screen from the cursor to the end of the screen.

Clear screen from cursor to the end of the current screen line.
Turn on character blinking
Turn off character blinking
Turn on protected field mode
Turn off protected field mode
Move the cursor one character to the left
Move the cursor one row up the screen
Turn on the cursor (visible)
Enable protect mode
Turn off the cursor (invisible)
Disable protect mode
Status line on
Turn on reverse video mode
Status line off
Turn off reverse video mode
Move cursor forward one character
Turn on underline mode
Move cursor one row down the screen
Turn off underline mode
Turn on the slave (printer) port
Turn off the slave (printer) port
Dump the screen to the slave port
Function
Move the cursor right one character
Move the cursor down one character

All

-128
.
.
.

The codes from -128 to -191 control screen attributes.

Where Bit 0 is least significant you may calculate the
desired code by setting Bit 7 and Bits 0-4:
Bit 0 - Dimmed mode when set to 1
Bit 1 - Flashing mode when set to 1
Bit 2 - Reverse mode when set to 1
Bit 3 - Blanked mode when set to 1
Bit 4 - Underline mode when set to 1
Bit 5 - Bold mode when set to 1
Bit 7 - Always set to 1

If a colour terminal is in use, -33 to -64 will control colours.

Thus Reverse and Flashing mode is -134.

To turn off all effects use -128.
ROS
ROS
ROS
ROS

-311
-312
-313
-314

Turn on the cursor (visible)

Turn off the cursor (invisible)
Turn on the status line
Turn off the status line

Examples
CRT @(-1):@(30):@(-132):"jBASE Heading":@(-128):
CRT @(5,5):@(-4):"Prompt: ": ; INPUT Answer

ABORT
The ABORT statement terminates the program running as well as the program that called it.
Command Syntax
ABORT {message.number{, expression ...}}
Syntax Elements
The optional message.number provided with the statement must be a numeric value, which corresponds to a
record key in the jBASE error message file

jBC

2-44

Programmers Reference Manual

A single expression or a list of expression(s) may follow the message.number. Where more than one expression
is listed, they must be delimited by use of the comma character. The expression(s) correspond to the parameters
that need to be passed to the error file record to print it.
The optional message.number and expression(s) given with the command are parameters or resultants provided
as variables, literal strings, expressions, or functions.
Notes
This statement is used to terminate the execution of a jBC program together with any calling program. It will
then optionally display a message, and return to the shell prompt.
The optional message displayed on terminating the program is held in the error file. For successful printing of
the message, parameters such as linefeeds, clearscreen, date and literal strings may also be required.
Operation of this command can be altered by setting the Command Level Restart option - see the Systems
Housekeeping chapter of the System Administrators Reference Manual for more details.
Example
CRT "CONTINUE (Y/N) ?":; INPUT ANS
IF ANS NE "Y" THEN ABORT 66, "Aborted"
This will terminate the program and print error message 66 passing to it the string "Aborted", which will be
printed as part of error message 66.

ABS( )
The ABS function will return the mathematical absolute of the ()expression.
Command Syntax
ABS(expression)
Syntax Elements
expression can be an expression of any form that should evaluate to a numeric. The ABS function will then
return the mathematical absolute of the expression. This will convert any negative number into a positive result.
Notes
This can be expressed as:
value < 0 ? 0-value : value;
Examples
CRT ABS(10-15)
Displays the value 5.
PositiveVar = ABS(100-200)
Assigns the value 100 to the variable PositiveVar.

ALPHA( )
The ALPHA function will check that the expression consists entirely of alphabetic characters.
Command Syntax
ALPHA(expression)

Programmers Reference Manual

2-45

jBC

Syntax Elements
The expression can return a result of any type. The ALPHA function will then return TRUE (1) if the expression
consists entirely of alphabetic characters. If any character in expression is non alphabetic then the function
returns FALSE (0).
Notes
Alphabetic characters are in the set a-z and A-Z
Example
Abc = "ABC"
IF ALPHA(Abc) THEN CRT "alphabetic"
Abc = "123"
IF NOT(ALPHA(Abc)) THEN CRT "non alphabetic"
Displays:
alphabetic
non alphabetic

ASCII( )
The ASCII function converts all the characters in the expression from the EBCDIC character set to the ASCII
character set.
Command Syntax
ASCII(expression)
Syntax Elements
The expression may return a data string of any form. The function will then assume that the characters are all
members of the EBCDIC character set and translate them using a character map. The original expression is
unchanged while the returned result of the function is now the ASCII equivalent.
Notes
Examples
READT EbcdicBlock ELSE CRT "Tape failed!"; STOP
AsciiBlock = ASCII(EbcdicBlock) ;* Convert to ASCII

ASSIGNED( )
The ASSIGNED function returns a Boolean TRUE or FALSE result depending on whether or not a variable has
been assigned a value.
Command Syntax
ASSIGNED(variable)
Syntax Elements
ASSIGNED returns TRUE if the variable named has been assigned a value before the execution of this
statement. If the variable has never been assigned a value then the function returns FALSE.
Notes
This function has been provided as it has been implemented in older implementations of the language. It is far
better to program in such a way as this statement will not be needed.

jBC

2-46

Programmers Reference Manual

Examples
IF ASSIGNED(Var1) THEN
CRT "Var1 has been assigned a value"
END

BITCHANGE
BITCHANGE toggles the state of a specified bit in the local bit table, and return the original value of the bit.
Command Syntax
BITCHANGE(table_no)
Syntax Elements
table_no specifies the position in the table of the bit to be changed.
Notes
A unique table of 128 bits (numbered 1 to 128) is maintained for each process. Each bit in the table is treated as
a two-state flag - the value returned will always be 0 (zero) or 1.
BITCHANGE returns the value of the bit before it was changed. You can therefore check and set (or reset) a
flag in one step.
BITCHANGE also provides some special functions if you use one of the following table_no values:
-1

toggles (enables/disables) the BREAK key Inhibit bit.

-2

toggles (enables/disables) the Command Level Restart feature.

-3

toggles (enables/disables) the Break/End Restart feature.

Example
OLD.VAL = BITCHANGE(100)
CRT OLD.VAL
If bit 100 in the table is 0 (zero), it will be set to 1 and 0 will be displayed. If bit 100 is set to 1 (one), the reverse
will apply.

BITCHECK
BITCHECK returns the current value of a specified bit from the local bit table.
Command Syntax
BITCHECK(table_no)
Syntax Elements
table_no specifies the position in the table of the bit to be checked.
Notes
A unique table of 128 bits (numbered 1 to 128) is maintained for each process. Each bit in the table is treated as
a two-state flag - the value returned will always be 0 (zero) or 1.
BITCHECK also provides some special functions if you use one of the following table_no values:
-1

returns the setting of the BREAK key Inhibit bit.

-2

returns the setting of the Command Level Restart feature.

-3

returns the setting of the Break/End Restart feature.

Examples
BIT.VAL = BITCHANGE(100)
CRT BIT.VAL

Programmers Reference Manual

2-47

jBC

If bit 100 in the table is 0 (zero), 0 will be displayed. If bit 100 is set to 1 (one), 1 will be displayed.

BITLOAD
BITLOAD assigns all values in the local bit table, or retrieves all the values.
Command Syntax
BITLOAD({bit-string})
Syntax Elements
bit-string is an ASCII string of characters which represent a hexadecimal value. It is interpreted as a bit pattern
and used to assign values to the table from left to right. Assignment stops at the end of the string or when a nonhexadecimal character is found.
If the string represents less than 128 bits, the remaining bits in the table are reset to 0 (zero).
If bit-string is omitted or evaluates to null, an ASCII hex character string is returned, which defines the value of
the table. Trailing zeroes in the string are truncated.
Notes
A unique table of 128 bits (numbered 1 to 128) is maintained for each process. Each bit in the table is treated as
a two-state flag - the value will always be 0 (zero) or 1.
Example 1
NEW.VALUE = 0123456789ABCDEF
OLD.VALUE = BITLOAD(X)
Loads the bit table with the value of ASCII hex string NEW.VALUE. After assignment, the contents of the bit
table are:
0000
1000
0000
0000

0001
1001
0000
0000

0010
1010
0000
0000

0011
1011
0000
0000

0100
1100
0000
0000

0101
1101
0000
0000

0110
1110
0000
0000

0111
1111
0000
0000

Note that all values beyond the 64th bit have been reset to 0 (zero).
Example 2
TABLE.VALUE = BITLOAD()
Loads variable TABLE.VALUE with the hexadecimal values of the bit table.

BITRESET
BITRESET resets the value of a specified bit in the local bit table to 0 and returns the value of the bit before it
was changed.
Command Syntax
BITRESET(table_no)
Syntax Elements
table_no specifies the position in the table of the bit to be reset. If table_no evaluates to zero, all elements in the
table are reset to 0 (zero) and the returned value is zero.
Notes
A unique table of 128 bits (numbered 1 to 128) is maintained for each process. Each bit in the table is treated as
a two-state flag - the value returned will always be 0 (zero) or 1.

jBC

2-48

Programmers Reference Manual

BITRESET returns the value of the bit before it was changed - checking and resetting a flag can be
accomplished in one step.
BITRESET also provides some special functions if you use one of the following table_no values:
-1

resets the BREAK key Inhibit bit.

-2

resets the Command Level Restart feature.

-3

resets the Break/End Restart feature.

Example
OLD.VALUE = BITRESET(112)
PRINT OLD.VALUE
If table entry 112 is 1, returns a value of 1, resets bit 112 to 0, and prints 1. If table entry 112 is 0, returns a value
of 0, and prints 0.

BITSET
BITSET sets the value of a specified bit in the bit table to 1 and returns the value of the bit before it was
changed.
Command Syntax
BITSET(table_no)
Syntax Elements
table_no specifies the bit to be SET. If table_no evaluates to zero, all elements in the table are set to 1 (one) and
the returned value is one.
Notes
A unique table of 128 bits (numbered 1 to 128) is maintained for each process. Each bit in the table is treated as
a two-state flag - the value returned will always be 0 (zero) or 1.
BITSET returns the value of the bit before it was changed - checking and setting a flag can be accomplished in
one step.
BITSET also provides some special functions if you use one of the following table_no values:
-1

sets the BREAK key Inhibit bit.

-2

sets the Command Level Restart feature.

-3

sets the Break/End Restart feature.

Example 1
OLD.VALUE = BITSET(112)
PRINT OLD.VALUE
If table entry 112 is 0, returns a value of 0, sets bit 112 to 1, and prints 0. If table entry 112 is 1, returns a value
of 1, and prints 1.

BREAK
The BREAK statement allows the break key to be configured.
Command Syntax
BREAK
BREAK ON
BREAK OFF
BREAK expression

Programmers Reference Manual

2-49

jBC

Syntax Elements
When used with an expression, or the keywords ON or OFF the BREAK statement enables or disables the
BREAK key for the current process. In UNIX terms the BREAK key is more commonly known as the interrupt
sequence intr defined by the stty command.
Used as a standalone statement, BREAK will terminate the currently executing loop. The EXIT statement is
functionally equivalent to the BREAK statement used without arguments.
Notes
As BREAK is used to terminate the innermost loop, it is ignored if used outside a loop construct. The compiler
will issue warning message 44, and ignore the statement.
Examples
LOOP
READNEXT KEY FROM LIST1 ELSE BREAK
......
REPEAT
* Program resumes here after BREAK

CALL
The CALL statement transfers program execution to an external subroutine.
Command Syntax
CALL {@}subroutine.name {(argument {, argument ... })}
Syntax Elements
The CALL statement transfers program execution to the subroutine called subroutine.name, which can be any
valid string either quoted or unquoted. The CALL @ variant of this statement assumes that subroutine.name is a
variable that contains the name of the subroutine to call.
The CALL statement may optionally pass a number of parameters to the target subroutine. These parameters can
consist of any valid expression or variable name. If a variable name is used then the called program may return a
value to the variable by changing the value of the equivalent variable in its own parameter list.
Notes
When using an expression to pass a parameter to the subroutine, you may not use any of the built-in functions
(such as COUNT), of jBC within the expression.
There is no limit to the number of parameters that may be passed to an external subroutine.
The number of parameters in the CALL statement must match exactly the number expected in the
SUBROUTINE statement declaring the external subroutine.
The calling program and the external subroutine must be compiled with the same PRECISION.
Variables passed as parameters to the subroutine may not reside in any COMMON areas declared in the
program. Here are some examples of the CALL statement:
Examples
CALL MySub
SUBROUTINE

MySub

CALL Hello("World")
SUBROUTINE Hello (Message)
CALL Complex(i, j, k)
SUBROUTINE Complex(ComplexA, ComplexB, ComplexC)

jBC

2-50

Programmers Reference Manual

CASE
The CASE statement allows the programmer to execute a particular sequence of instructions based upon the
results of a series of test expressions.
Command Syntax
BEGIN CASE
CASE expression
statement(s)
CASE expression
statement(s)
.....
END CASE
Syntax Elements
The CASE structure is bounded by the BEGIN CASE and END CASE statements. Within this block, an
arbitrary number of CASE expression statements may exist followed by any number of jBC statements. The
expression should evaluate to a TRUE or FALSE result. At execution time, each expression is evaluated in
order. If the expression returns a TRUE result, then the statements beneath it are executed. On completion of the
associated statements, execution will resume at the first statement following the END CASE.
Notes
A default action (to trap error conditions for instance) may be introduced by using an expression that is always
TRUE, such as CASE 1. This should always be the last expression in the CASE block.
Example
BEGIN CASE
CASE A = 1
CRT "You won!"
CASE 1
CRT "You came nowhere"
END CASE
A single comment is printed depending on the value of A. Note that if A is not 1 then the default CASE 1 rule
will be executed as a "catch all".

CHAIN
The CHAIN statement exits the current program and transfers process control to the program defined by the
expression. Process control will never return to the originating program.
Command Syntax
CHAIN expression
Syntax Elements
The expression should evaluate to a valid UNIX command (this may be another jBC program). The command
string may be suffixed with the (I option, which will cause any COMMON variables in the current program to be
inherited by the new program (providing it is a jBC program).
Notes
There are no restrictions to the CHAIN statement and you may CHAIN from anywhere to anywhere. However,
you should try and make your programs follow a logical path that may be easily seen by another programmer.
If the program which contains the CHAIN command (the current program) was called from a jCL program, and
the program to be executed (the target program) is another jBC program, control will return to the original jCL
program when the target program terminates. If the target program is a jCL program, control will return to the
command shell when the jCL program terminates.

Programmers Reference Manual

2-51

jBC

Examples
CHAIN "OFF"

;* Exit via the OFF command

! Prog1
COMMON A,B
A = 50; B = 100
CHAIN "NEWPROG (I"
! NEWPROG
COMMON I,J
! I and J inherited
CRT I,J

CHANGE
The CHANGE statement operates on a variable and replaces all occurrences of one string with another.
Command Syntax
CHANGE expression1 TO expression2 IN variable
Syntax Elements
Expression1 may evaluate to any result and is the string of characters that will be replaced. Expression2 may
also evaluate to any result and is the string of characters that will replace expression1. The variable may be any
previously assigned variable in the program.
Notes
Either string can be of any length and is not required to be the same length. The jBC language also supports the
CHANGE function for compatibility with older systems.
Examples
String1 = "Jim"
String2 = "James"
Variable = "Pick up the tab Jim"
CHANGE String1 TO String2 IN Variable
CHANGE "tab" TO "cheque" IN Variable

CHAR( )
The CHAR function returns the ASCII character specified by the expression.
Command Syntax
CHAR(expression)
Syntax Elements
The expression must evaluate to a numeric argument in the range 0-255. This is the entire range of the ASCII
character set.
Notes
jBC variables can contain any of the ASCII characters 0-255, thus there are no restrictions on this function.
This function is often used to insert field delimiters within a variable or string. These are commonly equated to
AM, VM, SV in a program.
Examples
EQUATE
EQUATE
EQUATE

jBC

AM
VM
SV

TO CHAR(254)
TO CHAR(253)
TO CHAR(252)

;* Field Mark
;* Value Mark
;* Sub Value mark

2-52

Programmers Reference Manual

CRT CHAR(7): ;* Ring the bell

CHDIR( )
The CHDIR function allows the UNIX current working directory, as seen by the process environment, to be
changed.
Command Syntax
CHDIR(expression)
Syntax Elements
The expression should evaluate to a valid path name within the UNIX system. The function returns a Boolean
TRUE result if the CHDIR succeeded and a Boolean FALSE result if it failed.
Examples
IF CHDIR("/usr/jbc/src") THEN
CRT "jBASE development system INSTALLED"
END

CHECKSUM ( )
The CHECKSUM function returns a simple numeric checksum of a character string.
Command Syntax
CHECKSUM(expression)
Syntax Elements
The expression may evaluate to any result but will usually be a string. The function then scans every character in
the string and returns a numeric addition of the characters within the string.
Notes
The function calculates the checksum by summing the product of the ASCII value of each character and its
position within the string.
Examples
INPUT DataBlock,128:
IF CHECKSUM(DataBlock) = ExpectedChk THEN
CRT AckChar:
END ELSE
......

CLEAR
The CLEAR statement will initialise all the variables to numeric 0.
Command Syntax
CLEAR
Notes
CLEAR can be used at any time during the execution of the program.
Examples
Var1 = 99
Var2 = 50
.
.

Programmers Reference Manual

2-53

jBC

CLEAR

CLEARFILE
The CLEARFILE statement is used to clear all the data from a file previously opened with the OPEN
statement.
Command Syntax
CLEARFILE {variable} {SETTING setvar} {ON ERROR statements}
Syntax Elements
The variable must have been the subject of an OPEN statement before the execution of CLEARFILE upon it.
If the variable is omitted from the CLEARFILE statement, then the default file variable is assumed as per the
OPEN statement.
Notes
The CLEARFILE statement will remove every database record on the file it is executed against. It should
therefore be used with great care.
If the variable argument does not describe a previously opened file, the program will enter the debugger with an
appropriate message.
If the SETTING clause is specified and the CLEARFILE fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Examples
OPEN "DATAFILE" ELSE ABORT 201, "DATAFILE"
OPEN "PROGFILE" TO FILEVAR ELSE ABORT 201, "PROGFILE"
CLEARFILE
CLEARFILE FILEVAR

CLOSE
The CLOSE statement is used to CLOSE a previously opened file when it is no longer needed.
Command Syntax
CLOSE variable{, variable ...}
Syntax Elements
The variable list is should contain a list of previously opened file variables that are no longer needed. The
variables will be cleared and may be reused as ordinary variables.
Notes
It is good practice to hold open only those file descriptors that you wish to have constant access to. Although
there is no limit to the number of files that may be opened within jBC, opening large numbers of files and
leaving them open can consume resource that can be better used.
Examples
OPEN "DATAFILE" TO FILEVAR ELSE ABORT 201, "DATAFILE"
.....
CLOSE FILEVAR

jBC

2-54

Programmers Reference Manual

COMMON
The COMMON statement declares a list of variables and matrices that can be shared among various programs.
There can be many common areas including a default, unnamed common area.
Command Syntax
COMMON {/CommonName/} variable{, variable ... }
Syntax Elements
The list of variables should not have been declared or referenced previously in the program file. The compiler
will detect any bad declarations and display suitable warning or error messages. If the common area declared
with the statement is to be named then the first entry in the list should be a string, delimited by the '/' character.
Notes
The compiler will not, by default, check that variables declared in COMMON statements are initialised before
they have been used as this may be beyond the scope of this single source code check. The -JCi option, when
specified to the jBC compiler, will force this check to be applied to common variables as well.
Variables declared without naming the common area may only be shared between the program and its
subroutines (unless CHAIN is used). Variables declared in a named common area may be shared across program
boundaries. When any common area is shared, all programs using it should have declared the same number of
variables within it.
Dimensioned arrays are declared and dimensioned within the COMMON statement.
Examples
COMMON
COMMON

A, B(2, 6, 10), c
/Common1/ A, D, Array(10, 10)

COL1( ) & COL2( )

These functions are used in conjunction with the FIELD function to determine the character positions 1 position
before and 1 position after the last field that was located.
Command Syntax
COL1()
COL2()
Notes
When a field has been located in a string, it is sometimes useful to know its exact position within the string to
manipulate either it, or the rest of the string. COL1() will return the position of the character immediately before
the last field located. COL2() will return the position of the character immediately after the end of the last field
located. They can then be used to manipulate the string.
Examples
A =
Fld
CRT
CRT

"A,B,C,D,E"
= FIELD(A, ",", 2)
COL1()
COL2()
Displays the values 2 and 4

COLLECTDATA
The COLLECTDATA statement is used to retrieve data passed from the PASSDATA clause of an EXECUTE
statement.

Programmers Reference Manual

2-55

jBC

Command Syntax
COLLECTDATA variable
Syntax Elements
variable is the name of the variable which is to store the retrieved data.
Notes
The COLLECTDATA statement can be used in any program which is EXECUTEd (or PERFORMed) by
another program where the calling program uses a PASSDATA clause. The EXECUTEd program uses a
COLLECTDATA statement to retrieve the passed data.
If a PASSDATA clause is not in effect, variable will be assigned a value of null.
Example
FIRST
001 EXECUTE RUN JBC_PROGS SECOND PASSDATA Handover
SECOND
001 COLLECTDATA PassedMessage
002 CRT PassedMessage
In the above example, program FIRST will EXECUTE program SECOND and will pass the string Handover in
the PASSDATA clause. Program SECOND retrieves the string to a variable PassedMessage and prints the string
on the Terminal screen.

CONTINUE
The CONTINUE statement is the complimentary statement to the BREAK statement without arguments.
Command Syntax
CONTINUE
The statement is used within a loop to skip the remaining code in the current iteration and proceed directly on to
the next iteration.
Notes
See also:

BREAK

EXIT

The compiler will issue a warning message and ignore the statement if it is found outside an iterative loop such
as FOR...NEXT, LOOP...REPEAT.
Examples
FOR I = 1 TO 30
IF Pattern(I) MATCHES "0N" THEN CONTINUE
GOSUB ProcessText
NEXT I
The above example will execute the loop 30 times but will only call the subroutine ProcessText when the
current array element of Pattern is not a numeric value or null.

CONVERT
The CONVERT statement will search a variable looking for every occurrence of every character in expression1.
When it finds such an occurrence it replaces it with the equivalent character in expression2.
Command Syntax
CONVERT expression1 TO expression2 IN variable

jBC

2-56

Programmers Reference Manual

Syntax Elements
The expressions may consist of any valid jBC expression but will normally evaluate to a string of characters. The
variable can be any previously assigned variable or array element within the program.
Notes
The CONVERT statement does a one for one character conversion (as opposed to the CHANGE statement).
This means that every occurrence of a character in expression1 is converted to the corresponding character in
expression2. If there is no corresponding character in expression2 (i.e. expression2 is shorter than expression1)
then the character is removed.
Examples
CONVERT ".," TO "$,." IN Value
CONVERT "abc" TO "ABC" IN PartCode
CONVERT "1234567890" TO "0987654321" IN Code
Selecting from the examples above, the '' is converted to '$', the 'b' to 'B' and the '4' to '7'.

CONVERT( )
The CONVERT function is the function form of the CONVERT statement described earlier. It performs
exactly the same function but may also operate on an expression rather than being restricted to variables.
Command Syntax
CONVERT(expression1, expression2, expression3)
Syntax Elements
Expression1 is the string to which the conversion will apply. Expression2 is the list of all characters to translate
in expression1. Expression3 is the list of characters that will be converted to.
Notes
See Also:

CONVERT statement.

Examples
Value = CONVERT(Value, ".,", "$,.")
Value = CONVERT(PartCode, "abc", "ABC")
Value = CONVERT(Code, "1234567890", "0987654321")

COS( )
The COS function calculates the cosine of any angle using floating point arithmetic, then rounds to the precision
implied by the jBC program. This makes it very accurate.
Command Syntax
COS(expression)
This function calculates the cosine of an expression.
Syntax Elements
The expression must evaluate to a numeric result or a runtime error will occur.
Notes
The value returned by expression is assumed to be in degrees.
Examples
FOR I = 1 TO 360

Programmers Reference Manual

2-57

jBC

CRT COS(I)
NEXT I

;* Print cos i for 1 to 360 degrees.

COUNT( )
The COUNT function returns the number of times that expression2 occurs in expression1.
Command Syntax
COUNT(expression1, expression2)
Syntax Elements
Both expression1 and expression2 may evaluate to any data type but logically they will evaluate to character
strings.
Notes
The count is made on overlapping occurrences as a pattern match from each character in expression1. This
means that the string jjj occurs 3 times in the string jjjjj.
Examples
Calc = "56 * 23 / 45 * 12"
CRT "There are ":COUNT(Calc, "*"):" multiplications"

CRT
The CRT statement sends data directly to the terminal, even if a PRINTER ON statement is currently active.
Command Syntax
CRT expression {, expression..} {:}
Syntax Elements
An expression can evaluate to any data type. The CRT statement will convert the result to a string type for
printing. Expressions separated by commas will be sent to the screen separated by a tab character.
The CRT statement will append a newline sequence to the final expression unless it is terminated with a colon ':'
character.
Notes
As the expression can be any valid expression, it may have output formatting applied to it.
A jBC program is normally executed using buffered output mode. This means that data is not flushed to the
terminal screen unless a newline sequence is printed or terminal input is requested. This makes it very efficient.
However you can force output to be flushed to the terminal by printing a null character CHAR(0). This has the
same effect as a newline sequence but without affecting screen output.
Examples
CRT A "L#5"
CRT @(8,20):"Jim":
FOR I = 1 TO 200
CRT @(10,10):I:CHAR(0):
...
NEXT I

DATA
The DATA statement stacks the series of expressions on a terminal input FIFO stack. Terminal input statements
will then treat this data as if it was typed in at the keyboard.

jBC

2-58

Programmers Reference Manual

Command Syntax
DATA expression {, expression ...}
Syntax Elements
The expression may evaluate to any data type. Each comma separated expression will be viewed as one line of
terminal input.
Notes
The data stacked for input will subsequently be treated as input by any jBC program. Therefore it may be used
before PERFORM/EXECUTE, CHAIN or any other method of transferring program execution. It may also be
used to stack input for the currently executing program.
When stacked data is detected by a jBC program, it is taken as keyboard input until the stack is exhausted. The
program will then revert to the terminal device for subsequent terminal input.
Stacked data delimited by field marks (xFE) will be treated as a series of separate terminal inputs.
Examples
DATA "Y", "N", "CONTINUE"
EXECUTE "PROGRAM1"

;* Stack input for prog

;* Execute the program

DATE( )
The DATE( ) function returns the date in internal system form. This date is expressed as the number of days
since December 31, 1967.
Command Syntax
DATE( )
Notes
The system and your own programs should manipulate date fields in internal form. They can then be converted
to a readable format of your choice using the OCONV( ) function and the date conversion codes.
See also:

TIMEDATE( )

Examples
CRT OCONV(DATE(), "D2")
displays todays date in the form:

14 JUL 64

DCOUNT( )
The DCOUNT( ) function counts the number of field elements in a string that are separated by a specified
delimiter.
Command Syntax
DCOUNT(expression1, expression2)
Syntax Elements
Expression1 evaluates to a string in which fields are to be counted. Expression2 evaluates to the delimiter string
that will be used to count the fields.
Notes
The delimiter string may consist of more than 1 character.
If expression1 is a NULL string, then the function will return a value of 0.

Programmers Reference Manual

2-59

jBC

The delimiter string may consist of any character, including system delimiters such as field marks or value
marks.
Examples
A = "A:B:C:D"
CRT DCOUNT(A, ":")
will display the value 4.

DEBUG
The DEBUG statement causes the executing program to enter the jBC debugger.
Command Syntax
DEBUG
Notes
The debugger is described in a separate chapter of this manual.
Examples
IF FatalError = TRUE THEN
DEBUG
;* Enter the debugger
END

DEFC
The DEFC statement is used to declare an external C function to the jBC compiler and define its arguments and
return types.
Command Syntax
DEFC {FuncType} FuncName ({ArgType {, ArgType ...}})
Syntax Elements
FuncType and ArgType are selected from one of INT, FLOAT or VAR. FuncType specifies the type of result
that the function will return. If FuncType is omitted then INT will be assumed. The optional list of ArgTypes
specifies the argument types that the C function will expect. The compiler must know this in advance as it will
automatically perform type conversions on these arguments.
Notes
A DEFC must be compiled for each C function before any reference is made to it or the compiler will not
recognise the function name.
The function is called in the same manner as it would be in a C program. This means it can be used as if it was
an intrinsic function of the jBC language and therefore returns a value. However it can also be specified as a
standalone function call, which causes the compiler to generate code that ignores any returned values.
When jBC variables are passed to a C function you must utilise predefined macros to access the various data
types it contains. These macros are fully documented in the manual "jBASE External Interfaces". This manual
also gives examples of working C functions and documents other interfaces available to the jBC programmer.
C functions are particularly useful for increasing the performance of tight loops that perform specific functions.
The jBC compiler must cater for any eventuality within a loop (such as the controlling variable changing from
integer to floating point). A dedicated C function can ignore such events, if they are guaranteed not to happen.
The jBC programmer may freely ignore the type of argument used when the C function is invoked as the jBC
compiler will automatically perform type conversion.

jBC

2-60

Programmers Reference Manual

Example 1
DEFC
INT cfunc( INT, FLOAT, VAR)
Var1
= cfunc( A, 45, B)
cfunc( 34, C, J)
Standard UNIX functions may be called directly be declaring them with the DEFC statement according to their
parameter requirements. However, they may only be called directly providing they return one of the types int or
float/double or that the return type may be ignored.
Example 2
DEFC INT getpid()
CRT Process id =:getpid()

DEL
The DEL statement is used to remove a specified element of a dynamic array.
Command Syntax
DEL variable<expression1{, expression2{, expression3}}>
Syntax Elements
The variable can be any previously assigned variable or matrix element. The expressions must evaluate to a
numeric value or a runtime error will occur. Expression1 specifies the field in the array to operate upon and must
be present. Expression2 specifies the multivalue within the field to operate upon and is an optional parameter.
Expression3 is optionally present when expression2 has been included. It specifies which subvalue to delete
within the specified multivalue.
Notes
Non integer values for any of the expressions are truncated to integers.
Invalid numeric values for the expressions are ignored without warning.
The command operates within the scope specified. I.E. if only a field is specified then the entire field (including
its multivalues and subvalues) is deleted. If a subvalue is specified, then only the subvalue is deleted leaving its
parent multivalue and field intact.
Examples
FOR I = 1 TO 20
Numbers<I> = I
;* Generate numbers
NEXT I
FOR I = I9 TO 1 STEP -2
DEL Numbers<I>
;* Remove odd numbers
NEXT I

DELETE
The DELETE statement is used to delete a record from a jBASE file.
Command Syntax
DELETE {variable,} expression {SETTING setvar} {ON ERROR statements}
Syntax Elements
The variable (if specified), should have been the subject of a previous OPEN statement. If the variable is
omitted then the default file variable is assumed.
The expression should evaluate to the name of a record stored in the open file.
If the SETTING clause is specified and the delete fails, setvar will be set to one of the following values:
128 No such file or directory

Programmers Reference Manual

2-61

jBC

4096 Network error

24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The statement will have no effect if the record name does not exist within the file.
If a lock was being held by the program against the file record, then the lock will be released.
Examples
OPEN "DAT1" TO DatFile1 ELSE ABORT 201, "DAT1"
DELETE DatFile1, "record1"
will delete the record "record1" from the file DAT1.

DELETELIST
The DELETELIST statement will delete the previously stored list named by expression.
Command Syntax
DELETELIST expression
Syntax Elements
The expression should evaluate to the name of a list that has been stored either with the WRITELIST statement
or the SAVE-LIST command from the shell.
Notes
Lists are saved in the jBASE work file.
Examples
List = "JobList"
DELETELIST List
will delete the pre-saved list called JobList.

DIMENSION
The DIM statement is used to declare arrays to the compiler before they are referenced.
Command Syntax
DIM{ENSION} variable(number{, number...}){, variable(number {, number...}) ...}
Syntax Elements
The variable may be any valid variable name that has not already been used or declared. The numbers define the
size of each dimension and must be either constants or the subject of an EQUATE statement.
A number of arrays may be declared by a single DIM statement by separating their declarations with a comma.
Notes
The array must be declared before it is referenced in the program source (compilation as opposed to execution).
The compiler will display an error message if a variable is used as a dimensioned array before it has been
declared.
The array variable may not be used as a normal variable or dynamic array before being dimensioned and the
compiler will detect this as an error.

jBC

2-62

Programmers Reference Manual

A dimension size may not be specified as 1 as this has no logical meaning. The compiler will detect this as a
warning.
When arrays are referenced directly as in A = Array(7), the compiler will optimise the reference as if it was a
single undimensioned variable.
See also:

COMMON

Examples
EQUATE DimSize1 TO 29
DIM Array1(10,10), Array2(5, 20, 5, 8)
DIM Age(DimSize1)

DTX( )
The DTX function will return the hexadecimal representation of a numeric expression.
Command Syntax
DTX( expression)
Syntax Elements
Expression must evaluate to a decimal numeric value or a runtime error will occur.
Examples
Decimal = 254
CRT DTX(Decimal)
displays FE.

EBCDIC( )
The EBCDIC function converts all the characters in an expression from the ASCII character set to the EBCDIC
character set.
Command Syntax
EBCDIC(expression)
Syntax Elements
expression may contain a data string of any form. The function will convert it to a character string, assume that
the characters are all members of the ASCII set and translate them using a character map. The original
expression is unchanged while the returned result of the function is now the EBCDIC equivalent.
Notes
Examples
READT AsciiBlock ELSE CRT "Tape failed!"; STOP
EbcdicBlock = EBCDIC(AsciiBlock)
;*
Convert to
*
EBCDIC

ECHO
The ECHO statement will turn on or off the echoing of characters typed at the keyboard.
Command Syntax
ECHO ON
ECHO OFF
ECHO expression

Programmers Reference Manual

2-63

jBC

Syntax Elements
The statement may be used with the keywords ON and OFF to specify echoing or not. If used with an
expression, then the expression should evaluate to a Boolean TRUE or FALSE result. If TRUE then echoing will
be turned on, and if FALSE, echoing will be turned off.
Notes
The SYSTEM function can be used to determine the current state of character echoing. If echoing is enabled
then SYSTEM(24) will return Boolean TRUE and if disabled it will return Boolean FALSE.
Examples
ECHO OFF
CRT "Enter your password ":
INPUT Password
ECHO ON
.....
This will disable character input echoing while a password is typed in.

ENTER
The ENTER statement unconditionally passes control to another executable program.
Command Syntax
ENTER program_name
ENTER @ variable_name
Syntax Elements
program_name is the name of the program to be executed. The use of single or double quotes to surround
program_name is optional.
@ specifies that the program name is contained in a named variable.
variable_name is the name of the variable which contains the program name.
Notes
The jBC COMMON data area can be passed to another jBC program by specifying the I option after the
program name - see the examples. The COMMON data area can only be passed to another jBC program.
ENTER can be used to execute any type of program.
If the program which contains the ENTER command (the current program) was called from a jCL program, and
the program to be executed (the target program) is another jBC program, control will return to the original jCL
program when the target program terminates. If the target program is a jCL program, control will return to the
command shell when the jCL program terminates.
Examples
ENTER menu.
ENTER menu (I.
ProgName = UPDATE (I
ENTER @ ProgName

EQUATE
EQUATE is used to declare a symbol equivalent to a literal, variable or simple expression.

jBC

2-64

Programmers Reference Manual

Command Syntax
EQU{ATE} symbol TO expression
Syntax Elements
symbol is the name of the symbol to use. Can be any name that would be valid for a variable.
expression can be a literal, a variable or a simple expression..
Notes
Sensible use of EQUATEd symbols can make your program easier to maintain, easier to read, and more
efficient.
Efficiency can be enhanced because the address of an EQUATEd value is computed during compilation and is
substituted for each occurrence of the symbol name. Unlike the address of a variable, which has to be computed
for each access during run time, the address of a symbol is always known. This means that the processing
overhead involved in accessing a particular value can be significantly reduced. See the example for a more
detailed explanation of the other benefits.
Readability can be enhanced by referring to say, QTY rather than INV_LINE(4). You would simply EQUATE
QTY TO INV_LINE(4) at an early stage in the program. This can also help with maintenance of the program,
particularly in situations where record layouts might change. For example, if the quantity field moves to
INV_LINE(6), you will only have to change one line in your program.
Example
COMMON FLAG
EQUATE NO_CHARGE TO FLAG
EQUATE CR TO CHAR(13), TRUE TO 1, FALSE TO 0
EQUATE PRICE TO INV_LINE(7), TAX TO 0.175
EQUATE DASHES TO -------
IF NO_CHARGE = TRUE THEN PRICE = 0
CRT Tax =:PRICE * TAX:CR:DASHES

EXECUTE
The EXECUTE or PERFORM statement allows the currently executing program to pause and execute any
other UNIX program, including another jBC program or a jBASE command.
Command Syntax
EXECUTE|PERFORM expression {CAPTURING variable} {RETURNING|SETTING variable}
{PASSLIST {expression}} {RTNLIST {variable}}
{PASSDATA variable} {RTNDATA variable}
Data, Dynamic Arrays and lists can be passed to programs written in jBC. Screen output and error messages can
be intercepted from any program.
Syntax Elements
The PERFORMed expression can be formed from any jBASE construct. The system will not verify that the
command exists before executing it. The command is executed by a new Bourne Shell (sh) by default. The shell
type can be changed by preceding the command with a CHAR(255) concatenated with either 'k', 'c', or 's' to
signify the Korn shell, C shell or Bourne Shell.
Variables used to pass data to the executed program should have been assigned to a value before they are used.
Any variable name may be used to receive data.
CAPTURING variable
The capturing clause will capture any output that the executing program would normally send to the terminal
screen and place it in the variable specified. Every newline normally sent to the terminal is replaced with a field
mark in the variable.

Programmers Reference Manual

2-65

jBC

RETURNING variable or SETTING variable

The returning and setting clauses are identical. Both clauses will capture the output associated with any error
messages the executing program issues. The first field of the variable will be set to the exit code of the program.
PASSLIST variable
The PASSLIST clause allows jBASE programs to exchange lists or dynamic arrays between them. The variable
should contain the list that the program wishes to pass to the jBASE program it is executing. The program to be
executed should be able to process lists, otherwise the list will just be ignored. If the variable name is not
specified then the clause will pass the default select list to the executing program.
RTNLIST variable
If the program executed sets up a list then the RTNLIST clause may be used to place that list into a specified
variable. If the variable is omitted then the list is placed in the default list variable.
PASSDATA variable
The data in the specified variable is passed to another jBC program. The executing jBC program should retrieve
the data using the COLLECTDATA statement.
RTNDATA variable
The RTNDATA statement returns any data passed from an executing jBC program in the specified variable. The
executing jBC program should use the RTNDATA statement to pass data back to the calling program.
Notes
The clauses may be specified in any order within the statement but only one of each clause may exist.
Examples
OPEN "DataFile" ELSE ABORT 201, "DataFile"
SELECT
PERFORM "MyProg" SETTING ErrorList PASSLIST
EXECUTE "ls" CAPTURING DirListing

EXIT( )
The EXIT statement is used to halt the execution of a program and return a numeric exit code to the parent
process. For compatibility with older versions of the language the EXIT statement may be used without an
expression. In this case it is synonymous with the BREAK statement (see earlier).
Command Syntax
EXIT (expression)
EXIT
Syntax Elements
Any expression provided must be parenthesised and must evaluate to a numeric result. The numeric result is
used as the UNIX exit code, which is returned to the parent process by the C function exit(). If the expression
does not evaluate to a numeric then the program will enter the debugger with a suitable error message.
Notes
The expression has been forced to be parenthesised to avoid confusion with the EXIT statement without an
expression as much as is possible. The authors apologise for having to provide two different meanings for the
same keyword.
Examples
READ Record FROM FileDesc, RecordKey ELSE

jBC

2-66

Programmers Reference Manual

CRT "Record ":RecordKey:" is missing"

EXIT(1)
END ELSE
CRT "All required records are present"
EXIT(0)
END

EXP( )
The EXP function returns the mathematical constant e to the specified power.
Command Syntax
EXP(expression)
Syntax Elements
The expression may consist of any form of jBC expression but should evaluate to a numeric argument or a
runtime error will occur and the program will enter the debugger.
Notes
The function will return a value that is accurate to as many decimal places as are specified by the PRECISION of
the program.
Examples
E10 = EXP(10)

;* Get e^10

EXTRACT
The EXTRACT function is an alternative method of accessing values in a dynamic array other than using the
<n,n,n> syntax described earlier.
Command Syntax
EXTRACT(expression1, expression2 {, expression3 {, expression4}})
Syntax Elements
Expression1 specifies the dynamic array to work with and will normally be a previously assigned variable. The
expressions 2 through 4 should all return a numeric value or a runtime error will occur and the program will
enter the debugger. Expression2 specifies the field to extract, expression3 the value to extract and expression4
the sub-value to extract.
Notes
Dynamic arrays are described in detail earlier in this chapter.
Examples
A = "0"; A<2> = "1"; A<3> = "2"
CRT EXTRACT(A, 2)
Will print the value '1' to the terminal display.

FIELD( )
The FIELD function will return a multi-character delimited field from within a string.
Command Syntax
FIELD(expression1, expression2, expression3)

Programmers Reference Manual

2-67

jBC

Syntax Elements
All three expressions within the function may evaluate to any argument type. Expression1 specifies the string to
search for the field. Expression2 specifies the character or characters that delimit fields within the string.
Expression3 specifies the field position to extract from the string.
Notes
The field delimiter may consist of more than a single character, allowing fields to be delimited by complex
codes.
Examples
Fields = "AAAA:BBJIMBB:CCCCC"
CRT FIELD(Fields, ":", 3)
CRT FIELD(Fields, "JIM", 1)
will display:
CCCCC
AAAA:BB
on the terminal

FIND
The FIND statement allows the location of a specified string within a dynamic array.
Command Syntax
FIND expression1 IN Var1 {, expression2}
SETTING Var2 {, Var3 {, Var4}} THEN | ELSE statement(s)
Syntax Elements
Expression1 evaluates to the string to compare every element of the dynamic array with. Var1 is the actual
dynamic array that will be searched. The FIND command will normally find the first occurrence of expression1
unless expression2 is specified. If specified then expression2 will cause a specific occurrence of expression1 to
located. The three variables Var2 through Var4 are used to record the Field, Value and Sub-Value positions in
which expression1 was found.
If expression1 is found in any element of Var1 then Vars 2, 3 and 4 are set to the position in which it was found
and any THEN clause of the statement is executed. If expression1 is not found within any element of the
dynamic array then Vars 2, 3 and 4 are undefined and the ELSE clause of the statement is executed.
Notes
The statement may omit either the THEN clause or the ELSE clause but may not omit both. It is valid for the
statement to contain both clauses if required.
Examples
Var = "ABC":VM:"JAC":AM:"CDE":VM:"WHO"
FIND "JAC" IN Var SETTING Ap, Vp THEN
CRT "JAC is in Field ":Ap:", value ":Vp
END ELSE
CRT "JAC could not be found"
END
Will display:
JAC is in Field 1, value 2
to the terminal.

jBC

2-68

Programmers Reference Manual

FINDSTR
The FINDSTR statement is used to locate a string as a substring of a dynamic array element. It is similar in
operation to the FIND statement (see earlier).
Command Syntax
FINDSTR expression1 IN Var1 {, expression2}
SETTING Var2 {,Var3 {, Var4}} THEN | ELSE statement(s)
Syntax Elements
Expression1 evaluates to the string to search every element of the dynamic array with. Var1 is the actual
dynamic array that will be searched. FINDSTR will normally locate the first occurrence of expression1 unless
expression2 is specified. If specified then expression2 will cause a specific occurrence of expression1 to be
located. The three variables Var2 through Var4 are used to record the Field, Value and Sub-Value positions in
which expression1 was found.
If expression1 is found as a substring of any element of Var1 then Vars 2, 3 and 4 are set to the position in which
it was found and the THEN clause of the statement is executed if it is present. If expression1 is not found within
any element of the dynamic array then Vars 2,3 and 4 are undefined and the ELSE clause of the statement is
executed.
Notes
The statement may omit either the THEN clause or the ELSE clause but may not omit both. It is valid for the
statement to contain both clauses if required.
Examples
Var = "ABC":VM:"OJACKO":AM:"CDE":VM:"WHO"
FINDSTR "JAC" IN Var SETTING Ap, Vp THEN
CRT "JAC is within Field ":Ap:", value ":Vp
END ELSE
CRT "JAC could not be found"
END
Would display
JAC is within Field 1, value 2
to the terminal.

FOOTING
The FOOTING statement causes all subsequent output to the terminal to be halted at the end of each output
page. The statement allows an expression to be evaluated and displayed at the foot of each page. If output is
currently being sent to the terminal, the output will be paused until a carriage return is entered at the terminal
(unless the N option is specified either in the current HEADING or in this FOOTING).
Command Syntax
FOOTING expression
Syntax Elements
The expression should evaluate to a string that will be printed at the bottom of every page of output. The string
may contain a number of special characters that are interpreted and replaced in the string before it is printed. The
following characters have special meaning within the string:
'C{n}'

Centre the line. If n is specified the output line is assumed to be n characters long.

'D' or \\

Replace with the current date.

'L' or ]

Replace with the newline sequence.

Programmers Reference Manual

2-69

jBC

'N'

Terminal output does not pause at the end of each page.

'P' or ^

Replace with the current page number.

'PP' or ^^ Replace with the current page number in a field of 4 characters. The field is right justified.
'T' or \

Replace with the current time and date.

''

Replace with a single ' character.

Notes
If output is being directed to the printer (a PRINTER ON) statement is in force then output sent to the terminal
with the CRT statement is not paged. If output is being sent to the terminal then all output is paged.
Example
FOOTING "Programming staff by weight

Page 'P'"

FOR
The FOR statement allows the programming of looping constructs within the program. The loop is controlled by
a counting variable and may be terminated early by expressions tested after every iteration.
Command Syntax
FOR Var=expression1 TO expression2 {STEP expression3}
{WHILE | UNTIL expression4}...NEXT {Var}
Syntax Elements
Var is the counting variable used to control the loop. The first time the loop is entered Var is assigned the value
of expression1, which must evaluate to a numeric value. After every iteration of the loop Var is automatically
incremented by 1. Expression2 must also evaluate to a numeric value as it causes the loop to terminate when the
value of Var is greater than the value of this expression. Expression2 is evaluated at the start of every iteration of
the loop and compared with the value of expression1.
If the STEP expression3 clause is included within the statement, Var will automatically be incremented by the
value of expression3 after each iteration of the loop. Expression3 is evaluated at the start of each iteration.
Expression3 may be negative, in which case the loop will terminate when Var is less than expression2.
The statement may optionally include either a WHILE or UNTIL clause (not both), which will be evaluated
before each iteration of the loop. When the WHILE clause is specified the loop will only continue with the next
iteration if Expression4 evaluates to Boolean TRUE. When the UNTIL clause is specified the loop will only
continue with the next iteration if Expression4 evaluates to Boolean FALSE.
Notes
Because expression2 and expression3 must be evaluated upon each iteration of the loop you should only code
complex expressions here if they may change within each iteration. If the values they yield will not change then
you should assign the value of these expressions to a variable before coding the loop statement. Expressions 3
and 4 should then be replaced with these variables. This can offer large performance increases where complex
expressions are being used.
See also:

BREAK, CONTINUE.

Examples
Max =DCOUNT(BigVar, CHAR(254))
FOR I = 1 TO Max STEP 2 WHILE BigVar<I> LT 25
BigVar<I> += 1
NEXT I
This example will increment every second field of the variable BigVar but the loop will terminate early if the
current field to be incremented is not numerically less than 25.

jBC

2-70

Programmers Reference Manual

GETCWD( )
The GETCWD function is a UNIX related function that allows a jBC program to determine the current working
directory of the program. This will normally be the directory from which the program was executed but may
have been changed with the CHDIR command.
Command Syntax
GETCWD(Var)
Syntax Elements
When executed the Var will be set to the name of the current working directory. The function itself returns a
Boolean TRUE or FALSE value indicating whether the command was successful or not.
Notes
Refer to your UNIX documentation (sh is a good place to start), for more information on the concept of the
current working directory.
Examples
IF GETCWD(Cwd) THEN
CRT "Current Working Directory = ":Cwd
END ELSE
CRT "Could not determine CWD!"
END

GETENV( )
All UNIX processes have an environment associated with them that contains a number of variables indicating the
state of various UNIX parameters. The GETENV function allows a jBC program to determine the value of any
of the environment variables associated with it.
Command Syntax
GETENV( expression, Variable)
Syntax Elements
The expression should evaluate to the name of the environment variable whose value is to be returned. The
function will then assign the value of the environment variable to Variable. The function itself returns a Boolean
TRUE or FALSE value indicating the success or failure of the function.
Notes
See the UNIX documentation for the Bourne shell (sh) for information on environment variables. See earlier in
this manual for information regarding environment variables unique to the jBASE system.
See also

PUTENV

Examples
IF GETENV("PATH", ExecPath) THEN
CRT "Execution path is ":ExecPath
END ELSE
CRT "Execution path is not set up"
END

GETLIST
GETLIST allows the program to retrieve a previously stored list (perhaps created with the SAVE-LIST
command), into a jBCvariable.

Programmers Reference Manual

2-71

jBC

Command Syntax
GETLIST expression TO variable1 {SETTING variable2} THEN|ELSE statements
Syntax Elements
Variable1 is the variable into which the list will be read.
Expression should evaluate to the name of a previously stored list to retrieve, or null. If expression evaluates to
null, the current default external select list (generated by a previous SELECT command for example) will be
retrieved.
Variable2 (if specified) will be set to the number of elements in the list.
If the statement succeeds in retrieving the list, then the statements associated with any THEN clause will be
executed. If the statement fails to find the list, then the statements associated with any ELSE clause will be
executed.
Notes
The GETLIST statement is identical in function to the READLIST statement.
See also:

WRITELIST

Examples
* Find the list first
GETLIST "MyList" TO MyList ELSE STOP
LOOP
* Loop until there are no more elements
WHILE READNEXT Key FROM MyList DO
......
REPEAT

GOSUB
The GOSUB statement causes execution of a local subroutine, after which execution will continue with the next
line of code.
Command Syntax
GOSUB label
Syntax Elements
The label should refer to an existent label within the current source code. This label identifies the start of a local
subroutine. Label formats are defined earlier in this chapter.
Examples
GOSUB Initialise ;* Open files etc..
GOSUB Main
;* Perform main program
GOSUB Finish
;* Close files etc..
STOP
....
Initialise: * Open files
OPEN.......
RETURN
....
Main:
* Main execution loop
.......RETURN
Finish:
* Clean up after execution
......RETURN

jBC

2-72

Programmers Reference Manual

GO{TO}
The GOTO statement causes program execution to jump to the code at a specified label.
Command Syntax
GO{TO} Label
Syntax Elements
The label should refer to an existing label within the current source code.
Notes
The use of the GOTO command is not recommended as it obscures the readability of code and therefore is a
hindrance to maintainability. All programs written using the GOTO construct can be written using structured
statements such as LOOP and FOR. Opinions on this are divided but the consensus is that GOTO should be
avoided.
One possibly acceptable use of the GOTO statement is to transfer execution to an error handler upon detection
of a fatal error that will cause the program to terminate.
Examples
GOTO Exception
;* Jump to the exception handler
.....
Exception:
* Exception handler
....STOP

GROUP( )
The GROUP function is an extension of the FIELD function allowing the return of a group of fields rather than
just a single one.
Command Syntax
GROUP(Expression1, Expression2, Expression3, Expression4)
Syntax Elements
Expression1 evaluates to the string containing fields to be extracted. Expression2 evaluates to the character(s)
delimiting each field within Expression1. Expression3 should evaluate to a numeric value specifying the number
of the first field to extract from Expression1. Expression4 evaluates to a numeric value specifying the number of
fields to extract as a group.
Notes
Expression2 may evaluate to more than a single character allowing fields to be delimited with complex
expressions.
Examples
A = "123:-456:-789:-987:-"
CRT GROUP(A, ":-", 2, 2)
This example will display
456:-789
on the terminal being the second and third fields and their delimiter within variable A.

Programmers Reference Manual

2-73

jBC

HEADING
The HEADING statement causes all subsequent output to the terminal to be halted at the end of each page. The
statement allows an expression to be evaluated and displayed at the top of each page. If output is currently being
sent to the terminal, output is paused until a carriage return is entered at the terminal - unless the N option is
specified.
Command Syntax
HEADING expression
Syntax Elements
The expression should evaluate to a string that will be printed at the top of every page of output. The string may
contain a number of special characters that are interpreted and replaced in the string before it is printed. The
following characters have special meaning within the string:
'C{n}'

Centre the line. If n is specified the output line is assumed to be n characters long.

'D' or \\

Replace with the current date.

'L' or ]

Replace with the newline sequence.

'N'

Terminal output does not pause at the end of each page.

'P' or ^

Replace with the current page number.

'PP' or ^^ Replace with the current page number in a field of 4 characters. The field is right justified.
'T' or \

Replace with the current time and date.

''

Replace with a single ' character.

Notes
If output is being directed to the printer (a PRINTER ON statement is in force), output sent to the terminal with
the CRT statement will not be paged. If output is being sent to the terminal, all output will be paged unless you
specify the N option.
Examples
HEADING "Programming staff by size of waist Page 'P'"

ICONV( )
The ICONV function converts data in external form such as dates to their internal form.
Command Syntax
ICONV(expression1, expression2)
Syntax Elements
Expression1 evaluates to the data that the conversion is to be performed upon. Expression2 should evaluate to
the conversion code that is to be performed against the data.
Notes
The range of conversion codes available are defined elsewhere in this manual. Also see OCONV
Examples
InternalDate = ICONV("14 JUL 1964", "D")
In this example ICONV returns the internal form of the date July 14, 1964.

jBC

2-74

Programmers Reference Manual

IF
The IF statement is used to allow other statements to be conditionally executed.
Command Syntax
IF expression THEN|ELSE statements
Syntax Elements
The expression will be evaluated to a value of Boolean TRUE or FALSE. If the expression is TRUE then the
statements defined by the THEN clause will be executed (if present). If the expression is FALSE then the
statements defined by the ELSE clause are executed.
The THEN and ELSE clauses may take two different forms being single and multiple line statements.
The simplest form of either clause is of the form:
IF A THEN CRT A
or
IF A ELSE CRT A
but the clauses may be expanded to enclose multiple lines of code using the END keyword as so:
IF A THEN
A = A*6
CRT A
END ELSE
A = 76
CRT A
END
The single and multi-line versions of either clause may be combined to make complex combinations of the
command. For reasons of readability it is suggested that where both clauses are present for an IF statement that
the same form of each clause is coded.
Notes
IF statements can be nested within either clause to any number of levels.
Examples
CRT "Are you sure (Y/N) ":
INPUT Answer,1_
IF OCONV(Answer, "MCU")= "Y" THEN
GOSUB DeleteFiles
CRT "Files have been deleted"
END ELSE
CRT "File delete was ignored"
END

IN
The IN statement allows the program to receive raw data from the input device, which is normally the terminal
keyboard, one character at a time.
Command Syntax
IN Var {FOR expression THEN|ELSE statements}
Syntax Elements
Var will be assigned the numeric value (0 - 255 decimal) of the next character received from the input device.
The statement will normally wait indefinitely (block) for a character from the keyboard.

Programmers Reference Manual

2-75

jBC

Specifying the FOR clause to the IN statement allows the statement to stop waiting for keyboard after a
specified amount of time. The expression should evaluate to a numeric value, which will be taken as the number
of deci-seconds (tenths of a second) to wait before abandoning the input.
The FOR clause must have either or both of the THEN or ELSE clauses. If a character is received from the
input device before the time-out period then Var is assigned its numeric value and the THEN clause is executed
(if present). If the input statement times out before a character is received then Var is unaltered and the ELSE
clause is executed (if present).
Examples
Char2 = ""
IN Char
IF Char = 27 THEN
;* ESC seen
IN Char2 FOR 20 THEN
;* Function Key?
Char2 = CHAR(Char2) ;* ASCII value
END
END
Char = CHAR(Char):Char2
;* Return key sequence

INDEX( )
The INDEX function will return the position of a character or characters within another string.
Command Syntax
INDEX(expression1, expression2, expression3)
Syntax Elements
Expression1 evaluates to the string to be searched. Expression2 evaluates to the string or character that will be
searched for within expression1. Expression3 should evaluate to a numeric value and specifies which occurrence
of expression2 should be searched for within expression1.
Notes
If the specified occurrence of expression2 cannot be found in expression1 then 0 is returned.
Examples
ABet = "abcdefghijklmnopqrstuvwxyzabc"
CRT INDEX(ABet, 'a', 1)
CRT INDEX(ABet, 'a', 2)
CRT INDEX(ABet, 'jkl', 1)
The above example will print
1
27
10
to the terminal.

INPUT
The INPUT statement allows the program to collect data from the current input device, which will normally be
the terminal keyboard but may be stacked input from the same or separate program.
Command Syntax
INPUT {@(expression1{, expression2)}{:} Var
{{, expression3}, expression4} {:}{_} {WITH expression5}
{FOR expression6 THEN|ELSE statements}

jBC

2-76

Programmers Reference Manual

Syntax Elements
@(expression1, expression2) allows the screen cursor to be positioned to the specified column and row before
the input prompt is sent to the screen. The syntax for this is exactly the same as for the @( ) function described
earlier.
Var is the variable in which the input data is to be stored.
Expression3, when specified, should evaluate to a sequence of 1 to 3 characters. The first character will be
printed expression4 times to define the field on the terminal screen. At the end of the input if less than
expression4 characters were input then the rest of the field is padded with the second character if it was supplied.
If the third character is supplied then the cursor will be positioned after the last character input rather than at the
end of the input field.
Expression4, when specified, should evaluate to a numeric value. This will cause input to be terminated with an
automatic newline sequence after exactly this number of characters has been input. If the _ option is specified
with expression3 then the automatic newline sequence is not specified but any subsequent input characters are
belled to the terminal and thrown away.
The : option, when specified, suppress the echoing of the newline sequence to the terminal. This will leave the
cursor positioned after the last input character on the terminal screen.
WITH expression5 allows the default input delimiter (the newline sequence) to be changed. When specified,
expression5, should evaluate to a string of up to 256 characters, each of which may delimit the input field. If this
clause is used then the newline sequence is removed as a delimiter and must be specified explicitly within
expression5 as CHAR(10).
The FOR clause allows the INPUT statement to time out after a specified waiting period instead of blocking as
normal. Expression6 should evaluate to a numeric value, which will be taken as the number of deci-seconds
(tenths of a second) to wait before timing out. The time-out value is used as the time between each keystroke and
should a time-out occur, Var will hold the characters that were input until the time-out.
The FOR clause requires either or both of the THEN and ELSE clauses. If no time-out occurs the THEN clause
is taken. If a time-out does occur the ELSE clause is taken.
Notes
The INPUT statement will always examine the data input stack before requesting data from the input device. If
data is present on the stack then it is used to satisfy INPUT statements one field at a time until the stack is
exhausted. Once exhausted, the INPUT statement will revert to the input device for further input.
There is no way (by default) to input a null field to the INPUT@ statement. If the INPUT@ statement receives
the newline sequence only as input, then the Var will be unchanged. The INPUTNULL statement should be
used to define a character that indicates a NULL input (see later).
Examples
Answer = ""
LOOP
WHILE Answer = "" DO
INPUT Answer,1 FOR 10 ELSE
GOSUB UpdateClock
END
REPEAT
The above example attempts to read a single character from the input device for 10 deci-seconds (1 second). The
LOOP will exit when a character has been input otherwise every second it will call the local subroutine
UpdateClock.

INPUTNULL
The INPUTNULL statement allows the definition of a character that will allow a null input to be seen by the
INPUT@ statement.

Programmers Reference Manual

2-77

jBC

Command Syntax
INPUTNULL expression
Syntax Elements
The expression should evaluate to a single character. Subsequently, any INPUT@ statement that sees only this
character input before the new-line sequence will NULL the variable in which input is being stored.
If expression evaluates to the NULL string "" then the default character of _ is used to define a NULL input
sequence.
Notes
The INPUT statement does not default to accepting the _ character as a NULL input, the programmer must
explicitly allow this with the statement:
INPUTNULL ""
Examples
INPUTNULL "&"
INPUT @(10,10):Answer,1
IF Answer = "" THEN
CRT "A NULL input was received"
END

INS
The INS statement allows the insertion of elements into a dynamic array.
Command Syntax
INS expression BEFORE Var<expression1{, expression2{, expression3}}>
Syntax Elements
Expression evaluates to the element to be inserted in the dynamic array.
Expression1, expression2 and expression3 should all evaluate to numeric values and specify the Field, Value and
Sub-Value before which the new element is to be inserted.
Notes
Specifying a negative value to any of expressions 1 through 3 will cause the element to appended as the last
Field, Value or Sub-Value rather than at a specific position. Only one of the expressions may be negative
otherwise the first negative value is used correctly but the others are treated as the value 1.
The statement will insert NULL Fields, Values or Sub-Values accordingly if any of the specified insertion points
exceeds the number currently existing.
Example
Values = ""
FOR I = 1 TO 50
INS I BEFORE Values<-1>
NEXT I
FOR I = 2 TO 12
INS I*7 BEFORE Values<7,I>
NEXT I

INSERT
The INSERT command is the function form of the INS statement, which should be used in preference to this
function.

jBC

2-78

Programmers Reference Manual

Command Syntax
INSERT(expression1, expression2{, expression3{, expression4}} ;expression5)
Syntax Elements
Expression1 evaluates to a dynamic array in which to insert a new element and will normally be a variable.
Expression2, Expression3 and Expression4 should evaluate to numeric values and specify the Field, Value and
Sub-Value before which the new element will be inserted.
Expression5 evaluates to the new element to be inserted in expression1.
Notes
See Also

INS

Examples
A = INSERT(B, 1,4; "Field1Value4")

INT( )
The INT function truncates a numeric value into its nearest integer form .
Command Syntax
INT( expression)
Syntax Elements
The expression should evaluate to a numeric value. The function will then return the integer portion of the value.
Notes
The function works by truncating the fractional part of the numeric value rather than by standard mathematical
rounding techniques. Therefore INT(9.001) and INT(9.999) will both return the value 9.
Examples
CRT INT(22/7)
Will print the value 3
on the terminal screen.

LEN( )
The LEN function returns the character length of the supplied expression.
Command Syntax
LEN( expression)
Syntax Elements
Expression can evaluate to any type and the function will convert it to a string automatically.
Examples
Lengths = ""
FOR I = 1 TO 50
Lengths<I> = LEN(Values<I>)
NEXT I

Programmers Reference Manual

2-79

jBC

LN( )
The LN function returns the value of the natural logarithm of the supplied value.
Command Syntax
LN( expression)
Syntax Elements
The expression should evaluate to a numeric value. The function will then return the natural logarithm of that
value.
Notes
The natural logarithm is calculated using the mathematical constant e as a number base.
Examples
A = LN(22/7)

LOCATE
The LOCATE statement finds the position of an element within a specified dimension of a dynamic array.
Command Syntax
LOCATE expression1 IN expression2{<expression3{, expression4}>}
{, expression5} {BY expression6} SETTING Var THEN|ELSE statement(s)
Syntax Elements
Expression1 evaluates to the string that will be searched for in Expression2.
Expression2 evaluates to the dynamic array within which expression1 will be searched for.
Expression3 and expression4, when specified, cause a value or subvalue search respectively.
Expression5 indicates the field, value or subvalue from which the search will begin.
BY expression6 causes the search to expect the elements to be arranged in a specific order, which can
considerably improve the performance of some searches. The available string values for Expression6 are:
"AL" Values are in ascending alphanumeric order.
"AR" Values are in right justified, then ascending order.
"DL" Values are in descending alphanumeric order.
"DR" Values are in right justified, then descending order.
Var will be set to the position of the Field, Value or Sub-Value in which expression1 was found if indeed, it was
found. If it was not found and expression6 was not specified then Var will be set to one position past the end of
the searched dimension. If expression6 did specify the order of the elements then Var will be set to the position
before which the element should be inserted to retain the specified order.
The statement must include one of or both of the THEN and ELSE clauses. If expression1 is found in an
element of the dynamic array the statements defined by the THEN clause are executed. If expression1 is not
found in an element of the dynamic array the statements defined by the ELSE clause are executed.
Notes
See also

FIND

FINDSTR

Examples
Name = "Jim"
LOCATE Name IN ForeNames BY 'AL' SETTING Pos ELSE
INS Name BEFORE ForeNames<Pos>
END

jBC

2-80

Programmers Reference Manual

LOCK
The LOCK statement will attempt to set an execution lock thus preventing any other jBC program that respects
that lock to wait until this program has released it.
Command Syntax
LOCK expression {THEN|ELSE statements}
Syntax Elements
The expression should evaluate to a numeric value between 0 and 255 (63 in R83 import mode).
The statement will execute the THEN clause (if defined) providing the lock could be taken. If the LOCK is
already held by another program and an ELSE clause was provided then the statements defined by the ELSE
clause are executed. If no ELSE clause was provided with the statement then it will block (hang) until the lock
has been released by the other program.
Notes
See also

UNLOCK

If the program was compiled with the environment variable JBCEMULATE set to R83, the number of execution
locks is limited to 64. If an execution lock greater than this number is specified, the actual lock taken is the
specified number modulo 64.
Examples
LOCK 32 ELSE
CRT "This program is already executing!"
STOP
END

LOOP
The LOOP construct allows the programmer to specify loops with multiple exit conditions.
Command Syntax
LOOP statements1 WHILE|UNTIL expression DO statements2 REPEAT
Syntax Elements
Statements1 and 2 consist of any number of standard statements include the LOOP statement itself, thus
allowing nested loops. Statements1 will always be executed at least once, after which the WHILE or UNTIL
clause is evaluated.
Expression is tested for Boolean TRUE/FALSE by either the WHILE clause or the UNTIL clause. When tested
by the WHILE clause statements2 will only be executed if expression is Boolean TRUE. When tested by the
UNTIL clause, statements2 will only be executed if the expression evaluates to Boolean FALSE.
REPEAT causes the loop to start again with the first statement following the LOOP statement.
Notes
See also

BREAK

CONTINUE

Examples
LOOP WHILE B < Max DO
Var<B> = B++ *6
REPEAT
LOOP
CRT "+":
WHILE READNEXT KEY FROM List DO

Programmers Reference Manual

2-81

jBC

READ Record FROM FILE, KEY ELSE CONTINUE

Record<1> *= 6
REPEAT
CRT

MAT
The MAT command is used to either assign every element in a specified array to a single value or to assign the
entire contents of one array to another.
Command Syntax
MAT Array = expression
MAT Array1 = MAT Array2
Syntax Elements
Array, Array1 and Array2 are all pre-dimensioned arrays declared with the DIM() statement. Expression can
evaluate to any data type.
Notes
Note that if any element of the array Array2 has not been assigned a value then a runtime error message will
occur. This can be avoided by coding the statement MAT Array2 = "" after the DIM statement.
Examples
001 DIM A(45), G(45)
002 MAT G = "Array value"
003 MAT A = MAT G

MATCH{ES}
The MATCH or MATCHES function allows pattern matching to be applied to an expression.
Command Syntax
expression1 MATCHES expression2
Syntax Elements
Expression1 may evaluate to any type. Expression2 should evaluate to a valid pattern matching string as
described below. Expression1 is then matched to the pattern supplied and a value of Boolean TRUE is returned
if the pattern is matched. A value of Boolean FALSE is returned if the pattern is not matched.
Expression2 can contain any number of patterns to match separated by value marks. The value mark implies a
logical OR of the specified patterns and the match will evaluate to Boolean TRUE if expression1 matches any of
the specified patterns.
Notes
Pattern matching strings are constructed from the rule table shown below. When reading the table n refers to any
integer number.

jBC

Pattern

Explanation

nN

This construct matches a sequence of n digits.

nA

This construct matches a sequence of n alpha

characters.

2-82

Programmers Reference Manual

nC

This construct matches a sequence of n alpha

characters or digits.

nX

This construct matches a sequence of any characters

"string"

This construct matches the character sequence string

exactly.

The pattern will be applied to all characters in expression1 and it must match all characters in the expression to
evaluate as Boolean TRUE.
The integer value n can be specified as 0. This will cause the pattern to match any number of characters of the
specified type.
Examples
IF Var MATCHES "0N" THEN CRT "A match!"
matches if all characters in Var are numeric or Var is a null string.
IF Var MATCHES "0N'.'2N".......
matches if Var contains any number of numerics followed by the . character followed by 2 numeric characters.
e.g. 345.65 or 9.99
Pattern = "4X':'6N'; 2A
Matched = Serno MATCHES Pattern
matches if the variable Serno consists of a string of 4 arbitrary characters followed by the : character then 6
numerics then the ; character and then 2 alphabetic characters. e.g. 1.2.:123456;A2 or 17st:456789;FB

MATBUILD
Command Syntax
The MATBUILD statement is used to create a dynamic array out of a dimensioned array.
MATBUILD variable FROM array{, expression1{, expression2}}
{USING expression3}
Syntax Elements
Variable is the jBC variable into which the created dynamic array will be stored. Array is a previously
dimensioned and assigned matrix from which the dynamic array will be created. Expression1 and expression2
should evaluate to numeric integers. Expression1 specifies which element of the array the extraction will start
with, expression2 specifies which element of the array the extraction will end with (inclusive).
By default, each array element is separated in the dynamic array by a field mark. By specifying expression3, the
separator character can be changed. If expression3 evaluates to more than a single character, only the first
character of the string is used.
Notes
When specifying start and end positions with multi-dimensional arrays, it is necessary to expand the matrix into
its total number of variables to calculate the correct element number. See the information about dimensioned
arrays earlier in this chapter for detailed instructions on calculating element numbers.
Examples
DIM A(40)
MATBUILD Dynamic FROM A,3,7 USING ':'
Builds a 5 element string separated by a : character.
MATBUILD Dynamic FROM A
Builds a field mark separated dynamic array from every element contained in the matrix A.

Programmers Reference Manual

2-83

jBC

MATPARSE
Command Syntax
The MATPARSE statement is used to assign the elements of a matrix from the elements of a dynamic array.
MATPARSE array{, expression1{, expression2}} FROM variable1
{USING expression3} SETTING variable2
Syntax Elements
Array is a previously dimensioned matrix, which will be assigned to from each element of the dynamic array.
Variable1 is the jBC variable from which the matrix array will be stored. Expression1 and expression2 should
evaluate to numeric integers. Expression1 specifies which element of the array the assignment will start with,
expression2 specifies which element of the array the assignment will end with (inclusive).
By default, each array element in the dynamic array is assumed to be separated by a field mark. By specifying
expression3, the separator character can be changed. If expression3 evaluates to more than a single character,
only the first character of the string is used.
As assignment will stop when the contents of the dynamic array have been exhausted, it can be useful to
determine the number of matrix elements that were actually assigned to. If the SETTING clause is specified then
variable2 will be set to the number of elements of the array that were assigned to.
Notes2
When specifying start and end positions with multi-dimensional arrays, it is necessary to expand the matrix into
its total number of variables to calculate the correct element number. See the information about dimensioned
arrays earlier in this section for detailed instructions on calculating element numbers.
Examples
DIM A(40)
MATPARSE A,3,7 FROM Dynamic
Assign 5 elements of the array starting at element 3.

MATREAD
The MATREAD statement allows a record stored in a jBASE file to be read and mapped directly into a
dimensioned array.
Command Syntax
MATREAD array FROM {variable1,}expression {SETTING setvar} {LOCKED statements} {THEN|ELSE
statements}
Syntax Elements
Array should be a previously dimensioned array, which will be used to store the record to be read. Variable1, if
specified, should be a jBC variable that has previously been opened to a file using the OPEN statement. If
variable1 is not specified then the default file is assumed (see OPEN statement). The expression should evaluate
to a valid record key for the file.
If the record is found and can be read from the file then it is mapped into array and the THEN statements are
executed (if any). If the record cannot be read from the file for some reason then array is unchanged and the
ELSE statements (if any) are executed.

It is our opinion that MATBUILD and MATPARSE have been named the wrong way round, but imagine the confusion if we had changed them!

jBC

2-84

Programmers Reference Manual

If the record could not be read because another process already had a lock on the record then one of two actions
is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed.
If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other
process.
If a LOCKED clause is used and the read is successful, a lock will be set.
If the SETTING clause is specified, setvar will be set to the number of fields in the record on a successful read.
If the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The record is mapped into the array using a predefined algorithm. The record is expected to consist of a number
of Field separated records, which are then assigned one at a time to each successive element of the matrix. See
the notes on matrix organisation earlier in this section for details of multi dimensional arrays.
If there were more fields in the record than elements in the array then the final element of the array will be
assigned all remaining fields. If there were fewer fields in the record than elements in the array then remaining
array elements will be assigned a null value.
Note that if multivalues are read into an array element they will then be referenced individually as:
Array(n)<1,m>
not:

Array(n)<m>

Examples
MATREAD Xref FROM CFile, "XREF" ELSE MAT Xref = ""
MATREAD Ind FROM IFile, "INDEX" ELSE MAT Ind = 0

MATREADU
The MATREADU statement allows a record stored in a jBASE file to be read and mapped directly into a
dimensioned array. The record will also be locked for update by the program.
Command Syntax
MATREADU array FROM {variable1,}expression {SETTING setvar} {LOCKED statements}
{THEN|ELSE statements}
Syntax Elements
Array should be a previously dimensioned array, which will be used to store the record to be read. Variable1, if
specified, should be a jBC variable that has previously been opened to a file using the OPEN statement. If
variable1 is not specified then the default file is assumed (see OPEN statement). The expression should evaluate
to a valid record key for the file.
If the record is found and can be read from the file then it is mapped into array and the THEN statements are
executed (if any). If the record cannot be read from the file for some reason then array is unchanged and the
ELSE statements (if any) are executed.
If the record could not be read because another process already had a lock on the record then one of two actions
is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed.
If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other
process.
If the SETTING clause is specified, setvar will be set to the number of fields in the record on a successful read.
If the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error

Programmers Reference Manual

2-85

jBC

24576 Permission denied

32768 Physical I/O error or unknown error
Notes
The record is mapped into the array using a predefined algorithm. The record is expected to consist of a number
of Field separated records, which are then assigned one at a time to each successive element of the matrix. See
the notes on matrix organisation earlier in this section for details of the layout of multi dimensional arrays.
If there were more fields in the record than elements in the array then the final element of the array will be
assigned all remaining fields. If there were fewer fields in the record than elements in the array then remaining
array elements will be assigned a null value.
Note that if multivalues are read into an array element they will then be referenced individually as:
Array(n)<1,m>
not:

Array(n)<m>

Examples
MATREADU Xref FROM CFile, "XREF" ELSE MAT Xref = ""
MATREADU Ind FROM IFile, "INDEX" LOCKED
GOSUB InformUserLock
;* Say it is locked
END THEN
GOSUB InformUserOk ;* Say we got it
END ELSE
MAT Ind = 0
;* It was not there
END

MATWRITE
The MATWRITE statement transfers the entire contents of a dimensioned array to a specified record on disc.
Command Syntax
MATWRITE array ON {variable,}expression {SETTING setvar} {ON ERROR statements} {THEN|ELSE
statements}
Syntax Elements
Array should be a previously dimensioned and initialised array. If specified, variable should be a previously
opened file variable (i.e. the subject of an OPEN statement). If variable is not specified the default file variable
is used. Expression should evaluate to the name of the record in the file.
The THEN|ELSE clause is optional on the MATWRITE statement. If the write is successful, the THEN
statements will be executed. If the write fails (because of security permissions for instance), the ELSE
statements are executed.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The compiler will check that the variable specified is indeed an array and has been dimensioned before its use in
the statement.
Examples
DIM A(8)
MAT A = 99
....

jBC

2-86

Programmers Reference Manual

MATWRITE A ON "NewArray" ELSE

CRT "Permission denied!"
STOP
END
...
MATWRITE A ON RecFile, "OldArray"

MATWRITEU
The MATWRITEU statement transfers the entire contents of a dimensioned array to a specified record on file,
in the same manner as the MATWRITE statement. An existing record lock will be preserved.
Command Syntax
MATWRITEU array ON {variable,}expression {SETTING setvar} {ON ERROR statements}
{THEN|ELSE statements}
Syntax Elements
Array should be a previously dimensioned and initialised array. If specified, variable should be a previously
opened file variable (i.e. the subject of an OPEN statement). If variable is not specified the default file variable
is used. Expression should evaluate to the name of the record in the file.
The THEN|ELSE clause is optional on the MATWRITE statement. If the write is successful, the THEN
statements will be executed. If the write fails (because of security permissions for instance), the ELSE
statements are executed.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The compiler will check that the variable specified is indeed an array and has been dimensioned before its use in
the statement.
Examples
DIM A(8)
MAT A = 99
....
MATWRITEU A ON "NewArray"

MOD( ) and REM( )

The MOD function returns the arithmetic modulo of two numeric expressions.
Command Syntax
MOD(expression1, expression2)
Syntax Elements
Both expression1 and expression2 should evaluate to numeric expressions or a runtime error will occur.
Notes
The modulo is calculated as the remainder of expression1 divided by expression2.
If expression2 evaluates to 0, then the value of expression1 is returned.
Examples
FOR I = 1 TO 10000

Programmers Reference Manual

2-87

jBC

IF MOD(I, 1000) = 0 THEN CRT "+":

NEXT I
sends a '+' to the screen every 1000 iterations.

NOT( )
The NOT function is used to invert the Boolean value of an expression. It useful for explicitly testing for a false
condition.
Command Syntax
NOT(expression)
Syntax Elements
Expression may evaluate to any Boolean result.
Notes
The NOT function will return Boolean TRUE if the expression returned a Boolean FALSE. It will return
Boolean FALSE of the expression returned a Boolean TRUE.
The NOT function is useful for explicitly testing for the false condition of some test and can clarify the logic of
such a test.
Examples
EQU Sunday TO NOT(MOD(DATE(), 7))
IF Sunday THEN
CRT "It is Sunday!"
END
In this example the expression MOD(DATE(),7) will return 0 (FALSE) if the day is Sunday and 1 to 6 (TRUE)
for the other days. To explicitly test for the day Sunday we need to invert the result of the expression. BY using
the NOT function we return a 1 (TRUE) if the day is Sunday and 0 (FALSE) for all other values of the
expression.

NULL
The NULL statement performs no function but can be useful in clarifying syntax and where the language
requires a statement but the programmer does not wish to perform any actions.
Command Syntax
NULL
Syntax Elements
None.
Examples
LOCATE A IN B SETTING C ELSE NULL

NUM( )
The NUM function is used to test arguments for numeric values.
Command Syntax
NUM(expression)
Syntax Elements
Expression may evaluate to any data type.

jBC

2-88

Programmers Reference Manual

Notes
If every character in expression is found to be numeric then NUM returns a value of Boolean TRUE. If any
character in expression is found not to be numeric then a value of Boolean FALSE is returned.
Note that to execute user code migrated from older systems correctly, the NUM function will accept both a null
string and the single characters '.', +, and - as being numeric.
Note if running jBC in ROS mode the . , + and - characters would not be considered numeric.
Examples
LOOP
INPUT Answer,1
IF NUM(Answer) THEN BREAK
REPEAT

;* Exit loop if numeric

OCONV( )
The OCONV statement is used to convert internal representations of data to their external form.
Command Syntax
OCONV(expression1, expression2)
Syntax Elements
Expression1 may evaluate to any data type but should be relevant to the conversion. Expression2 should evaluate
to a conversion code from the list below. Alternatively, expression2 may evaluate to a user exit known to the
jBC language or supplied by the user (see external interfaces documentation).
Notes
OCONV will return the result of the conversion of expression1 by expression2. Valid conversion codes are
shown below:
Conversion
D{n{c}}

Action
Converts an internal date to an external date format. The numeric argument
n specifies the field width allowed for the year and can be 0 to 4 (default 4).
The character c causes the date to be return in the form ddcmmcyyyy. If it is
not specified the month name is return in abbreviated form.

DI

Allow the conversion of an external date to the internal format even though
an output conversion is expected.

DD

Returns the day in the current month.

DM

Returns the number of the month in the year.

DMA

Returns the name of the current month.

DJ

Returns the number of the day in the year (0-366).

DQ

Returns the quarter of the year as a number 1 to 4

DW

Returns the day of the week as a number 1 to 7 (Monday is 1).

DWA

Returns the name of the day of the week.

DY{n}

Returns the year in a field of n characters.

Given a prospective filename for a command such as CREATE-FILE this

conversion will return a filename that is acceptable to the version of UNIX
jBASE is running on.

MCA

Removes all but alphabetic characters from the input string.

MC/A

Removes all but the NON alphabetic characters in the input string.

MCN

Removes all but numeric characters in the input string

Conversion
MC/N

Action
Removes all but NON numeric characters in the input string

Programmers Reference Manual

2-89

jBC

MCB

Returns just the alphabetic and numeric characters from the input string

MC/B

Remove the alphabetic and numeric characters from their input string.

MCC;s1;s2

Replaces all occurrences of string s1 with string s2

MCL

Converts all upper case characters in the string to lower case characters

MCU

Converts all lower case characters in the string to upper case characters.

MCT

Capitalises each word in the input string; i.e. JIM converts to Jim

MCP{c}

Converts all non printable characters to a tilde character '~' in the input
string. If the character 'c' is supplied then this character is used instead of
the tilde.

MCPN{n}

In the same manner as the MCP conversion all non printable characters are
replaced. However the replacing character is followed by the ASCII
hexadecimal value of the character that was replaced.

MCNP{n}

Performs the opposite conversion to MCPN. The ASCII hexadecimal value

following the tilde character is converted back to its original binary
character value.

MCDX

Converts the decimal value in the input string to its hexadecimal equivalent.

MCXD

Converts the hexadecimal value in the input string to its decimal equivalent.

Gncx

Extracts x groups separated by character c skipping n groups, from the input

string.

MT{HS}

Performs time conversions.

MD

Converts the supplied integer value to a decimal value.

MP

Converts a packed decimal number to an integer value.

MX

Converts ASCII input to hexadecimal characters.

Performs file translations given a cross reference table in a record in a file.

ON...GOSUB, ON...GOTO
The ON...GOSUB and ON...GOTO statements are used to transfer program execution to a label based upon a
calculation.
Command Syntax
ON expression GOTO label{, label...}
ON expression GOSUB label{, label...}
Syntax Elements
Expression should evaluate to an integer numeric value. Labels should be defined somewhere in the current
source file.
ON GOTO will transfer execution to the labelled source code line in the program. ON GOSUB will transfer
execution to the labelled subroutine within the source code.
Notes
The value of expression is used as an index to the list of labels supplied. If the expression evaluates to 1 then the
first label will be jumped to, 2 then the second label will be used and so on.
If the program was compiled with the environment variable JBCEMULATE set to R83 then no validations are
performed on the index to see if it is valid. Therefore if the index is out of range this instruction will take no
action and report no error.
If the program was compiled for other compatibilities then the index will be range checked. If the index is found
to be less than 1 it is assumed to be 1 and a warning message is issued. If the index is found to be too big, then
the last label in the list will be used to transfer execution and a warning message issued.

jBC

2-90

Programmers Reference Manual

Examples
INPUT Ans,1_
ON SEQ(Ans)-SEQ(A)+1 GOSUB RoutineA, RoutineB...

OPEN
The OPEN statement is used to open a file or device to a descriptor variable within jBC.
Command Syntax
OPEN {expression1,}expression2 TO {variable} {SETTING setvar} THEN|ELSE statements
Syntax Elements
The combination of expression1 and expression2 should evaluate to a valid file name of a file type that has been
installed into the jBASE system. If the file has a dictionary section and this is to be opened by the statement then
this may be emphasised by the literal string "DICT" being specified in expression1. If specified, the variable will
be used to hold the descriptor for the file. It should then be to access the file using READ and WRITE. If no file
descriptor variable is supplied, then the file will be opened to the default file descriptor.
Specific data sections of a multi level file may specified by separating the section name from the file name by a
',' char in expression2.
If the OPEN statement fails it will execute any statements associated with an ELSE clause. If the OPEN is
successful it will execute any statements associated with a THEN clause. Note that the syntax requires either one
or both of the THEN and ELSE clauses.
If the SETTING clause is specified and the open fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The OPEN statement uses the environment variable JEDIFILEPATH to search for the file named. If this is not
defined then the current working directory is looked in followed by the home directory of the current process.
See the documentation on environment variables for more details.
The file that is the subject of the OPEN statement can be of any type known to the jBASE system. Its type will
be determined and correctly opened transparently to the application, which need not be aware of the file type.
There is no limit to the number of files that may be opened by a jBC program.
Examples
OPEN "DICT", "CUSTOMERS" TO F.Dict.Customers ELSE
ABORT 201, "DICT CUSTOMERS"
END
opens the dictionary section of file CUSTOMERS to its own file descriptor F.Dict.Customers.
OPEN "CUSTOMERS" ELSE ABORT 201, "CUSTOMERS"
opens the CUSTOMERS file to the default file variable.

OUT
The OUT statement is used to send raw characters to the current output device (normally the terminal).
Command Syntax
OUT expression

Programmers Reference Manual

2-91

jBC

Syntax Elements
Expression should evaluate to a numeric integer in the range 0 to 255, being the entire range of ASCII
characters.
Notes
The numeric expression is first converted to the raw ASCII character specified and then sent directly to the
output advice.
Examples
EQUATE BELL
TO
OUT 7
BELL
;* Sound terminal bell
FOR I = 32 TO 127; OUT I; NEXT I ;* Printable chars
BELL

PAGE
Prints any FOOTING statement, throws a page and prints any heading statement on the current output device.
Command Syntax
PAGE {expression}
Syntax Elements
If expression is specified it should evaluate to a numeric integer, which will cause the page number after the page
throw to be set to this value.
Examples
HEADING "10 PAGE REPORT"
FOR I = 1 TO 10
PAGE
GOSUB PrintPage
NEXT I

PERFORM
Notes
See EXECUTE

PRECISION
The PRECISION statement informs jBASE as to the number of digits of precision it uses after the decimal
point in numbers.
Command Syntax
PRECISION integer
Syntax Elements
Integer should be in the range 0 to 9.
Notes
PRECISION is a compiler directive rather than a jBC executable statement and may only be specified once in a
source file.
Calling programs and external subroutines MUST be compiled at the same degree of precision or unpredictable
results will occur in calculations.

jBC

2-92

Programmers Reference Manual

jBASE uses the maximum degree of precision allowed on the host UNIX machine in all mathematical
calculations to ensure maximum accuracy. It then uses the defined precision to format the number.
Examples
PRECISION 6
CRT 2/3
will print the value 0.666666 (note truncation not rounding!).

PRINT
The PRINT statement sends data directly to the current output device, which will either be the terminal or the
printer.
Command Syntax
PRINT expression {, expression...} {:}
Syntax Elements
An expression can evaluate to any data type. The PRINT statement will convert the result to a string type for
printing. Expressions separated by commas will be sent to the output device separated by a tab character.
The PRINT statement will append a newline sequence to the final expression unless it is terminated with a colon
':' character.
Notes
As the expression can be any valid expression, it may have output formatting applied to it.
If a PRINTER ON statement is currently active then output will be sent to the currently assigned printer form
queue, (see also SP-ASSIGN command).
See also:

CRT

Examples
PRINT A "L#5"
PRINT @(8,20):"Patrick":

PRINTER ON|OFF|CLOSE
The PRINTER statement is used to control the destination of output from the PRINT statement.
Command Syntax
PRINTER ON|OFF|CLOSE
Notes
PRINTER ON will cause all subsequent output from the PRINT statement to be redirected to the print spooler.
PRINTER OFF will cause all subsequent output from the PRINT statement to be redirected to the terminal
device.
PRINTER CLOSE will act as PRINTER OFF but in addition will close the currently active spool job created
by the active PRINTER ON statement.
Examples
PRINTER ON
;* Open a spool job
FOR I =1 TO 60
PRINT "Line ":I ;* Send to printer
PRINTER OFF
PRINT "+":
;* Send to terminal
PRINTER ON
;* Back to printer

Programmers Reference Manual

2-93

jBC

NEXT I
PRINTER CLOSE
.....etc.

;* Allow spooler to print it

PRINTERR
To print standard jBASE error messages.
Command Syntax
PRINTERR expression
Syntax Elements
Field 1 of the expression should evaluate to the numeric or string name of a valid error message in the jBASE
error message file. If the error message requires parameters then these can be passed to the message as
subsequent fields of the expression.
Notes
The PRINTERR statement is most useful for user defined messages that have been added to the standard set.
See the section on error messages in this manual for more information.
You should be very careful when typing this statement it is very similar to the PRINTER statement. Although
this is not ideal, the PRINTERR statement must be supported for compatibility with older systems.
Examples
PRINTERR 201:CHAR(254):"CUSTOMERS"

PROCREAD
Used to retrieve data passed to programs from a jCL program.
Command Syntax
PROCREAD variable THEN|ELSE statements
Syntax Elements
Variable is a valid jBC identifier, which will be used to store the contents of the primary input buffer of the last
jCL program called.
If the program was not initiated by a jCL program then the PROCREAD will fail and any statements associated
with an ELSE clause will be executed. If the program was initiated by a jCL program then the PROCREAD
will succeed, the jCL primary input buffer will be assigned to variable and any statements associated with a
THEN clause will be executed.
Notes
It is recommended that the use of jCL and therefore the PROCREAD statement should be not be expanded
within your application and gradually replaced with more sophisticated methods such as UNIX scripts or jBC
programs.
Examples
PROCREAD Primary ELSE
CRT "Unable to read the jCL buffer"
STOP
END

PROCWRITE
Used to pass data back to the primary input buffer of a calling jCL program.

jBC

2-94

Programmers Reference Manual

Command Syntax
PROCWRITE expression
Syntax Elements
Expression may evaluate to any valid data type.
Notes
See also: PROCREAD
Examples
PROCWRITE "Success":CHAR(254):"0"

PROGRAM
Performs no function other than to document the source code.
Command Syntax
PROGRAM progname
Syntax Elements
Progname can be any string of characters.
Notes
Examples
PROGRAM HelpUser
!
! Start of program

PROMPT
Used to change the prompt character used by terminal input commands
Command Syntax
PROMPT expression
Syntax Elements
Expression can evaluate to any printable string.
Notes
The entire string is used as the prompt.
The default prompt character is the question mark '?' character.
Examples
PROMPT "Next answer : "
INPUT Answer

PUTENV
Used to set environment variables for the current process.
Command Syntax
PUTENV(expression)

Programmers Reference Manual

2-95

jBC

Syntax Elements
Expression should evaluate to a string of the form:
EnvVarName=value
Where EnvVarName is the name of a valid environment variable and value is any string that makes sense to
variable being set.
If PUTENV function succeeds it returns a Boolean TRUE value, if it fails it will return a Boolean FALSE
value.
Notes
PUTENV only sets environment variables for the current process and processes spawned (say by EXECUTE)
by this process. These variables are known as export only variables.
Examples
IF PUTENV("JBCLOGNAME=":UserName) THEN
CRT "Environment configured"
END

PWR( )
The PWR function raises a number to the nth power.
Command Syntax
PWR(expression1, expression2)
or
expression1 ^ expression2
Syntax Elements
Both expression1 and expression2 should evaluate to numeric arguments. The function will return the value of
expression1 raised to the value of expression2.
Notes
If expression1 is negative and expression2 is not an integer then a maths library error is displayed and the
function returns the value 0. The error message displayed is:
pow: DOMAIN error
All calculations are performed at the maximum precision supported on the host machine and truncated to the
compiled precision on completion.
Examples
A =
B =
CRT
or
CRT

2
31
"2 GB is ":A^B
2GB is:PWR(A,B)

READ
The READ statement allows a program to read a record from a previously opened file into a variable.
Command Syntax
READ variable1 FROM {variable2,} expression {SETTING setvar} {LOCKED statements} THEN|ELSE
statements

jBC

2-96

Programmers Reference Manual

Syntax Elements
Variable1 is the identifier into which the record will be read.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
The expression should evaluate to a valid record key for the file.
If the SETTING clause is specified and the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
If the record could not be read because another process already had a lock on the record then one of two actions
is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed.
If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other
process.
On a successful read, if a LOCKED clause is used, a lock will be set.
Many programmers assume that using a LOCKED clause with a READ statement will allow a test for the
record being locked without setting a lock for the current program. In fact this is not the case as the use of a
LOCKED clause will result in a lock being taken against the record. As the programmer has assumed a lock is
not taken on the record this can result in erroneous programs.
If you wish to set a lock on a record you should do so explicitly with the READU statement.
Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
READ Rec FROM DCusts, "Xref" THEN
READ DataRec FROM Rec<7> ELSE
ABORT 202, Rec<7>
END
END ELSE
ABORT 202, "Xref"
END

READLIST
READLIST allows the program to retrieve a previously stored list (perhaps created with the SAVE-LIST
command), into a jBC variable.
Command Syntax
READLIST variable1 FROM expression {SETTING variable2} THEN|ELSE statements
Syntax Elements
Variable1 is the variable into which the list will be read. Expression should evaluate to the name of a previously
stored list to retrieve. Variable2 (if specified) will be set to the number of elements in the list.
If the statement succeeds in retrieving the list, then the statements associated with any THEN clause will be
executed. If the statement fails to find the list, then the statements associated with any ELSE clause will be
executed.
Notes
The READLIST statement is identical in function to the GETLIST statement.

Programmers Reference Manual

2-97

jBC

See also:

WRITELIST

Examples
* Find the list first
READLIST MyList FROM "MyList" ELSE STOP
LOOP
* Loop until there are no more elements
WHILE READNEXT Key FROM MyList DO
......
REPEAT

READNEXT
READNEXT retrieves the next element in a list variable.
Command Syntax
READNEXT variable1, variable2 {FROM variable3} {SETTING setvar} {THEN|ELSE statements}
Syntax Elements
Variable1 is the variable into which the next element of the list will be read.
Variable2 is used when the list has been retrieved externally from a SSELECT or similar jBASE command that
has used an exploding sort directive. When specified, this variable will be set to the multi-value reference of the
current element. For example, if the SSELECT used a BY-EXP directive on field 3 of the records in a file, the
list will contain each record key in the file as many times as there are multi-values in the field. Each
READNEXT instance will set variable2 to the multi-value in field 3 that the element refers to. This allows the
multi-values in field 3 to be retrieved in sorted order.
If variable3 is specified with the FROM clause, the READNEXT operates on the list contained in variable3. If
variable3 is not specified, the default select list variable will be assumed.
If the SETTING clause is specified and the read (to build the next portion of the list) fails, setvar will be set to
one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
See also:

SELECT

READNEXT can be used as an expression returning a Boolean TRUE or FALSE value. If an element is
successfully read from the list, TRUE is returned. If the list was empty, FALSE is returned.
Examples
LOOP
WHILE READNEXT Key FROM RecordList DO
......
REPEAT

READT
The READT statement is used to read a range of tape devices 0-9.
Command Syntax
READT variable {FROM expression} THEN|ELSE statements

jBC

2-98

Programmers Reference Manual

Syntax Elements
Variable is the variable that will receive any data read from the tape device. Expression should evaluate to an
integer value in the range 0-9 and specifies from which tape channel to read data. If the FROM clause is not
specified the READT will assume channel 0.
If the READT fails then the statements associated with any ELSE clause will be executed. SYSTEM(0) will
return the reason for the failure as follows:
Value
1
2

Meaning
There is no media attached to the channel
An end of file mark was found.

Notes
A "tape" does not refer to magnetic tape devices only but any device that has been described to jBASE. Writing
device descriptors for jBASE is beyond the scope of this manual.
If no tape device has been assigned to the channel specified then the jBASE debugger is entered with an
appropriate message.
Each instance of the READT statement will read the next record available on the device. The record size is not
limited to a single tape block and the entire record will be returned whatever block size has been allocated by the
T-ATT command.
Examples
LOOP
READT TapeRec FROM 5 ELSE
Reason = SYSTEM(0)
IF Reason = 2 THEN BREAK
CRT "ERROR"; STOP
END
REPEAT

;* done

READU
The READU statement allows a program to read a record from a previously opened file into a variable. It
respects record locking and locks the specified record for update.
Command Syntax
READU variable1 FROM {variable2,} expression {SETTING setvar} {LOCKED statements} THEN|ELSE
statements
Syntax Elements
Variable1 is the identifier into which the record will be read.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
The expression should evaluate to a valid record key for the file.
If the SETTING clause is specified and the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error

Programmers Reference Manual

2-99

jBC

Notes
If the record could not be read because another process already had a lock on the record then one of two actions
is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed.
If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other
process.
If the statement fails to read the record then any statements associated with the ELSE clause will be executed. If
the statement successfully reads the record then the statements associated with any THEN clause are executed.
Either or both of THEN and ELSE clauses must be specified with the statement.
The lock taken by the READU statement will be released by any of the following events:
The record is written to by the same program with WRITE, WRITEV or MATWRITE statements.
The record lock is released explicitly using the RELEASE statement.
The program stops normally or abnormally.
See also: WRITE, WRITEU, MATWRITE, MATWRITEU, RELEASE
Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
LOOP
READU Rec FROM DCusts, "Xref" LOCKED
CRT "Locked - retrying"
SLEEP 1; CONTINUE
;* Restart LOOP
END THEN
READ DataRec FROM Rec ELSE
ABORT 202, Rec
END
BREAK
;* Leave the LOOP
END ELSE
ABORT 202, "Xref"
END
REPEAT

READV
The READV statement allows a program to read a specific field from a record in a previously opened file into a
variable.
Command Syntax
READV variable1 FROM {variable2,} expression1, expression2 {SETTING setvar} {LOCKED statements}
THEN|ELSE statements
Syntax Elements
Variable1 is the identifier into which the record will be read.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified, the default file is assumed (see OPEN statement).
Expression1 should evaluate to a valid record key for the file.
Expression2 should evaluate to a positive integer. If the number is invalid or greater than the number of fields in
the record, a NULL string will be assigned to variable1. If a non-numeric argument is evaluated, a run time error
will occur.
If the SETTING clause is specified and the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied

jBC

2-100

Programmers Reference Manual

32768 Physical I/O error or unknown error

Notes
If the record could not be read because another process had already set a lock, one of two actions is taken. If the
LOCKED clause was specified in the statement, the associated statements are executed. If a LOCKED clause
was not specified, the process will pause (hang) until the lock is released by the other process.
On a successful read, if a LOCKED clause is used, a lock will be set.
A common error is to assume that using a LOCKED clause will allow you to test for the record being locked
without actually setting a lock. This is not the case. If you use a LOCKED clause, a lock will be set against the
record.
If you wish to set a lock on a record you should do so explicitly with the READVU statement.
Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
READV Rec FROM DCusts, "Xref,7 THEN
READ DataRec FROM Rec<7> ELSE
ABORT 202, Rec<7>
END
END ELSE
ABORT 202, "Xref"
END

READVU
The READVU statement allows a program to read a specific field in a record in a previously opened file into a
variable. It also respects record locking and locks the specified record for update.
Command Syntax
READVU variable1 FROM {variable2,} expression1, expression2 {SETTING setvar} {LOCKED
statements} THEN|ELSE statements
Syntax Elements
Variable1 is the identifier into which the record will be read.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
Expression1 should evaluate to a valid record key for the file.
Expression2 should evaluate to a positive integer number. If the number is invalid or greater than the number of
fields in the record, then a NULL string will be assigned to variable1. If a non-numeric argument is evaluated a
run time error will occur.
If the SETTING clause is specified and the read fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
If the record could not be read because another process already had a lock on the record then one of two actions
is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed.
If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other
process.

Programmers Reference Manual

2-101

jBC

If the statement fails to read the record then any statements associated with the ELSE clause are executed. If the
statement successfully reads the record then the statements associated with any THEN clause are executed.
Either or both of the THEN and ELSE clauses must be specified with the statement.
The lock taken by the READVU statement will be released by any of the following events:

The record is written to by the same program with WRITE, WRITEV or MATWRITE statements.

The record lock is released explicitly using the RELEASE statement.

The program stops normally or abnormally.

See also: WRITE, WRITEU, MATWRITE, MATWRITEU, RELEASE

Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
LOOP
READVU Rec FROM DCusts, "Xref,7 LOCKED
CRT "Locked - retrying"
SLEEP 1; CONTINUE
;* Restart LOOP
END THEN
READ DataRec FROM Rec ELSE
ABORT 202, Rec
END
BREAK
;* Leave the LOOP
END ELSE
ABORT 202, "Xref"
END
REPEAT

REGEXP
The REGEXP function is a very powerful function that allows pattern matching using UNIX regular
expressions.
Command Syntax
REGEXP(variable, expression)
Syntax Elements
Variable can be any type of jBC variable and is the variable upon which pattern matching will be performed.
Expression should evaluate to a standard UNIX regular expression as defined in the UNIX documentation.
Notes
The function returns a numeric integer value being the first character in variable that failed to match the
specified regular expression. If a match is not found or the regular expression was invalid then the function
returns 0.
Examples
String = "James Anthony Computing"
CRT REGEXP(String, "C[^t]*")
would display the value 20 being the position of the character 't' in the word Computing.

RELEASE
The RELEASE statement enables a program to explicitly release record locks without updating the records
using WRITE.

jBC

2-102

Programmers Reference Manual

Command Syntax
RELEASE {{variable,} expression}
Syntax Elements
If variable is specified it should be a valid file descriptor variable (i.e. It should have been the subject of an
OPEN statement).
If an expression is supplied it should evaluate to the record key of a record whose lock the program wishes to
free. If variable was specified the record lock in the file described by it is released. If variable was not specified
the record lock in the file described by the default file variable is released.
If RELEASE is issued without arguments then all record locks in all files that were set by the current program
will be released.
Notes
Where possible the program should avoid the use of RELEASE without arguments. This is less efficient and can
be a dangerous - especially in subroutines.
Examples
READU Rec FROM File, "Record" ELSE ABORT 203, "Record"
IF Rec<1> = "X" THEN
RELEASE File, "Record"
END
......

REMOVE
REMOVE will successively extract delimited strings from a dynamic array.
Command Syntax
REMOVE variable FROM array SETTING setvar
Syntax Elements
variable is the variable which is to receive the extracted string.
array is the dynamic array from which the string is to be extracted.
setvar is set by the system during the extraction to indicate the type of delimiter found - as described in the
following table:
0
1
2
3
4
5
6
7

end of the array

xFF ASCII 255
xFE ASCII 254
xFD ASCII 253
xFC ASCII 252
xFB ASCII 251
xFA ASCII 250
xF9 ASCII 249

Field marker
Value marker
Subvalue marker

Notes
The first time the REMOVE statement is used with a particular array, it will extract the first delimited string it
and set the special remove pointer to the start of the next string (if any). The next time REMOVE is used on the
same array, the pointer will be used to retrieve the next string and so on. The array is not altered.
The variable named in the SETTING clause is used to record the type of delimiter that was found - so that you
can tell whether the REMOVE statement extracted a field, a value or a subvalue for example. Delimiters are
defined as characters between xF9 and xFF only.

Programmers Reference Manual

2-103

jBC

Once the end of the array has been reached, the string variable will not be updated and the SETTING clause will
always return 0. You can reset the remove pointer by assigning the variable to itself - for example REC = REC.
Example
EQU FM TO CHAR(254), VM to CHAR(253), SVM to CHAR(252)
REC = Field 1:FM:Value 1:VM:Value 2:FM:Field 3
REMOVE EXSTRING FROM REC SETTING DELIM
REMOVE EXSTRING FROM REC SETTING DELIM
The first time REMOVE is used, EXSTRING will contain Field 1 and DELIM will contain xFE. The second
time REMOVE is used, EXSTRING will contain Value 1 and DELIM will contain xFD.

REPLACE
This is an obsolete way to assign to dynamic arrays via a function.
Command Syntax
REPLACE (var, expression1{, expression2{, expression3}}; expression4)
Syntax Elements
Var is the dynamic array that the REPLACE function will use to assign expression4. Unless the same var is
assigned the result of the function it will be unchanged.
Expression1 specifies into which field assignment will be made and should evaluate to a numeric.
Expression2 is only specified when multi-value assignment is to be done and should evaluate to a numeric.
Expression3 is only specified when sub-value assignment is to be done and should evaluate to a numeric.
Expression4 can evaluate to any data type and is the actual data that will be assigned to the array.
Notes
The function returns a copy of var with the specified replacement carried out. This value may be assigned to the
original var in which case the jBC compiler will optimise the assignment.
See the heading Dynamic Arrays earlier in this chapter for information on the preferred method of accessing
dynamic arrays.
Examples
X = "JBASE":MV:"is Great"
X = REPLACE(X,1,1;"jBASE")

RETURN
The RETURN statement transfers program execution to the caller of a subroutine or to a specific label in the
program.
Command Syntax
RETURN {TO label}
Notes
The RETURN statement will transfer program execution to the statement after the GOSUB that called the
current internal subroutine.
If the RETURN statement is executed in an external SUBROUTINE and there are no outstanding GOSUBs,
then the program will transfer execution back to the program that called it via CALL.
The program will enter the debugger with an appropriate message should a RETURN be executed with no
GOSUB or CALL outstanding.

jBC

2-104

Programmers Reference Manual

REWIND
The REWIND statement will issue a rewind command to the device attached to the specified channel.
Command Syntax
REWIND {ON expression} THEN|ELSE statements
Syntax Elements
Expression, if specified, should evaluate to an integer in the range 0 to 9. Default is 0.
Notes
If the statement fails to issue the rewind then any statements associated with the ELSE clause are executed. If
the statement successfully issues the rewind command then the statements associated with any THEN clause are
executed. Either or both of the THEN and ELSE clauses must be specified with the statement.
If the statement fails then the reason for failure can be determined via the value of SYSTEM(0) as follows:
Value
1
2

Meaning
There is no media attached to the channel
An end of file mark was found.

RND
The RND statement allows the generation of random numbers by a program.
Command Syntax
RND(expression)
Syntax Elements
Expression should evaluate to a numeric integer value or a runtime error will occur. The absolute value of
expression is used by the function (see ABS).
Notes
The function will return a random integer number between 0 and the value of expression-1.
Examples
FOR I=1 TO 20
CRT RND(100):", ":
NEXT I
prints 20 random numbers in the inclusive range 0 to 99.

RQM
See SLEEP

RTNDATA
The RTNDATA statement allows a jBC program to return specific data to the RTNDATA clause of another
programs EXECUTE statement.
Command Syntax
RTNDATA expression
Syntax Elements
Expression may evaluate to any data type.

Programmers Reference Manual

2-105

jBC

Notes
When a jBC program executes another jBC program using the EXECUTE statement it may specify a variable to
pick up data in using the RTNDATA clause. The data picked up will be that specified by the executed program
using the RTNDATA statement.
The data will be discarded if the program is not executed by an EXECUTE statement in another program.

SELECT
The SELECT statement creates a select list of elements in a specified variable.
Command Syntax
SELECT {variable1} {TO variable2} {SETTING setvar}
Syntax Elements
variable1 can be an OPENed file descriptor, in which case the record keys in the specified file will be selected,
or an ordinary variable in which case each field in the variable will become a list element. Variable1 may also be
an existing list in which case the elements in the list will be selected.
If variable1 is not specified in the statement then the default file variable is assumed.
If variable2 is specified then the newly created list will be placed in the variable. If variable2 is not specified
then the default list variable will be assumed.
If the SETTING clause is specified and the select fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
When a list is being built from record keys in a file, the list is not created immediately by scanning the file for all
the record keys. Instead, only the first few keys will be extracted. When these keys have been taken from the list,
the next few keys will be obtained and so on. This means that the list could contain records that are written to
the file after the SELECT command is started.
Consider the situation where you open a file, SELECT it and then, on the basis of the keys obtained, write new
records to the same file. It would be easy to assume that these new keys would not show up in the list because
you created the list before the new records existed. THIS IS NOT THE CASE. Any records written beyond the
current position in the file will eventually show up in the list. In situations where this might cause a problem, or
to ensure that you obtain a complete, qualified list of keys, you should use a slower external command like jQL
SELECT or SSELECT and then READNEXT to parse the file.
Lists can be selected as many times as required.
Example
OPEN "Customers" ELSE ABORT 201, "Customers"
SELECT TO CustList1
SELECT TO CustList2
.....

SENTENCE
The SENTENCE statement allows a program to find out the command used to invoke it and the arguments it
was given.
Command Syntax
SENTENCE({expression})

jBC

2-106

Programmers Reference Manual

Syntax Elements
If expression is specified it should evaluate to a positive integer value. A negative value will return a null string.
A value of zero or null will return the entire command line.
A positive integer value of expression will return a specific element of the command line with the command
itself being returned by SENTENCE(1), the first parameter being returned by SENTENCE(2) and so on.
If expression is omitted the a value of zero is assumed.
Notes
The command line arguments are assumed to be space separated and when the entire command line is returned
they are returned as such.
Examples
DIM Parm(5)
ProgName = SENTENCE(1) ;* Program is ?
FOR I = 2 TO 5
Parm(I) = SENTENCE(I) ;* Get parameters
NEXT I

SEQ( )
The SEQ function returns numeric ASCII value of a character.
Command Syntax
SEQ(expression)
Syntax Elements
Expression may evaluate to any data type. However the SEQ function will convert the expression to a string and
operate on the first character of that string.
Notes
SEQ operates on any character in the integer range 0 to 255
Examples
EQU ENQ TO 5
* Get next comms code
* Time-out after 20 seconds
INPUT A,1 FOR 200 ELSE BREAK
IF SEQ(A) = ENQ THEN
* Respond to ENQ char
......

SIN( )
The SIN function returns the mathematical sine value of a numeric expression.
Command Syntax
SIN(expression)
Syntax Elements
Expression should evaluate to a numeric value and is interpreted as a number of degrees between 0 and 360.
Notes
The function will calculate the sine of the angle specified by the expression as accurately as the host system will
allow. It will then truncate the value according to the PRECISION of the program.

Programmers Reference Manual

2-107

jBC

Examples
CRT @(-1):
FOR I = 0 TO 79
CRT @(I,12+INT(SIN(360/80*(I+1))*10)):"*":
NEXT I

SLEEP
Allows the program to halt execution for a specified time period.
Command Syntax
SLEEP {expression}
Syntax Elements
Expression may evaluate to one of two forms:
Numeric in which case the statement will sleep for the specified number of seconds.
"nn:nn{:nn}" in which case the statement will sleep until the time specified.
If expression is not supplied then a default time period of 1 second is assumed.
Notes
Sleeping until a specified time works by calculating the time between the current time and the time supplied and
sleeping for that many seconds. If the host clock is changed in the meantime then the program will not wake up
at the desired time.
Examples
* Sleep until the end of the working day for anyone
* who doesn't program computers.
SLEEP "17:30"
*
* 40 winks...
SLEEP 40

SORT( )
The SORT function allows the program to sort a dynamic array.
Command Syntax
SORT(expression)
Syntax Elements
Expression may evaluate to any data type but will only be useful if it evaluates to a dynamic array.
Notes
The SORT command will return a dynamic array sorted by the highest delimiter found in the array. This means
the if it is passed a list of fields it will sort by field but if passed a list of sub-values it will sort by sub-values.
The SORT is achieved by the quick sort algorithm, which sorts in situ and is very fast.
Examples
* Read a list, sort it and write it back
*
READ List FROM "Unsorted" ELSE List = ""
List = SORT(List)

jBC

2-108

Programmers Reference Manual

WRITE List ON "Sorted"

SOUNDEX( )
The SOUNDEX function allows phonetic conversions of strings.
Command Syntax
SOUNDEX(expression)
Syntax Elements
Expression may evaluate to any data type but the function will only give meaningful results for English words.
Notes
The phonetic equivalent of a string is calculated as the first alphabetic character in the string followed by a 1 to 3
digit representation of the rest of the word.
The digit string is calculated from the following table:
Characters
BFPV
CGJKQSXZ
DT
L
MN
R

Value code
1
2
3
4
5
6

All characters not contained in the above table are ignored. The function is case insensitive and identical
sequences of a character are interpreted as a single instance of the character.
The idea is to provide a crude method of identifying words such as surnames even if they are not spelt correctly.
The function is not foolproof by any means and should not be the sole method of identifying a word.
Examples
INPUT Surname
Surname = SOUNDEX(Surname)
.....search the data bases

SPACE( )
The SPACE function is a convenient way to generate a specific number of ASCII space characters.
Command Syntax
SPACE(expression)
Syntax Elements
Expression should evaluate to a positive integer value.
Notes
The SPACE function will return the specified number of ASCII space characters and is useful for padding
strings. It should not be used to position output on the terminal screen however as this is inefficient and should
be accomplished using the @( ) function.
Examples
TenSpaces = SPACE(10)

SQRT
The SQRT function returns the mathematical square root of a value.

Programmers Reference Manual

2-109

jBC

Command Syntax
SQRT(expression)
Syntax Elements
The expression should evaluate to a positive numeric value as the authors do not want to introduce a complex
number type within the language. Negative values will cause a math error.
Notes
The function calculates the result at the highest precision available and then truncates the answer to the required
PRECISION.
Examples
FOR I = 1 TO 1000000
J=SQRT(I)
NEXT I

STOP
The STOP statement is virtually identical in function to the ABORT statement except that the calling jCL
program will not be terminated.

STR( )
The STR function allows the duplication of a string a number of times.
Command Syntax
STR(expression1, expression2)
Syntax Elements
Expression1 will evaluate to the string to duplicate and may be of any length.
Expression2 should evaluate to a numeric integer, which specifies the number of times the string will be
duplicated.
Examples
LongString = STR("long string ", 999)

SUBROUTINE
The SUBROUTINE statement is used at the start of any program that will be called externally by the CALL
statement. It also declares any parameters to the compiler.
Command Syntax
SUB{ROUTINE} Name {({MAT} variable{,{MAT} variable...})}
Syntax Elements
Name is the identifier by which the subroutine will be known to the compilation process. It should always be
present as this name (not the source file name), will be used to call it by. However, if the name is left out, the
compiler will name subroutine as the source file name (without suffixes). Default naming is not encouraged as it
can cause problems if source files are renamed.
Each comma separated variable in the optional parenthesised list is used to identify parameters to the compiler.
These variables will be assigned the values passed to the subroutine by a CALL statement.

jBC

2-110

Programmers Reference Manual

Notes
A subroutine will inherit all the variables declared using the COMMON statement providing an equivalent
COMMON area is declared within the SUBROUTINE source file. The program will fail to compile if the
number of common variables used in each common area exceeds the number defined in the equivalent area in the
main program.
Subroutines may only be called via the jBC CALL statement. and must be compiled at the same PRECISION as
the calling program or unpredictable results will occur.
A subroutine will return to the CALLing program if it reaches the logical end of the program or a RETURN
statement is executed with no outstanding GOSUB statement.
A SUBROUTINE will not return to the calling program if a STOP or ABORT statement is executed.
See also:

CALL, COMMON, RETURN

Examples
SUBROUTINE DialUp(Number, MAT Results)
DIM Results(8)
....

SYSTEM
The SYSTEM function allows the program to determine the state of many system level variables and functions
by a numeric index.
Command Syntax
SYSTEM(expression)
Syntax Elements
Expression should evaluate to one of the integer numbers defined below.
Notes
The SYSTEM() function will return the following information according to the numeric index:
Index

Description

Return the last tape or file error number as defined by the error message file.

Returns 1 if output is being sent to the printer, 0 if it is not.

Returns the current page width taken either from the terminfo database, the environment
variable JBCSCREEN_WIDTH or JBCPRINTER_WIDTH.

Returns the current page width taken either from the terminfo database or from the
environment variable JBCSCREEN_LENGTH or JBCPRINTER_LENGTH.

Returns the number of lines remaining in the current formatted page. Only effective
when a HEADING or FOOTING statement is in force.

Returns the current page number of formatted output. Only effective when a HEADING
or FOOTING statement is in force.

Returns the current line counter in the current formatted output. Only effective when a
HEADING or FOOTING statement is in force.

Returns the terminal type as defined by the environment variable TERM. If the
environment variable JBCTERM_TYPE is defined then the value of this variable will
be returned instead.

Returns the record length for tape channel 0. The IOCTL() statement can be used to
determine record lengths for other channels.

Returns the CPU millisecond count used by both the current process and any child
processes.

10

Returns 1 if keyboard input is actually being read from a previously stacked data or a
UNIX pipe, rather than from the keyboard.

Programmers Reference Manual

2-111

jBC

11

Returns 1 if a default external select list is currently active.

12

If JBCEMULATE is set to ROS then this index returns the current system time in 1/10
seconds past midnight. Other values of JBCEMULATE will return the system time in
1/1000 seconds past midnight.

Index

Description

13

On some systems this will force a release of the time slice quantum. This is neither
necessary nor desirable within jBASE. This function will return 1 if the JBCEMULATE
variable is set to ROS or 0 otherwise.

14

Returns the number of characters currently buffered in the output buffer.

15

Returns the string of command line options used to invoke this command. I.e. all the
options following ( in the command line.

16

Returns the level of nesting (EXECUTE/PERFORM) level of the current process.

17

If the program has EXECUTEd a daughter process then this index will return the STOP
code of the daughter process. The function will return a null string if there have been no
daughter processes spawned by this process.

18

Returns the port number of the current process. This index will return a number defined
by the UNIX environment unless the environment variable JBCPORTNO is defined, in
which case the value of this variable is returned. It is recommended that the
JBCPORTNO variable is determined at login time by the .profile script.

and
101
19

Returns the login account name for the current process. This will normally be the UNIX
user login name (env LOGNAME) unless the environment variable JBCLOGNAME has
been defined, in which case the value of this variable will be returned.

23

Returns 1 if the BREAK key (stty intr) is enabled or 0 if it is not.

24

Returns 1 if character echoing is enabled (stty echo) or 0 if it is not (stty -echo).

25

Returns 1 if the current process is running in the background or as a jBTP job.

26

Returns the current prompt string defined by the PROMPT statement.

40

Returns the name of the current program.

100

Returns the version string compiled into the program by jBASE.

101

See SYSTEM(18).

1000

Returns the command line string with each component separated by a field mark. The
invocation option string (characters following the '(') is not returned.

1001

Returns the command line string as SYSTEM(1000) but includes the invocation option
string.

1002

Returns the name of the temporary scratch file currently used by the program (may not
be useful outside jBASE system programs).

1003

Returns the entire binary information provided by the terminfo database for the
currently defined terminal type.

1004

Returns the terminfo NUMBERS information for the currently defined terminal.

1005

Returns the terminfo STRING information.

1006

Returns the time of the last login for this user.

1007

Returns the current time in UNIX format.

1008

Returns the name of the SYSTEM file if it has been defined using the
JEDIFILENAME_SYSTEM environment variable.

Index

Description

1009

Returns the name of the MD file if it has been defined using the JEDIFILENAME_MD
environment variable.

jBC

2-112

Programmers Reference Manual

1013

Returns information about how much memory you are using as follows :
<1> Number of bytes in the small free space block.
<2> Number of bytes in the large free space block.
<3> Number of bytes in the small used space block.
<4> Number of bytes in the large used space block.
Useful when testing programs. Use SYSTEM(1013) after the first loop and compare
with the results after the last loop, differences should be minimal.

Examples
024 PortNo = SYSTEM(18)
;* Get Port number
025 READ Control FROM CFile, "CTL*":PortNo
001
002
056
057

TStart = SYSTEM(9) ;* Get CPU time at start

.....
TEnd = SYSTEM(9) ;* Get CPU time at end
TTotal = TEnd - TStart ;* Total CPU time

TAN( )
The TAN function returns the mathematical tangent of an angle.
Command Syntax
TAN(expression)
Syntax Elements
Expression should evaluate to a numeric type.
Notes
The function calculates the result at the highest precision available on the host system. The result is truncated to
the current PRECISION after calculation.
Examples
Adjacent = 42
Angle = 34
CRT "Opposite length = ":TAN(Angle)*Adjacent

TIME( )
The TIME() function returns the current system time.
Command Syntax
TIME()
Notes
The time is returned as the number of seconds past midnight
Examples
CRT "Time is ":OCONV(TIME(), "MTS")

TIMEDATE( )
The TIMEDATE() function returns the current time and date as a printable string.
Command Syntax
TIMEDATE()

Programmers Reference Manual

2-113

jBC

Notes
The function returns a string of the form: hh:mm:ss dd mmm yyyy, or in the appropriate format for your
international date setting.
Examples
CRT "The time and date is ":TIMEDATE()

TRANSABORT
TRANSABORT is used to abort the current transaction and reverse any updates to the database.
Command Syntax
TRANSABORT {abort-text} [THEN statement | ELSE statement]
Syntax Elements
abort-text specifies an optional variable or quoted literal text string which is to be saved with the transaction
abort record.
Notes
A THEN or ELSE (or both) statement is required. The THEN clause will be executed if the transaction is
successfully aborted. The ELSE clause will be executed if the transaction abort fails for any reason.
Any record locks set during the transaction will be released upon successful completion.

TRANSEND
TRANSEND is used to mark the end of a successfully completed transaction.
Command Syntax
TRANSEND {end-text} [THEN statement | ELSE statement]
Syntax Elements
end-text specifies an optional variable or quoted literal text string which is to be saved with the transaction end
record.
Notes
A THEN or ELSE (or both) statement is required. The THEN clause will be executed if the transaction is
successfully ended. The ELSE clause will be executed if the transaction end fails for any reason.
Any record locks set during the transaction will be released upon successful completion.

TRANSQUERY
TRANSQUERY is used to detect whether or not a transaction is active in the current process.
Command Syntax
TRANSQUERY()
Notes
TRANSQUERY will return 1 (true) if the process is within a transaction boundary, or 0 (false) if it is not. In
other words, TRANSQUERY will return 1 (true) if a TRANSTART has been issued but a TRANSEND or
TRANSABORT has not yet been processed.

jBC

2-114

Programmers Reference Manual

TRANSTART
TRANSTART is used to mark the beginning of a transaction.
Command Syntax
TRANSTART {start-text} [THEN statement | ELSE statement]
Syntax Elements
start-text specifies an optional variable or quoted literal text string which is to be saved with the transaction start
record.
Notes
A THEN or ELSE (or both) statement is required. The THEN clause will be executed if the transaction is
successfully started. The ELSE clause will be executed if the transaction start fails for any reason.
Record locks set during the transaction will not be released until a TRANSEND or TRANSABORT statement is
processed.
A program (or series of programs) can only have one active transaction at one time. If another TRANSTART
statement is encountered whilst a transaction is active, a run-time error will be generated.

TRIM( )
The TRIM statement allows characters to be removed from a string in a number of ways.
Command Syntax
TRIM(expression1 {, expression2{, expression3}})
Syntax Elements
Expression1 specifies the string from which to trim characters.
Expression2 may optionally specify the character to remove from the string. If not specified then the space
character is assumed.
Expression3 evaluates to a single character specifies the type of trim to perform.
Notes
The trim types available for expression3 are as follows:
Type

Operation

Removes leading characters only.

Removes trailing characters only.

Removes leading and trailing characters.

Removes all occurrences of the character.

Removes leading, trailing and redundant characters.

Removes leading spaces and tabs.

Removes trailing spaces and tabs.

Leading, trailing and redundant spaces and tabs.

Examples
INPUT Answer
* Remove spaces and tabs (second parameter ignored)
Answer = TRIM(Answer, "", "D")
INPUT Joker

Programmers Reference Manual

2-115

jBC

* Remove all dots

Thief = TRIM(Joker, ".", "A")

TRIMB( )
The TRIMB() function is equivalent to TRIM(expression, " ", "T")

TRIMF( )
The TRIMF() function is equivalent to TRIM(expression, " ", "L")

UNASSIGNED
The UNASSIGNED() function allows a program to determine whether a variable has been assigned a value or
not.
Command Syntax
UNASSIGNED(variable)
Syntax Elements
Variable is the name of variable used elsewhere in the program.
Notes
The function returns Boolean TRUE if variable has not yet been assigned a value. The function returns Boolean
FALSE if variable has already been assigned a value.
See also:

ASSIGNED

Examples
IF UNASSIGNED(Var1) THEN
Var1 = "Assigned now!"
END

UNLOCK
The UNLOCK statement releases a previously LOCKed execution lock.
Command Syntax
UNLOCK {expression}
Syntax Elements
If expression is specified it should evaluate to the number of a held execution lock, which will then be released.
If expression is omitted then all execution locks held by the current program will be released.
Notes
No action is taken if the program attempts release an execution lock that it had not taken.
Examples
LOCK 23 ; LOCK 32
......
UNLOCK

WEOF
The WEOF statement allows the program to write an EOF mark on an attached tape device.

jBC

2-116

Programmers Reference Manual

Command Syntax
WEOF {ON expression}
Syntax Elements
Expression specifies the device channel to use. Should evaluate to a numeric integer argument in the range 0-9.
Default value is 0.
Notes
If the WEOF fails then the statements associated with any ELSE clause will be executed. SYSTEM(0) will
return the reason for the failure as follows:
Value
1
2

Meaning
There is no media attached to the channel
End of media found

Notes
A "tape" does not refer to magnetic tape devices only but any device that has been described to jBASE. Writing
device descriptors for jBASE is beyond the scope of this manual.
If no tape device has been assigned to the channel specified then the jBASE debugger is entered with an
appropriate message.
Examples
WEOF ON 5 ELSE
CRT "No tape device exists for channel 5"
END

WRITE
The WRITE statement allows a program to write a record into a previously opened file.
Command Syntax
WRITE variable1 ON {variable2,} expression {SETTING setvar} {ON ERROR statements}
Syntax Elements
Variable1 is the identifier containing the record to write.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
The expression should evaluate to a valid record key for the file.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
If a lock was being held on the record by this process it will be released by the WRITE.
If you wish to retain a lock on a record you should do so explicitly with the WRITEU statement.
Examples
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
WRITE Rec ON DCusts, "Xref" ON ERROR

Programmers Reference Manual

2-117

jBC

CRT "Xref not written to DICT Customers"

END

WRITELIST
WRITELIST allows the program to store a list held in a jBC variable to the global list file.
Command Syntax
WRITELIST variable ON expression {SETTING setvar} {ON ERROR statements}
Syntax Elements
Variable is the variable in which the list is held.
Expression should evaluate to the required list name. If expression is null, the list will be written to the default
external list.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
See also:

READLIST

Examples
* Create the list first
WRITELIST MyList ON "MyList"

WRITET
The WRITET statement enables data to be written to a range of tape devices between 0-9.
Command Syntax
WRITET variable {ON expression} THEN|ELSE statements
Syntax Elements
Variable is the variable that holds the data for writing to the tape device. Expression should evaluate to an
integer value in the range 0-9 and specifies which tape channel to read data from. If the ON clause is not
specified the WRITET will assume channel 0.
If the WRITET fails then the statements associated with any ELSE clause will be executed. SYSTEM(0) will
return the reason for the failure as follows:
Value
1
2

Meaning
There is no media attached to the channel
End of media found

Notes
A "tape" does not refer to magnetic tape devices only but any device that has been described to jBASE. Writing
device descriptors for jBASE is beyond the scope of this manual.
If no tape device has been assigned to the channel specified then the jBASE debugger is entered with an
appropriate message.
Where possible the record size is not limited to a single tape block and the entire record will be written blocked
to whatever block size has been allocated by the T-ATT command. However certain devices do not allow
jBASE to accomplish this (SCSI tape devices for instance).

jBC

2-118

Programmers Reference Manual

Examples
LOOP
WRITET TapeRec ON 5 ELSE
Reason = SYSTEM(0)
IF Reason = 2 THEN BREAK
CRT "ERROR"; STOP
END
REPEAT

;* done

WRITEU
The WRITEU statement allows a program to write a record into a previously opened file. An existing record
lock will be preserved.
Command Syntax
WRITEU variable1 ON {variable2,} expression {SETTING setvar} {ON ERROR statements}
Syntax Elements
Variable1 is the identifier holding the record to be written.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
The expression should evaluate to a valid record key for the file.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
If the statement fails to write the record then any statements associated with the ON ERROR clause are
executed.
The lock maintained by the WRITEU statement will be released by any of the following events:

The record is written to by the same program with WRITE, WRITEV or MATWRITE statements.

The record lock is released explicitly using the RELEASE statement.

The program stops normally or abnormally.

See also: READU, MATREADU, RELEASE

Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
WRITEU Rec FROM DCusts, "Xref" Setting Err ON ERROR
CRT I/O Error[:Err:]
ABORT
END

WRITEV
The WRITEV statement allows a program to write a specific field of a record in a previously opened file.
Command Syntax
WRITEV variable1 FROM {variable2,} expression1, expression2 {SETTING setvar} {ON ERROR
statements}

Programmers Reference Manual

2-119

jBC

Syntax Elements
Variable1 is the identifier holding the record to be written.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
Expression1 should evaluate to a valid record key for the file.
Expression2 should evaluate to a positive integer number. If the number is greater than the number of fields in
the record, null fields will be added to variable1. If Expression2 evaluates to a non-numeric argument, a run time
error will be generated.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error
Notes
The WRITEV statement will cause any lock held on the record by this program to be released.
If you wish to retain a lock on the record you should do so explicitly with the WRITEVU statement.
Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
WRITEV Rec FROM DCusts, "Xref",7 Setting Err ON ERROR
CRT I/O Error[:Err:]
ABORT
END

WRITEVU
The WRITEVU statement allows a program to write a specific field on a record in a previously opened file. An
existing record lock will be preserved.
Command Syntax
WRITEVU variable1 ON {variable2,} expression1, expression2 {SETTING setvar} {ON ERROR
statements}
Syntax Elements
Variable1 is the identifier holding the record to be written.
Variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN
statement. If variable2 is not specified then the default file is assumed (see OPEN statement).
Expression1 should evaluate to a valid record key for the file.
Expression2 should evaluate to a positive integer number. If the number is greater than the number of fields in
the record, null fields will be added to variable1. If Expression2 evaluates to a non-numeric argument, a run time
error will be generated.
If the SETTING clause is specified and the write fails, setvar will be set to one of the following values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error

jBC

2-120

Programmers Reference Manual

Notes
If the statement fails to write the record then any statements associated with the ON ERROR clause are
executed.
The lock taken by the WRITEVU statement will be released by any of the following events:
The record is written to by the same program with WRITE, WRITEV or MATWRITE statements.
The record lock is released explicitly using the RELEASE statement.
The program stops normally or abnormally.
See also: MATWRITEU, RELEASE, WRITE, WRITEU
Examples
OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
ABORT 201, "DICT Customers"
END
WRITEVU Rec ON DCusts, "Xref",1 SETTING Err ON ERROR
CRT I/O Error[:Err:]
ABORT
END

XTD( )
The XTD() function converts hexadecimal number into its decimal equivalent.
Command Syntax
XTD(expression)
Syntax Elements
Expression should evaluate to a valid hexadecimal string.
Notes
The conversion process will halt at the first character that is not a valid base 16 character in the set [0-9, A-F or
a-f].
Examples
A = "FF"
CRT XTD(A)
will print 255 to the terminal.

Programmers Reference Manual

2-121

jBC

Chapter 3: jCL

Introduction
This chapter shows you how to write and execute jCL (jBASE Command Language) programs. It also discusses
how jCL manipulates data in the various buffers and select 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.

Programmers Reference Manual

3-1

jCL

jCL Program Structure

A jCL program is stored as a text record in a file.
The first line of a jCL program is usually PQ or PQN, unless you have elected to run the program as a UNIX
executable (script), in which case the first line will contain #!usr/jbc/bin/jpq.
Subsequent lines contain jCL statements that can execute other programs, manipulate data in the buffers, control
the flow of program execution and so on.
jCL program statements comprise an 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:
()
FB
F-UREAD
MVA
RSUB

[]
F-CLEAR
F-WRITE
MVD
RTN

B
F-FREE
GOSUB
O
U

BO
F-KLOSE
H
P
X

F
F-OPEN
IBH
RI

F;
F-READ
IH
RO

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.

jCL

3-2

Programmers

Reference

Manual

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, or
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.

Programmers Reference Manual

3-3

jCL

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, lets 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.

jCL

3-4

Programmers

Reference

Manual

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.
Individual parameters within the PIB are referenced 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 or 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.

Programmers Reference Manual

3-5

jCL

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.
Each line of data placed in the SOB using the H command must be terminated 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 parameters sequence number. For example, you
might refer to the 10th parameter as %10.

jCL

3-6

Programmers

Reference

Manual

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
.
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) are 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
001
002
003
004

TEST1
ABC
DEF
GHI
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.

Programmers Reference Manual

3-7

jCL

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
#4
&4.19
!3

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

Refers to the 4th parameter in the current output buffer.
Refers to field 19 in file buffer 4.
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;
F-FREE
F-CLOSE

jCL

F-OPEN
F-READ
F-UREAD
FB
H

IBH
IBP
IF
IF (multivalued)
IF (mask)

IFN
IH
IP
L
MV

3-8

MVA
MVD
RI
S
T

Programmers

Reference

Manual

Hints and Tips

Branching
Wherever possible, avoid using the obsolete Mark command to control branching within the program. Using
labels and the GO commands 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 <CTRL \>. For example:
001 PQN
002 10 T "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/

Programmers Reference Manual

3-9

jCL

Puts the current date, in external format (D2/ yields dd/mm/yy or mm/dd/yy - depending on your
internationalisation 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
002
003
005
006
007

PQN
HGET-LIST listname
STON
HSORT filename WITH ...
H HEADING "..."
P

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.

Concatenation
Use an asterisk (*) to concatenate (join) a series of values. For example:
001
002
003
004

PQN
MV %2 string
MV %1 Text *%2* has been concatenated
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

3-10

Programmers

Reference

Manual

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

Input Buffer Commands

B

Moves the buffer pointer back to the previous parameter.

Moves the buffer pointer forward to the next parameter.

IBH

Inserts a text string containing embedded blanks into the active input buffer.

IH

Inserts a text string, creates a new null parameter, or nulls an existing parameter in the active input
buffer.

RI

Clears all or part of the primary input buffer, and can be used to clear the secondary input buffer.

Moves the input buffer pointer to a specified parameter or column.

Output Buffer Commands

BO

Moves the active output buffer pointer back one parameter.

Inserts a literal into the active output buffer.

RO

Clears both output buffers and selects the primary as active.

STOFF Selects the primary as the active output buffer.

STON Selects the secondary (stack) as the active output buffer.

Data Movement Commands

A

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

MS

Moves the secondary input buffer contents to the primary input buffer.

MV

Copies data between primary input buffer, active output buffer, file buffers and select registers.

MVA

Copies the specified source into the destination buffer and stores it as a multivalue.

MVD

deletes data from a multivalued parameter in the destination buffer.

Input/Output Buffer Operations

IBN

Accepts input from the terminal as a single parameter with all blanks intact and places it in the
secondary input buffer.

IBP

Accepts input from the terminal as a single parameter with all blanks intact and places it in the specified
buffer or the active input buffer.

IN

Accepts input from the terminal and places it in the secondary input buffer.

IP

Accepts input from the terminal and places it in the specified buffer or the active input buffer.

IT

Transfers a tape record to the primary input buffer.

Jump and Branch Operations

()

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

[]

Calls an external jCL program routine.

G, GO, Transfers control to the jCL program statement with the specified label.
GOTO
GO B

Transfers control backward to the previous M (mark) command and continues execution from that
point.

Programmers Reference Manual

3-11

jCL

GO F

Transfers control forward to the next M (mark) command and continues execution from that point.

GOSUB Transfers control to the local subroutine with the specified label.
M

Marks a location to which a GO F or a GO B command transfers control.

RSUB terminates execution of the local subroutine and returns control to the statement following the GOSUB
that called the subroutine.
RTN

Returns control from an external jCL program subroutine to the jCL program that called the subroutine.

Conditional Operations
IF

Allows conditional execution of jCL program commands.

IF E

Tests for presence of an error condition after processing a shell command.

IFN

Performs numeric comparisons and allows conditional execution of jCL program commands.

File Operations
F-CLEAR, F-C

Clears the specified file buffer.

F-DELETE, F-D

Deletes an record from a file opened by an F-OPEN command.

F-FREE, F-F

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

F-KLOSE, F-K

Closes the specified file buffer.

F-OPEN, F-O

Clears and opens a file buffer to allow reads and writes.

F-READ, F-R

Reads a record from a file into a file buffer.

F-UREAD, F-UR

Reads a record from a file into a file buffer and locks the record.

F-WRITE, F-W

Writes the contents of the specified file buffer to a file.

FB

Reads an record into a special 'fast buffer' without first opening the file.

Arithmetic Operators
+

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

Subtracts an integer from the current parameter in the active input buffer.

F;

Performs arithmetic functions on constants and buffer parameters.

Processing
P

Executes the shell command in the primary output buffer.

PU

Executes the UNIX command in the primary output buffer, using the UNIX shell.

Terminal and Printer Output

L

Formats output to the printer.

Outputs a text string to the terminal.

Produces complex, formatted terminal output and display buffer values.

jCL

3-12

Programmers

Reference

Manual

Debugging
C or *

Includes a comment in a jCL program.

Displays all or part of the active input buffer.

DEBUG Turns debug on or off.

TR

Invokes a trace for a jCL program and displays each command on the terminal before it is executed.

PP

Displays the command in the output buffer and prompts to continue.

PW

Displays the command in the output buffer and prompts to continue.

Exiting
()

Terminates the current jCL program and begins execution of another jCL program.

Halts execution of a jCL program and returns control to the shell.

Programmers Reference Manual

3-13

jCL

jCL Command Syntax

()
Terminates the current jCL program and begins execution of (chains to) another jCL program.
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, minimising 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)

jCL

3-14

Programmers

Reference

Manual

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.
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.
Syntax
+n
Syntax Elements
n is the integer to be added.

Programmers Reference Manual

3-15

jCL

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^050^333

AAA^+20^333

Example 2
Command PIB Before

PIB After

+100

BBB^100^44

BBB^AA^44

Example 3
Command PIB Before

PIB After

+51

ABC^0051^55

ABC^0000^55

Subtracts an integer from the current parameter in the active input buffer.
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
-300
AAA^345^666

PIB After
AAA^045^666

Example 2
Command PIB Before
-20
AAA^ABC^666

PIB After
AAA^-20^666

Example 3
Command PIB Before
jCL

PIB After
3-16

Programmers

Reference

Manual

-50

AAA^-50^666

AAA^-100^666

Example 4
001
002
003
004
005
006
007
008
009

PQN
OEnter a number+
S5
IBP
+7
T %5
-3
T %5
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.

A
Copies a parameter from the active input buffer to the active output buffer.
Syntax
A{c|\}{p}
A{c|\}{p}({n},m)
Syntax Elements
c specifies a character to surround the string being copied. Can be any non-numeric character except left
parenthesis ( or backslash \.
\ specifies that the value is to be concatenated with the current parameter in the active output buffer.
p specifies the number of the parameter to be copied. If p is not specified, the current parameter will be copied.
n specifies the starting column in the PIB. Copying continues until the end of the parameter is reached or the
number of characters specified by m have been copied.
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
Command PIB Before

PIB After

AAA^SALES^JAN

AAA^SALES^JAN

Programmers Reference Manual

3-17

jCL

POB Before

POB After

LIST^

LIST^SALES^

Note the position of the buffer pointer after you issue the A command.
Example 2
Command PIB Before
A

PIB After

AAA^SALES^JAN

AAA^SALES^JAN

POB Before

POB After

LIST^SALES^

LIST^SALES^JAN^

Issuing an A3 command would have achieved the same result, except that the starting position of the PIB
pointer would have been immaterial.
Example 3
Command PIB Before

PIB After

A\

ABC^DEF^GHI

ABC^DEF^GHI

POB Before

POB After

XXX^

XXXABC^

Example 4
Command PIB Before

PIB After

A2(2,-2) ABC^MYLIST^JKL

ABC^MYLIST^JKL

POB Before

POB After

SAVE-LIST

SAVE-LIST MYLIST

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.

B
Moves the active input buffer pointer back to the previous parameter.
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
Command PIB Before
B

PIB After

ABC^DEF^GHIJK

jCL

ABC^DEF^GHIJK

3-18

Programmers

Reference

Manual

Example 2
Command PIB Before
B

PIB After

ABC^DEF^GHIJK

ABC^DEF^GHIJK

BO
Moves the active output buffer pointer back by one parameter.
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
Command POB Before
BO

POB After

ABC^DEF^GHIJK

ABC^DEF^GHIJK

Example 2
Command SOB Before

SOB After

BO

SAVE-LIST

SAVE-LIST

C
Defines a comment.
Syntax
C
*
Notes
The C command indicates that the following text is a comment. All comments are ignored at run-time. Use
comments to improve the readability of a program or to help when you are debugging.
Typically, the first few lines of a jCL program are used to describe the program, identify the programmer and
record the date it was last modified.
Comments can be used within grouped commands (more than one command on a single line) but make sure that
you only use them where they will not conflict with normal command syntax.
Do not include too many comment lines, they may slow down execution.
Example
001
002
003
004
005
006
007
008
009

PQN
C This program will...
C Created by A. Programmer, dd/mm/yy
C Last modified by:...
RI
RO
10 T C, (5, 10), "Password :",+
HECHO OFF
P

Programmers Reference Manual

3-19

jCL

010
011
012
.
.
.

IP %1 \C Input password
HECHO ON
P

Lines 2 to 4 are comment lines. Line 10 has a comment after an input command (the \ is a subvalue mark
<CTRL \>).

D
Displays the current parameter of the active input buffer or specific parameters from the PIB.
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
Command Active Input Buffer

Display

DEF

ABC^DEF^GHI

Example 2
Command Primary Input Buffer Display
D3

ABC^DEF^GHI

GHI

Example 3
Command Primary Input Buffer Display
D0

ABC^DEF^GHI

ABC^DEF^GHI

DE
Displays the current value of LastError.
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

3-20

Programmers

Reference

Manual

DEBUG
Turns debug function on or off.
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:
<RETURN> execute current line
?
display list of available commands
e
toggle last error display
f
toggle file buffer display
h
display list of available commands
i
toggle input buffer display
n
toggle next line display between one and two lines
o
toggle output buffer display
q
quit (terminate) program
x
exit DEBUG function
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).

F
Moves the active input buffer pointer forward to the next parameter.
Syntax
F
Notes
The input buffer pointer is moved forward to the next field mark, or to the end of the buffer.
Example 1
Command PIB Before

PIB After

ABC^DEF^GHI

ABC^DEF^GHI

Example 2
Command PIB Before

PIB After

ABC^DEF^GHI

ABC^DEF^GHI

F;
Provides a range of arithmetic functions.
Syntax
F;element{;element}...;?[P|r]
Syntax Elements
element

operators or operands - see below.

?P

moves the result (top stack entry) into the current parameter of the primary input buffer.

Programmers Reference Manual

3-21

jCL

?r

moves the result (top stack entry) into the reference r. Can be a direct or indirect reference to a
buffer.

Operators
+

Add last stack entry and penultimate stack entry. Store the result in stack entry 1.

Subtract last stack entry from penultimate stack entry. Store the result in stack entry 1.

Multiply the last two stack entries. Store the result in stack entry 1.

Divide stack entry 2 by stack entry 1. Store the result in stack entry 1.

Divide stack entry 2 by stack entry 1. Store the remainder in stack entry 1.

_ (underscore)

reverse the last two stack entries.

Operands
r

A direct or indirect reference to a buffer or select register value to be put on the stack.

{C}literal

Literal value specified by literal.

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
Command

PIB Before

PIB After

F;C100;%2;-;?%3

6^8^999^7^GHI

6^8^92^7^GHI

Stack

100

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

100
8

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

92

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

F-CLEAR
Clears the specified file buffer.
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.

jCL

3-22

Programmers

Reference

Manual

Notes
This command is equivalent to using the MV file-buffer.0 ,_ command
Example
001
002
003
.

PQN
F-C 1
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.)

F-DELETE
Deletes a record from a file.
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.

F-FREE
Releases a record lock set by the F-UREAD 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.

Programmers Reference Manual

3-23

jCL

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

F-KLOSE
Closes a specified file buffer.
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.

F-OPEN
Clears a file buffer and opens a file for reading and writing.
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

jCL

3-24

Programmers

Reference

Manual

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 1
001
002
003
004
.

PQN
F-OPEN 1 SALES
X ERROR: Cant find the Sales File!
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.

F-READ
Reads a record from an open file into a file buffer.
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
002
003

PQN
F-OPEN 1 SALES
X ERROR: Cant find the Sales File!

Programmers Reference Manual

3-25

jCL

004
.
015
016
017
.

T C, (5, 10), "Welcome to...",+

F-READ 1 ABC
X ERROR: Record ABC not found!
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.

F-UREAD
Reads and locks a record from an open file into a file buffer.
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 record is
unlocked by the other process.
Record locks are released by F-DELETE, F-WRITE or F-FREE commands, or when the program terminates.
It is good practise 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.

F-WRITE
Writes the contents of a file buffer as a record.
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.

jCL

3-26

Programmers

Reference

Manual

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
002
003
004
.
015
016
017
018
019
.

PQN
F-OPEN 1 SALES
X ERROR: Cant find the Sales File!
T C, (5, 10), "Welcome to...",+
F-UREAD 1 ABC
F-F 1 \ G 1002
T Record ABC found
MV &1.2 Field 2
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.

FB
Reads a record from a file into the special "fast" buffer without having to open the file first.
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 FOPEN 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.

Programmers Reference Manual

3-27

jCL

Example 1
001
002
003
004
.

PQN
FB SALES ABC
T ABC not on file / G 1001
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
002
003
004
005
006
007
.

PQN
T C, (5, 10), "Name :",+
IP %2
FB SALES %2
T "New record"
T "Area :",+
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.

G, GO or GOTO
Transfers control unconditionally to another location in the program.
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.
jCL

3-28

Programmers

Reference

Manual

Example 1
001
002
003
004
.
087
088
089
.

PQN
F-OPEN 1 SALES
G 1001
T C, (5, 10), "Welcome to...",+
1001 T ERROR: Cant find the Sales File!
IP %99
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
023
024
025
.

5 T "Option :",+
IP %1
IF %1 = A]B]C GO 10]20]30
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 recognised, control transfers back to label 5.

GO B
Transfers control to the statement following the most recent M (mark) command executed.
Syntax
GB
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:
Cant find mark at line n in programname
Example 1
001
.
010
011
012
013
014
015
016
017
.
025
026

PQN
MV #1 "SSELECT SALES BY MONTH"
STON
MV #1 "PQ-SELECT 1"
P
M
MV %1 !1
IF # %1 GO F
C Process the record
GO B
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.

Programmers Reference Manual

3-29

jCL

Example 2
001
.
009
010
011
012
013
014
015
016
017
018
019
.

PQN
MV
M
IF
M
IF
GO
30
GO
40
GO
50

%1 ,
# %1 GO 30
# %2 GO 40
50
MV %1 ABC
B
MV %2 DEF
B
...

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.

GO F
Transfers control to the statement containing the next M (mark) command.
Syntax
GF
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:
Cant find mark at line n in programname
Example
001
.
005
006
007
008
009
.

PQN
GO
10
MV
MV
M

F
MV %1 ABC
%6 DEF
%10 HIJ

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.

GOSUB
Transfers control to a specific subroutine.

jCL

3-30

Programmers

Reference

Manual

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
011
.
031
032
033

GOSUB 1000
T Returned from GOSUB
1000 T In subroutine
IP %1
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.

H
Places a text string in the active output buffer.
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.

Programmers Reference Manual

3-31

jCL

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
002
003

PQN
HSLEEP 10
P

Forces the process to sleep for 10 seconds.

Example 2
Command

POB Before

POB After

HCOPY

COPY

H SALES

COPY

COPY^SALES

H ABC

COPY^SALES

H-DEF

COPY^SALES^ABC

H (P)

COPY^SALES^ABC-DEF

COPY^SALES^ABC

COPY^SALES^ABC-DEF

COPY ^SALES^ABC-DEF^(P)

Note how COPY and SALES have become separate parameters but ABC and -DEF have been concatenated.
Example 3
001
002
003
004
005
006

PQN
HGET-LIST LISTA
STON
HCOPY SALES<
H(SALES.HOLD
P

IBH
Places text in the active input buffer whilst retaining embedded spaces and applying any required input/output
conversions.
Syntax
IBHtext
IBHreference;input-conversion;
IBHreference:output-conversion:
jCL

3-32

Programmers

Reference

Manual

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
Command

PIB Before

PIB After

IBHDEF GHI

ABC^XXX^Z

ABC^DEF GHI^Z

Example 2
Command

PIB Before

IBH XX

AA^BB^CC^DD

PIB After
AA^BB^CC^DD^ XX

Example 3
File buffer 1 contains:
000 Key
001 9873
Command

PIB Before

PIB After

IBH&1.1:D2:

AA^BB^CC^DD

AA^BB^11 JAN 95^DD

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.
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 (:).

Programmers Reference Manual

3-33

jCL

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 RETURN only, a null parameter will be created.
Example 1
Input

SIB Before

ABC

SIB After

XXX

ABC

XXX

ABC DEF

XXX

Example 2
ABC DEF
Example 3
<RETURN>

IBP
Prompts for input from the terminal. Input data is kept as a single parameter and embedded spaces are retained.
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
IBP?

PIB Before
AAA^BBB

Input
CCC

PIB After
AAA^BBB^CCC

Example 2
Command
IBP?

PIB Before
AA^BB^CC

Input
XX X

PIB After
AA^XX X^CC

jCL

3-34

Programmers

Reference

Manual

Example 3
PIB Before
ABC^DEF^GHI

Command
IBP?

Input
<RETURN>

PIB After
ABC^^GHI

Example 4
Command

File Buffer 2
Before

Input

File Buffer 2
After

IBP:&2.2

000
001
002
003

BBB

000
001
002
003

Input
<RETURN>

File Buffer 2
After

Key
AAA
XXX
CCC

Key
AAA
BBB
CCC

Example 5
Command

File Buffer 2
Before

IBP:&2.2

000
001
002
003

Key
AAA
XXX
CCC

000 Key
001 AAA
002
003 CCC

IF
Allows conditional execution of jCL commands based on the evaluation of an expression, or the presence (or
absence) of a reference.
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:
=
#
<
>
[
]

Equal to
Not equal to
Less than
Greater than
Less than or equal to
Greater than or equal to

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.

Programmers Reference Manual

3-35

jCL

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
022
023

IF %1 T %1 is not null
IF # %1 T %1 is null
...

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
022
023

IF &1.1 = ABC GO 10
MV %3 &1.1
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
011
009
012
013
014
015
016

T "Continue (Y/n) :",+

IP %1
S1
IF # A G 10
IF A(1,1) = Y G 10
IF A(1,1) = y G 10
XFinished
10 ...

If the user enters Y, y or <RETURN> to the prompt on line 11, execution will continue at label 10 on line 16.
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.
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.
jCL

3-36

Programmers

Reference

Manual

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

Programmers Reference Manual

3-37

jCL

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:
(nA)

Tests for n alphabetic characters. If n is 0 (zero), any number (or no) alphabetic characters are
assumed to match.

(nC)

Tests for n alphanumeric characters. If n is 0 (zero), any number (or no) alphanumeric
characters are assumed to match.

(nN)

Tests for n numeric characters. If n is 0 (zero), any number (or no) numeric characters are
assumed to match.

(nP)

Tests for n printable characters. If n is 0 (zero), any number (or no) printable characters are
assumed to match.

(nX)

Tests for n characters. If n is 0 (zero), any number (or no) characters are assumed to match.

(string)

Tests for one or more specified characters. If string contains numeric characters, %, #, &, !, or
spaces, it must be enclosed in quotes.

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 # (2NAAA) 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.
jCL

3-38

Programmers

Reference

Manual

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.

IF E
Conditionally executes a command depending on the presence or absence of an error message after running a
shell 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 ERRMSG 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
022
023

HCOUNT SALES WITH VALUE > 1000

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

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

Programmers Reference Manual

3-39

jCL

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
022
023

HSELECT SALES WITH VALUE > 1000

PH
IF S G 100

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

IFN
Allows conditional execution of commands depending on the result of numeric comparisons.
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:
=
#
<
>
[
]

Equal to
Not equal to
Less than
Greater than
Less than or equal to
Greater than or equal to

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.

jCL

3-40

Programmers

Reference

Manual

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.

IH
Places a text string in the active input buffer, clears an existing parameter, or creates new null parameters.
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.

Programmers Reference Manual

3-41

jCL

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
Command

PIB Before

PIB After

IHXXX

AB^CD^YY^ZZ

AB^CD^XXX^ZZ

Example 2
Command

PIB Before

PIB After

IH GH IJ

AB^CD^EF

AB^CD^EF^GH^IJ

Example 3
%3 contains 9873
Command

PIB Before

PIB After

IH%3:D2:

AB^CD^9873^GH

AB^11^JAN^95^9873^GH

Example 4
Command

PIB Before

PIB After

IH%4

AB^CD^EF^GH IJ^

AB^CD^EF^GH^IJ^

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
Command

PIB Before

PIB After

IH\

AB^CD^EF^GH

AB^CD^^GH

Example 6
Command

PIB Before

PIB After

S(7)
IH\

AB^CDEFGH^IJK

AB^CDE^IJK

This example demonstrates how to truncate a parameter..

Example 7
Command

PIB Before

PIB After

IH \

AB^CD^EF^GH

AB^CD^^EF^GH

Example 8
Command

PIB Before

PIB After

IH \

AB^CDEFGH^IJK

AB^CDE^^FGH^IJK

jCL

3-42

Programmers

Reference

Manual

IN
Prompts for input and places it in the secondary input buffer. Selects the secondary input buffer as the active
buffer input.
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 RETURN 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
Input

SIB Before

SIB After

XYZ

ABC^DEF

ABC

ABC

Example 2
ABC DEF
Example 3
<RETURN>

WWW^XXX

IP
Prompts for input and places it into the active input buffer or a nominated buffer.
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.

Programmers Reference Manual

3-43

jCL

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
Command
IP?

PIB Before
AAA^BBB

Input
CCC

PIB After
AAA^BBB^CCC

Example 2
Command
IP?

PIB Before
AA^BB^CC

Input
XX X

PIB After
AA^XX^X^CC

Example 3
Command
IP?

PIB Before
ABC^DEF^GHI

Input
<RETURN>

PIB After
ABC^^GHI

Example 4
Command

File Buffer 2
Before

Input

File Buffer 2
After

IP:&2.2

000
001
002
003

BBB

000
001
002
003

Input
BB CC DD

File Buffer 2
After

Key
AAA
XXX
CCC

Key
AAA
BBB
CCC

Example 5
Command

File Buffer 2
Before

IP:&2.2

000
001
002
003

Key
AAA
XXX
DDD

000
001
002
003
004

Key
AAA
BB
CC
DD

IT
Reads a tape record into the primary input buffer.
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.

jCL

3-44

Programmers

Reference

Manual

Example
Command

PIB Before

PIB After

IT

ABC

tape data

L
Formats printed output.
Syntax
L element{, element}...
Syntax Elements
element can be any of the following:
"text"

Prints literal text. Enclose the text in quotes.

r{;input;} Prints the result of a direct or indirect reference to a buffer or select register (r). If required, a
jQL input conversion can be applied before output.
r{:output:} Prints the result of a direct or indirect reference to a buffer or select register (r). If required, a
jQL output conversion can be applied before output.
n

Skips n lines before printing. You cannot use n in a HDR print format specification.

(c)

Sets the print position to column number c. Can be a direct or indirect reference to a buffer or
select register.

Suppresses NEWLINE being output at the end of the L command. You cannot use + in a
HDR print format specification.

Closes the print file and forces printing. You cannot use C in a HDR print format
specification.

Ejects to top-of-form (form feed). You cannot use E in a HDR print format specification.

Redirects subsequent printer output to the terminal. Normally only used for debugging. Must
be the only element in an L command.

HDR

Allows you to define a page heading. HDR, must be the first element in the L command.

Outputs a line feed in the heading. Only used in a HDR specification.

Outputs the current page number in a heading. Only used in a HDR specification.

Outputs current time and date in a heading. Only used in a HDR specification.

Resets the current page number in a heading to zero. Only used in a HDR specification.

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 (see the jLP chapter of the System Administrators Reference Manual).
Continuation lines (which do not start with an L) can be created 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.

Programmers Reference Manual

3-45

jCL

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

10:30:45

10 JAN 1995

Sales Report for Quarter 4

M
Marks a destination for a GO F or GO B 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.

MS
Move the entire content of the secondary input buffer to the primary input buffer.
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
002
003
004
005
006
008

jCL

PQN
HSP-ASSIGN HS
P
HCOPY SALES ABC (P
P
S10
MS

3-46

Programmers

Reference

Manual

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

MV
Copies data between buffers or between buffers and select registers.
Syntax
MV destination source{,source}...{,*{n}}{,_}
or
MV destination source{*source}...
Syntax Elements
destination is a direct or indirect reference to the destination buffer or select register which is to receive that
data.
source is the data you want to copy. Can be a direct or indirect reference to a buffer or select register, or a literal
string enclosed in single or double quotes.
,* copies all source parameters starting with the specified parameter. If * is the last operand in the source field,
the destination buffer or select register will be truncated after the last copied parameter.
,*n copies the number of source parameters specified by n starting with the specified parameter. The destination
buffer or select register will not be truncated.
,_ specifies that the destination is to be truncated after the source is copied.
*source specifies the source values are to be concatenated into one field in the destination buffer or select
register.
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.

Programmers Reference Manual

3-47

jCL

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.
Intervening parameters in the destination can be preserved by using commas as place holders in the source. 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
Command

PIB Before

PIB After

MV %5 "XXX"

ABC

ABC^^^^XXX

Example 2
Command
MV %4 %1

PIB Before

PIB After

ABC^DEF^GHI

ABC^DEF^GHI^ABC

Example 3
PIB contains:
QTR^ABC^DEF
Command

POB Before

POB After

MV #3 %1

SORT^SALES^

SORT^SALES^QTR^

Example 4
Command
MV %1 "AA",,"CC"

PIB Before

PIB After

XX^BB^YY^ZZ

AA^BB^CC^ZZ

Command

File Buffer 1
Before

File Buffer 1
After

MV &1.1 &2.2,*

000
001
002
003
004

000
001
002
003
004

Example 5
File buffer 2 contains:
000
001
002
003

Key
111
AAA
BBB

KEY1
WWW
XXX
YYY
ZZZ

KEY1
AAA
BBB
YYY
ZZZ

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

jCL

3-48

Programmers

Reference

Manual

Command
MV &2.1 %3,_

File Buffer 2
Before
000 Key
001 XXX
002 YYY

File Buffer 2
After
000 Key
001 GHI

MVA
Copies a value from the source to the destination buffer and stores it as a multivalue.
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 copied 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
Command

File Buffer 1
Before

File Buffer 1
After

MVA &1.1 %3

000 Key
001 FFF]HHH
002 YYY

000 Key
001 FFF]GHI]HHH
002 YYY

Command

File Buffer 1
Before

File Buffer 1
After

MVA &1.1 &2.1

000 Key
001 FFF]HHH
002 YYY

000 Key
001 FFF]GG]YY]HHH
002 YYY

Example 2
File buffer 2 contains:
000 Key
001 GG]YY
002 AAA

MVD
Deletes a value from a multivalued parameter in the target buffer.
Syntax
MVD target source

Programmers Reference Manual

3-49

jCL

Syntax Elements
target is a direct or indirect reference to a buffer or select register which contains the data to be deleted.
source is the data you want to delete. Can be a literal string, or a direct or indirect reference to a buffer or select
register.
Notes
Values in the target must be in ascending ASCII sequence, otherwise the result of the command will be
unpredictable.
If the source does not exist or if the multivalue cannot be matched, the command will no effect, except perhaps
to move the buffer pointer.
If the source element exists more than once in the target parameter, only the first occurrence will be deleted.
If the target is the primary input buffer, the buffer pointer will be left at the beginning of the specified target
parameter.
Example
Command

File Buffer 1
Before

File Buffer 1
After

MVD &1.1 DEF

000 Key
001 ABC]DEF]GHI
002 YYY

000 Key
001 ABC]GHI
002 YYY

O
Outputs a text string to the terminal.
Syntax
O{text}{+}
Syntax Elements
text is the text to be displayed.
+ inhibits a NEWLINE at the end of the output and leaves the cursor positioned to the right of the last character
displayed. This is often used when prompting for input.
Notes
The O command has largely been replaced by the T command which also provides cursor positioning and
special display features.
If no text is supplied, a blank line will be output.
Example 1
Command
O
SALES SYSTEM
O
OEnter Password +
IP:

Terminal output
SALES SYSTEM
Enter Password :

P
Submits the shell command created in the primary output buffer for execution.
Syntax
P{P}{H}{Ln}{X}{U}{W}

jCL

3-50

Programmers

Reference

Manual

Syntax Elements
P displays the primary and secondary output buffers. In ROS emulation mode, displays the command and
prompts to continue. Normally only used for testing or debugging.
H suppresses (hushes) any terminal output that would normally be displayed. The H and Ln options can be
combined as PHLn.
Ln sets an execution lock where n represents a lock number from 0 to 255. The lock is after command has been
executed. Any other process attempting to set the same lock is forced to wait. The H and Ln options can be
combined as PHLn.
X terminates the program after the command is executed. Cannot be used with any other options.
U specifies that the command is to be submitted for execution by UNIX.
W causes the command to behave like PP when used in a non-ROS emulation.
Notes
When the P command is executed, control is passed to the shell and only returns when the shell process has been
completed. After the P command has been executed, both output buffers are cleared and the stack is turned off.
Commands and data in the secondary output buffer are made available to processes which require further input.
If you need to preserve buffer contents when passing control between jCL programs, use the ( ) or [ ] command
instead.
If you use the PP variants (PP, PPH, PPLn), the content of both output buffers will be displayed before they are
executed and you will be prompted with a question mark (?). Enter:
Y to continue.
S to cancel execution but continue the program.
N to cancel execution and exit the program.
Example 1
003
004

HLIST SALES QTR VALUE

P

Copy the jQL command LIST SALES QTR VALUE to the output buffer and execute it.
Example 2
003
004
005
006

HCOPY SALES ABC

STON
H(SALES.HOLD<
PP

Place the COPY command in the primary output buffer. Turn the stack on. Put the response to the TO: prompt
into the secondary input buffer. Issue the PP command to display the contents of the buffers and prompt for input
before continuing.
Example 3
003
006

Henv | grep EMULATE

PU

Issue the UNIX grep command.

RI
Resets (clears) the primary and secondary input buffers.
Syntax
RI

Programmers Reference Manual

3-51

jCL

RIp
RI(n)
Syntax Elements
p specifies starting parameter from which to clear to the end of the buffer. Can be a number, or a direct or
indirect reference to a buffer or select register.
(n) specifies the starting column from which to clear to the end of the buffer. Can be a number, or a direct or
indirect reference to a buffer or select register.
Notes
The RI command clears the entire PIB and SIB.
RIp clears the PIB starting from parameter p and continuing to the end of the buffer.
RI(n) clears the PIB starting from parameter n and continuing to the end of the buffer.
The buffer pointer will be left at the end of the PIB. The primary input buffer becomes the active buffer and the
secondary input buffer will be cleared.
Example 1
Command PIB Before
RI

PIB After

ABC^DEF^GHI

Example 2
RI3

ABC^DEF^GHI

ABC^DEF

Example 3
RI(6)

ABC^DEF^GHI

ABC^D

RO
Resets (clears) the active output buffer.
Syntax
RO
Notes
The RO command clears the active output buffer.
The buffer pointer is left at the beginning of the buffer.
Example 1
Command POB Before
STOFF
RO

POB After

ABC^DEF

Example 1
Command SOB Before
STON
RO

GHI^JKL

jCL

SOB After

3-52

Programmers

Reference

Manual

RSUB
Terminates execution of a local subroutine and returns control to a statement line following the GOSUB
command that called the subroutine.
Syntax
RSUB {n}
Syntax Elements
n specifies that control should be returned to the n'th statement line after the calling GOSUB. Can be a number,
or a direct or indirect reference to a buffer or select register.
Notes
If n is not specified, control will return to the statement immediately following the calling GOSUB.
An RSUB without a corresponding GOSUB will ignored.
Example 1
010
011
012
.
051
052
052
053

GOSUB 1001
...
...
1001 T Press <CR> to continue...,+
S10
IP?
RSUB

The RSUB command on line 53 will return control to line 11.

Example 2
010
011
012
.
051
052
052
053

GOSUB 1001
...
...
1001 T Press <CR> to continue...,+
S10
IP?
RSUB 2

The RSUB command on line 53 will return control to line 12.

RTN
Terminates execution of an external subroutine and returns control to a statement following the [ ] command that
called the subroutine.
Syntax
RTN{n}
Syntax Elements
n specifies that control should be returned to the n'th statement line after the calling [ ] command. Can be a
number, or a direct or indirect reference to a buffer or select register.
Notes
If n is not specified, control will return to the statement immediately following the calling [ ] command.
A RTN without a corresponding [ ] command will terminate the program.

Programmers Reference Manual

3-53

jCL

Example 1
MENU
.
051 [SUBS MENU2]
052 ...
053 ...

MENU2
.
066 RTN

jCL program MENU calls MENU2 from line 51. When MENU2 reaches line 66, control will be returned to
MENU at line 52.
Example 2
MENU
.
051 [SUBS MENU2]
052 ...
053 ...

MENU2
.
066 RTN 2

jCL program MENU calls MENU2 from line 51. When MENU2 reaches line 66, control will be returned to
MENU at line 53.

S
Positions the primary input buffer pointer to a specified parameter or column, and selects the primary input
buffer as active.
Syntax
Sp
S(n)
Syntax Elements
p specifies the parameter to which the buffer pointer should be set. Can be a number, or a direct or indirect
reference to a buffer or select register.
(n) specifies the starting column to which the buffer pointer should be set. Can be a number, or a direct or
indirect reference to a buffer or select register.
Notes
Sp sets the buffer pointer to the field mark preceding parameter p.
If the specified column or parameter number is less than 2, the buffer pointer is placed at the beginning of the
active input buffer.
If the specified column or parameter number is beyond the end of the buffer, the buffer pointer will positioned at
the end of the buffer. Use the MV command to create parameters beyond the current end of the buffer.
All data in the secondary input buffer will be cleared.
Example 1
Command

PIB Before

PIB After

S3

ABC^DEF^GHI

ABC^DEF^GHI

Example 2
Command

PIB Before

PIB After

S(4)

12345^ABC

12345^ABC

jCL

3-54

Programmers

Reference

Manual

STOFF
Selects the primary output buffer as the active output buffer.
Syntax
STOFF
ST OFF
Notes
The stack can be turned on (STON) or off (STOFF) at any point within a jCL program.
At the start of a jCL program or after execution of an RO or P command, both output buffers will be empty, and
the stack will be off.
When the stack is off, H commands will place their data in the primary output buffer.

STON
Selects the secondary output buffer as the active output buffer.
Syntax
STON
ST ON
Notes
The STON command selects the SOB as the active output buffer. With the stack turned on, all data moved to an
output buffer with an MV, H or A command will be placed in the secondary output buffer.
The stack is often used to feed responses to interactive processes. It can also be used to store a series of
commands that you might need for example when you are dealing with select lists. For example, do a GETLIST, followed by a SORT-LIST and then run a jBC program.
Typically, you would create the command necessary to start the external job stream in the primary output buffer.
Next you would turn the stack on and store all the necessary responses (or commands) to the external process.
When you issue the P command to execute the external program, instead of taking its input from the terminal,
the program will be fed directly from the stack.
Terminated successive responses in the stack, with a less-than-character (<) to represent a RETURN key
depression. A single response or the last response in the stack does not require the less than character (<)
because a RETURN is generated by the P command.
Example
Command

POB Before

STON
H(SALES.HOLD<

COPY^SALES^ABC

POB After
COPY^SALES^ABC

SOB Before

SOB After
(SALES.HOLD<

T
Produces formatted terminal output.
Syntax
T element{, element}

Programmers Reference Manual

3-55

jCL

Syntax Elements
element is literal text, a reference or a formatting instruction:
text

Outputs the specified text. The text must be enclosed in double quotes.

r{;input;} Outputs the value obtained by the direct or indirect reference to a buffer or select register
specified by r. An optional jQL input conversion can be applied to the value prior to output.
r{:output:} Outputs the value obtained by the direct or indirect reference to a buffer or select register
specified by r. An optional jQL output conversion can be applied to the value prior to output.
(c,r)

Sets the cursor to the column c and row r. Can be direct or indirect buffer references.

(c)

Sets the cursor to the column c in the current row.

*cn

Outputs the character c n number of times. Value n can be a direct or indirect reference to a
buffer or select register.

(-n)

Provides terminal independent cursor control or video effects.

Outputs carriage return/line feed at the end of the output line. On ROS emulations, this clause
will inhibit the carriage return/line feed at the end of the output line.

Sounds terminal bell.

Clears the screen (outputs top-of-form).

One second delay. Often used when outputting error messages.

Ir

Converts the integer r (0 to 255) into its equivalent ASCII character. r can be a direct or
indirect reference to a buffer or select register that contains the integer.

Terminates a loop started with a T element. The elements between the T and L are executed
three times.

Sn

Outputs the number of spaces specified by n. The value n can be a direct or indirect reference
to a buffer or select register than contains the number of spaces.

Marks the top of a loop. The loop is terminated by the L element. The elements between T
and L are executed three times.

Moves the cursor up one line.

Xr

Converts the hex value r (x00 to xFF) into its equivalent ASCII character. The value r can
be a direct or indirect reference to a buffer or select register that contains the hex value.

Notes
The T command must be followed by a single space and each element must be separated by a comma.
Continuation lines (which do not start with a T) can be created by ending the preceding line with a comma.
Terminal Independent Cursor Control
Terminal independent cursor control is available using the same table of negative numbers as used by the jBC @
command. See the @ command in the jBC chapter for more details
Example 1
Commands
MV %1 99
T C, "%1 = ",%1

Terminal Output
clear screen
%1 = 99

Example 2
Commands

Terminal Output

T "Enter Password :",+

jCL

3-56

Programmers

Reference

Manual

IP %3

Enter Password : _

Example 3
Commands

Terminal Output

T *=6

======

Example 4
Commands

Terminal Output

MV %1 9873
T "DATE:",S2,%1:D2:

DATE:

11 JAN 95

Example 5
Command:

T (0,10),T,(0),"ERROR",B,D,(O),S5,D,L

Terminal Output:

ERROR bell (flashing)

Example 6
Commands

Terminal Output

T X1B,"J",+

erase to end of screen

or
T I27,I74,+
or
T (-3),+

TR
Traces jCL program execution and displays each command (source line) before it is executed.
Syntax
TR {ON}
TR OFF
Notes
The TR command will help you to test and debug your jCL programs.
TR or TR ON turns the trace on. TR OFF turns the trace off.
You can easily provide a general purpose trace program by creating a jCL program called TRACE in the file
defined by the JEDIFILENAME_MD environment variable. The TRACE program should look like this:
TRACE
001 PQN
002 TR ON
003 (%1 %2)
Run the TRACE program like this:
TRACE jcl_file jcl_program
If the target program relies on the initial content of the PIB, you will have to insert a line into the program like
this:
002 MV %1 %2,*
to move the PIB parameters to their required positions - otherwise the word TRACE will appear in %1 and the
jCL program name (normally in %1) will be in %2.

Programmers Reference Manual

3-57

jCL

Example
001
002
003
004
005
006
007
008
009
010
011
012
013
.

PQN
TR
MV %21 ,,
MV %98 1,A
S21
U147F
T MTS
S23
U147F
D D2
T Todays date is , %23
T the time is ,%21
TR OFF

will output:
MV %21 ,,
MV %98 1,A
S21
U147F
S23
U147F
T Todays date is , %23
Todays date is 01/01/95
T the time is ,%21
the time is 19:30:32
Line 2 turns the trace on. Line 13 turns it off.

U
Execute a user exit from a jCL program.
Syntax
Unxxx
Syntax Elements
n represents the user exit entry point
xxx is the id of the user exit.
Notes
User exits are user written functions which are used to manipulate buffers and perform tasks beyond the scope of
the standard jCL commands. For more details, refer to the Advanced Programmers Reference Manual.
See the Time and Date topic earlier in this chapter and the TR command for more examples of standard user
exits.
Example 1
012 U31AD
Returns the current port number.
Example 2
012 U307A
013 300
Causes the process to sleep for 300 seconds.

jCL

3-58

Programmers

Reference

Manual

Example 3
003 U407A
004 12:0
Causes the process to sleep until 12:10.

X
Halts execution of the program and returns control to the shell.
Syntax
X{text}{+}
Syntax Elements
text is any text to be displayed on exit.
+ suppress a NEWLINE at exit or after text output.
Notes
The X command returns control directly to the shell.
Example 1
F-OPEN 1 SALES
XCannot Open SALES file!
The X command stops execution of the program if the file SALES cannot be opened, and displays a suitable
message.

Programmers Reference Manual

3-59

jCL

List Processing Commands

The two shell commands associated with jCL which permit list handling are the PQ-SELECT and PQRESELECT commands. See the chapter on List Processing for more information on lists.

PQ-RESELECT
Executed from a jCL program, resets the pointer of a specified select register to the beginning of the list of
record keys.
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

PQ-SELECT
Executed from a jCL program, loads a list of keys into a select register.
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.

jCL

3-60

Programmers

Reference

Manual

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
002
003
004
005
006
007
008
009

PQN
HSSELECT SALES
STON
HPQ-SELECT 1
P
10 MV %1 !1
IF # %1 X Done
T %1
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.

Programmers Reference Manual

3-61

jCL

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-CLEAR
F-DELETE
F-FREE

F-KLOSE
F-OPEN
F-READ
F-UREAD

F-WRITE
FB
IBH
IBP

L
MS
MV
MVA

MVD

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

()
[]
+
C
D

jCL

G
GO B
GO F
GOSUB
IF
IF (mask)

IF E
IFN
M
P
RI
RO

RSUB
RTN
S
STOFF
STON
TR

3-62

U
X

Programmers

Reference

Manual

Chapter 4: jQL

Introduction
The jBASE Query Language (jQL) is a powerful and easy to use facility which allows you to retrieve data from
the database in a structured manner and to present the data in a flexible and easily understood format.
The language is characterised by the use of intuitive commands that resemble everyday English language
commands. For example, if you wanted to review a particular set of sales figures you might phrase your request
like this:
Show me the sales figures for January sorted in date order.
This request would translate into a jQL command like this:
LIST SALES WITH MONTH = JANUARY BY DATE
By using the jQL command LIST with a file named SALES and your predefined data definition records such as
MONTH and DATE, you can construct complex ad-hoc reports directly from the command line interface.
jQL contains a rich range commands for listing, sorting, selecting and controlling the presentation of your data.
jQL is a safe language for end users. With the exception of the EDELETE command, jQL will not alter the
contents of the source data files.
All jQL command sentences begin with a verb-like command such as LIST or SELECT, followed by a file name
such as SALES or PERSONNEL, and then a series of qualifiers and modifiers with which you control elements
such as eligible data, report formatting, any totals that you want to appear and so on.
Most data files on the system will have two storage areas assigned, one for the data (the data section) and one for
the data definition records (the dictionary section). Some files might be single level and others might have
multiple data sections. See the File Management chapter of the System Administrators Guide for more details.
Typically, all of the data fields in a file will be defined by data definition records kept in the dictionary portion
of the file. These data definition records do not have to exist - you can use defaults provided in the environment
variables or even the dictionaries of other files - but where you need to manipulate say dates (which are held in
internal format), or to join data that is held in different files (perhaps even on remote systems), you will find that
one or more definition records will be required for each data field.
The data definition records are simple to create and maintain. They allow you to specify for example, the
position of the data in a record (its field number), a narrative to be used as a column heading, any input or output
conversions required (such as for dates), the data type (left or right justified, or text that will break on word
boundaries) and a column width which will be used in the reports.
Input and output conversion codes can also be used to manipulate the data by performing mathematical
functions, concatenating fields, or by extracting specific data from the field.

Programmers Reference Manual

4-1

jQL

jQL Command Sentence Construction

A jQL command sentence must contain at least a command and a file name. The command specifies the process
to be performed and the filename indicates the initial data source.
Optional clauses can be added to refine the basic command. You can use clauses to control the range of eligible
record keys, define selection and sorting criteria, or to specify the format of the output, and so on.

Command Syntax
jQL-command file-specifier {record-list} {selection-criteria} {sort-criteria} {USING file-specifier} {outputspecification} {format-specification} {(options}
Syntax Elements
jQL-command is one of the verb-like commands detailed later. Most commands will accept any or all of the
optional clauses.
file-specifier identifies the main data file to be processed. Usually the data section of a file, but could be a
dictionary or a secondary data area.
record-list defines which records will be eligible for processing. Comprises an explicit list of record keys or
record selection clauses. An explicit list comprises one or more record keys enclosed in single or double quotes.
A selection clause uses value strings enclosed in single or double quotes and has at least one relational operator.
If no record list is supplied, all records in the file will be eligible for processing unless an implicit record list is
provided by preceding the command with a selection command such as GET-LIST or SELECT.
selection-criteria qualify the records to be processed. Comprises a selection connective (WITH or IF) followed
by a field name. Field names can be followed by relational operators and value strings enclosed in double
quotes.
sort-criteria specify the order in which data is to be listed. Comprises a sort modifier, such as BY or BY-DSND,
followed by a field name. Can also be used to explode a report by sorting lines corresponding to multivalued
fields by value, and to limit the output of values (see output-specification).
USING file-specifier defines an alternate file to be used as the dictionary. There is no restriction of the number
of USING clauses that can be included in a jQL sentence.
output-specification comprises of the names of fields to be included in the report, optionally preceded by a
TOTAL or BREAK-ON connective. Print limiters (values strings enclosed in double quotes after the field name,
optionally preceded by relational operators) can be used to restrict multivalue output.
format-specification comprises modifiers, such as HEADING, ID-SUPP, and DBL-SPC, that define the overall
format of the report.
options comprise letters enclosed in parentheses which modify the action of the command - to redirect output to
a printer for example.
Notes
Any element of a jQL command sentence (with the exception of the command and filename) can be substituted
with a macro - see later.

Reserved Words and Symbols

The following words and symbols have specific meanings when used in a jQL sentence. They should only be
used as described later in this chapter.
!
<
=<
AFTER
ANY

jQL

#
<=
>=
AN
ARE

&
=
A
AND
BEFORE

4-2

Programmers

Reference

Manual

BETWEEN
BY
BY-EXP-DSND
COL-HDR-SUPP
DBL-SPC
EACH
ESEARCH
FOR
GRAND-TOTAL
HEADER
IF
LIST
LT
NOPAGE
ONLY
PG
SORT
SSELECT
SUPP
TAPE
USING
WITHIN

BREAK-ON
BY-DSND
CAPTION
COUNT
DET-SUPP
EDELETE
EVERY
FOOTING
GT
HEADING
IN
LIST-LABEL
NE
NOT
OR
REFORMAT
SORT-LABEL
SUBVALUE
T-DUMP
THE
VALUE
WITHOUT

BSELECT
BY-EXP
CHECK-SUM
DATA
DICT
EQ
FILE
GE
HDR-SUPP
ID-SUPP
LE
LPTR
NO
OF
PAGE
SELECT
SREFORMAT
SUM
T-LOAD
TOTAL
WITH

Entering a jQL Command Sentence

A jQL command sentence is entered at the shell in response to a command prompt (:) or a select prompt (>). The
select prompt is displayed if an implicit record list has been created by a command such as SELECT or GETLIST whilst in jSHELL. Each sentence must start with a jQL command and can be of any length. Having
constructed your sentence, you submit it for processing by pressing the RETURN key.
If you enter an invalid command, the system will reject it and display an appropriate error message.
Example
SORT SALES WITH PART.NO = ABC] BY POSTCODE CUST.NAME POSTCODE TOTAL
VALUE DBL-SPC HDR-SUPP (P
where:
SORT is the jQL command.
SALES is the filename.
WITH PART.NO = ABC] is the selection criterion. Select all records which contain a part number that starts
with ABC.
BY POSTCODE is the sort criterion.
CUST.NAME POSTCODE TOTAL VALUE is the output specification. Column 1 will contain the key of the
SALES file, column 2 will contain the customer name and column 3 will contain the POSTCODE. Column 4
will contain VALUE and will be totalled at the end of the report.
DBL-SPC HDR-SUPP are the format specifications. Double-space the lines and suppress the automatic header.
(P is an option. Redirect output to the system printer, rather than to the terminal.
PART.NO, CUST.NAME, POSTCODE and VALUE are references to data definition records which are defined
in the dictionary level of the SALES file.

Default Data Definition Records

When you issue a jQL command that does not contain specific references to data definition records, and you do
not suppress output of the report detail, the system will attempt to locate any default data definition records that
you may have set up.

Programmers Reference Manual

4-3

jQL

For example, if you issue the command LIST SALES, the system will look in the dictionary of the SALES file
for a data definition record named 1. If it finds 1, this will become the default output for column two. The
system will then look for a data definition record named 2 and so until the next data definition record is not
found. If 1 is not found in the file dictionary, the system will search the default dictionaries for the same
sequence of data definition records.
When you issue a jQL command that does contain specific references to data definition records, the system will
first attempt to locate each data definition record in the dictionary of the file (or in the file specified in a USING
clause). If it fails to locate the record any file specified in the JBCDEFDICTS environment variable will be
searched. If the record is still not located, the file specified by the JEDIFILENAME_MD environment variable
will be searched.
For example, if you issue the command LIST SALES VALUE, the system will look in the dictionary of the
SALES file for a data definition record named VALUE. If it cannot find VALUE in the file dictionary, the
system will look in the file specified by the JEDIFILENAME_MD environment variable.
In this way, you can set up data-specific, file-specific or account-specific defaults to be used with any jQL
command.

jQL Output (Reports)

By default, output from a jQL command will be displayed on your terminal, in columnar format, with a pause at
the end of each page (screenful).
Output Device
You can redirect the output to a printer (or the currently-assigned Spooler device) by using the LPTR format
specifier or the P option.
Report Layout
If the columnar report will not fit in the current page width of the output device, it will be output in noncolumnar format where each field of each record occupies one row on the page.
Paging
If the report is displayed at the terminal and extends over more than one screen, press RETURN to view the next
screen. To exit the report without diaplaying any remaining screens, press <CTRL X>, <CTRL E> or q.

jQL Commands
A jQL command is the first word in the jQL sentence.
The commands available from a particular account may be defined in the file specified by the
JEDIFILENAME_MD environment variable.
If JEDIFILENAME_MD is not set, all of the commands will be available.
If JEDIFILENAME_MD has been set and the user attempts to issue a command that is not defined in the
specified file, they will receive an error message. You can therefore effectively restrict user access to commands
by removing the definitions of unwanted commands from the specified file.
A later section of this chapter gives detailed descriptions of all the jQL commands in alphabetical order.
The most frequently used jQL commands are:
LIST

SORT

SELECT

SSELECT

COUNT
REFORMAT
T-LOAD

EDELETE
SORT-LABEL

Other jQL commands are:

BSELECT
ESEARCH
SREFORMAT

CHECK-SUM
LIST-LABEL
T-DUMP

A number of jQL and non-jQL command can be used to generate an implicit list. These are:

jQL

4-4

Programmers

Reference

Manual

BSELECT
QSELECT

ESEARCH
SEARCH

FORM-LIST
SELECT

GET-LIST
SSELECT

Having generated an implicit list, you can pass it to another list processing command (to refine the list), a jQL
sentence, a shell command (such as COPY or EDIT), a jBC program, or a jCL program.

Throwaway Connectives
A number of words and symbols can be used in a jQL sentence simply to make it easier to read and understand.
These words are ignored by the system.
Throwaway connectives include:
A
ITEMS

AN
OF

ANY
PAGE

ARE
PG

DATA
THE

FILE

FOR

IN

Example
:LIST THE DATA IN THE SALES FILE WITH ANY S.CODE = ABC
The words THE, DATA, IN, FILE and ANY are ignored. This command is functionally equivalent to:
:LIST SALES WITH S.CODE = ABC

File Specifiers
The file specifier element of a jQL sentence defines the initial source of the data that will be used to build the
report.
Syntax
{DICT}{ ONLY}{ WITHIN}{ TAPE} filename{,data-section-name}
Syntax Elements
DICT specifies that the dictionary section of the named file is to be used as the source of data, and that the
JEDIFILENAME_MD is to be used as the source of the data definition records (unless you include a USING
clause - see later). DICT must be included immediately before the filename.
ONLY specifies that other than record keys, all data-related output is to be suppressed. ONLY can be included
anywhere on the command line.
WITHIN specifies a sublist such as bill of materials records. See the V Code - Sublist section for more
information.
TAPE tells the processor to retrieve the data from magnetic tape. The data must have been written in T-DUMP
format. When using the TAPE connective, filename is used indirectly to specify the default dictionary; although
you specify the data portion of the file, jQL will search the associated dictionary (DICT filename) for any data
definition records.
filename specifies the name of the file that is to be used as the initial source of data for the report. A filename
used without a modifier (SALES for example) specifies the primary data section of the named file. Can be
modified by DICT or data-section-name.
data-section-name specifies that the named (secondary) data section of filename is to be used as the initial
source of data for the report. data-section-name must be separated from filename by a comma but no space.

Record List Clause

The record list clause of a jQL sentence allows you to specify which records within the file are to be considered
as eligible for processing. If no list is given, all records in the file are assumed.
A record list takes one of three forms:
an explicit list of record keys
an implicit list of record keys
a record selection clause

Programmers Reference Manual

4-5

jQL

Record selection can be combined with an implicit list but not with an explicit list.
Any type of record list can be combined with the selection criteria discussed later.
Explicit List of Record Keys
An explicit list is a series of literal record keys, each enclosed in quotes.
Spaces between the keys are optional. An explicit list cannot contain relational operators, and any logical
connectives are ignored, as are special characters such as the left ignore, right ignore, and wild card characters.
If an implicit list is outstanding when you issue a command containing an explicit list, the implicit list will be
ignored.
When you use an explicit list, only the specified records will be processed. This is more efficient than using
selection criteria because the processor does not have to access all of the records in the file.
Syntax
key {key}...
Example
:LIST SALES ABC DEF GHI
Restricts report to records ABC, DEF and GHI only.
Implicit List of Record Keys
An implicit list of record keys is generated by executing a command such as SELECT or GET-LIST
immediately before executing the jQL command that is to use the list.
If you also specify a record selection clause, the jQL processor will AND its results with the implicit list to
further limit the records eligible for processing.
Record Selection Clause
A record selection clause imposes limits on the range of record keys that will be eligible for processing.
Each clause has at least one value string that defines a complete or partial record key, and at least one value
string must be preceded by a relational operator. The ability to perform relational tests differentiates the record
selection clause from an explicit record list.
Logical connectives (such as AND or OR) can be used to combine relational operations. Where a logical
connective is implied but not specified, jQL will use the OR connective.
The file will be searched for all record keys that match the criteria. If an implicit list of record keys is
outstanding, the initial search will be restricted to only those keys in the list.
Syntax
{value-string}... relational-operator value-string {{logical-connective} {relational-operator} valuestring}...
Syntax Elements
value-string is a text string enclosed in delimiters (usually single quotes but could be double quotes), which is
compared against record keys in the file. Can also include any or all of the following special characters:
Left ignore ([) at the beginning of the string to indicate that the record key may start with any
characters (for example, [DEF)
Right ignore (]) at the end to indicate that the record key may end with any characters (for example,
ABC]).
Left ignore ([) at the beginning and Right ignore (]) at the end of a string indicate that the record key
must contain the enclosed string. (for example, [DEF])

jQL

4-6

Programmers

Reference

Manual

 Wild card (^) anywhere within the string. Each wild card matches one character of any value (for
example, ABC^EF^HI).
relational-operator tests for a relationship between a record key and the value string. Value strings which are not
preceded by a relational-operator are assumed to be preceded by the equal operator (=). The result of a relational
test is true or false. Valid operators are shown below.
Symbol
=
#

>
>=
<
<=

Synonyms
EQ
NE
NOT
NO
GT
AFTER
GE
=>
LT
BEFORE
LE
=<

Meaning
Equal
Not Equal
Not Equal
Not Equal
Greater Than
After
Greater Than or Equal
Greater Than or Equal
Less Than
Before
Less Than or Equal
Less Than or Equal

logical-connective is an AND or OR connective which joins two relational expressions. The default connective
is OR so that if two relational expressions are given without a logical operator between them, records satisfying
either expression are selected (as if the OR connective had been used). The AND connective yields true if all
combined values are true, and false if any of the combined values are false. The OR connective yields true if any
of the combined values is true. Ampersand (&) is a synonym for AND, and exclamation point (!) is a synonym
for OR.
A special connective BETWEEN followed by two value strings can be used as a quick way of saying all values
greater than the first value string and less than the second. Value strings including special characters such as
the left ignore, right ignore, and wild card characters are not valid.
Notes
A value string can contain any printable character, excluding RETURN, LINE FEED, and system delimiters, but
it cannot contain the character with which it is delimited. For example, a value string enclosed in single quotes
may contain double quotes, but not single quotes. You are recommended to use single quotes within record
selection clauses and double quotes within ordinary selection criteria, except when you are searching for a record
key that includes single quotes.
Example 1
LIST SALES ABC DEF
Shows an explicit list of record keys. Accesses and reports on records ABC and DEF only.
Example 2
LIST SALES = ABC] DEF
Shows a record selection clause with an implied OR connective between the two value strings. Accesses all
records but only reports on records with keys that match ABCanything or DEF.
Example 3
:GET-LIST SALES.Q4
>LIST SALES GT DEF
Get an implied list (SALES.Q4). List only those records that are in the implied list and have keys greater than
DEF.

Selection Criteria Clause

The selection criteria clause allows you to specify data-specific limits on the range of records that will be eligible
for processing.

Programmers Reference Manual

4-7

jQL

If a record list of any type is outstanding when processing reaches the selection criteria, only those records in the
list will be submitted to the selection process. If a record-list is not outstanding, all records in the file are
considered by the selection process.
Each selection criterion specifies a field (data or key) that is to be tested to determine whether or not a record
should be selected. The selection criterion begins with the connective WITH (or IF) and must also include a field
name. The field name can be followed by a value selection clause otherwise it defaults to NE (not equal
NULL).
Syntax
WITH | IF {NOT} {EACH} field {value-selection clause} {{AND | OR} {WITH | IF} {NOT} {EACH}
field {value-selection clause}...}
value-selection-clause has the form:
{relational-operator} value string {{logical-connective} {relational-operator} value string}...
Syntax Elements
WITH or IF is the selection connective. Must be the first word of a selection criterion. WITH and IF are
synonymous. WITHOUT is a synonym for WITH NOT.
NOT inverts the test result of the selection criterion. NOT and NO are synonymous. WITHOUT is a synonym
for WITH NOT.
EACH specifies that every value in a multivalued or subvalued field must satisfy the value selection clause for
the record to be selected. EVERY is a synonym for EACH.
field is the name of a data definition record.
AND joins two or more selection criteria. All ANDed tests must yield true for the record to be selected. The
number of ANDed selection criteria that you can specify is virtually unlimited.
OR joins two or more sets of selection criteria that may or may not contain ANDed clauses. The OR connective
does not have to be used explicitly but is recommended to improve readability.
relational-operator tests for a relationship between the field data and the value string. Value strings which are
not preceded by a relational-operator are assumed to be preceded by the equal operator (=). The result of a
relational test is true or false. Valid operators are shown below.
Symbol
=
#

>
>=
<
<=

Synonyms
EQ
NE
NOT
NO
GT
AFTER
GE
=>
LT
BEFORE
LE
=<

Meaning
Equal
Not Equal
Not Equal
Not Equal
Greater Than
Greater Than
Greater Than or Equal
Greater Than or Equal
Less Than
Less Than
Less Than or Equal
Less Than or Equal

value-string is a text string enclosed in delimiters (usually single quotes but could be double quotes), which is
compared against the field data in the file. Can also include any or all of the following special characters:
Left ignore ([) at the beginning of the string to indicate that the data may start with any characters (for
example, [DEF)
Right ignore (]) at the end to indicate that the data may end with any characters (for example,
ABC]).
Wild card (^) anywhere within the string. Each wild card matches one character of any value (for
example, ABC^EF^HI).

jQL

4-8

Programmers

Reference

Manual

logical-connective is an AND or OR connective which joins two relational expressions. The default connective
is OR so that if two relational expressions are given without a logical operator between them, records satisfying
either expression are selected (as if the OR connective had been used). The AND connective yields true if all
combined values are true, and false if any of the combined values are false. The OR connective yields true if any
of the combined values is true. Ampersand (&) is a synonym for AND, and exclamation point (!) is a synonym
for OR.
A special connective BETWEEN followed by two value strings can be used as a quick way of saying all values
greater than the first value string and less than the second. For example, LIST file BETWEEN ABC XYZ.
Notes
A value string can contain any printable character, excluding RETURN, LINE FEED, and system delimiters, but
it cannot contain the character with which it is delimited. For example, a value string enclosed in double quotes
may contain single quotes, but not double quotes. You are recommended to use double quotes within the
selection criteria and single quotes within record selection clauses, except when you are searching for data that
includes double quotes.
Processing of Values and Subvalues
The selection processor works down to the subvalue level. If the value in a field does not have any subvalue
marks, the processor treats the value as though it had one subvalue. Similarly, if there are no value marks or
subvalue marks in the field, the processor treats the field as though it were a single subvalue.
For example:
WITH field will be true if any subvalue in any value in the field contains a value, that is, not all values
are null.
WITH NOT field will be true if no subvalue in any value contains a value, that is, all values are null.
WITH field value-selection-clause will be true if any subvalue satisfies the selection clause.
WITH NOT field value-selection-clause will be true if no subvalue satisfies the selection clause.
WITH EACH field value-selection-clause will be true if each value contains at least one subvalue that
satisfies the selection clause.
WITH NOT EACH field value-selection-clause will be true if any value does not contain a subvalue that
satisfies the selection clause.
Example 1
LIST SALES WITH S.CODE = ABC]
List the records in the SALES file in which the S.CODE field contains subvalues which start with ABC.
Example 2
LIST SALES WITH S.CODE = ABC] OR [DEF
List the records in the SALES file in which the S.CODE field contains subvalues which start with ABC or end
with DEF.
Example 3
LIST SALES WITH NO S.CODE = ABC] OR [DEF
List the records in the SALES file in which the S.CODE field does not contain subvalues which start with ABC
or end with DEF.
Example 4
LIST SALES WITH S.CODE = ABC AND WITH C.CODE = DEF
List the records in the SALES file in which the S.CODE field contains subvalues of ABC and the C.CODE field
contains subvalues of DEF.

Programmers Reference Manual

4-9

jQL

Example 5
LIST SALES WITH S.CODE = ABC AND WITH C.CODE = DEF OR WITH A.CODE #
GHI
List the records in the SALES file in which the S.CODE field contains subvalues of ABC and the C.CODE field
contains subvalues of DEF, or any record in which the A.CODE field does not contain subvalues of GHI.

Sort Criteria Clause

The sort criteria clause allows you to specify the order in which the records are to be presented in the report.
Syntax
BY field
BY-DSND field
BY-EXP field {print-limiter}
BY-EXP-DSND field {print-limiter}
Syntax Elements
print-limiter has the form:
{relational-operator} value string {{logical-connective} {relational-operator} value string}...
field is the name of a data definition record.
BY specifies a single value sort that will order the records according to an ascending sequence based on the first
value in the specified field.
BY-DSND specifies a single value sort that will order the records according to a descending sequence based on
the first value in the specified field.
BY-EXP specifies a multivalue sort that will order the multivalues of the specified field according to an
ascending sequence based on the first subvalue in each multivalued element.
BY-EXP-DSND specifies a multivalue sort that will order the multivalues of the specified field according to a
descending sequence based on the first subvalue in each multivalued element.
Notes
Each sort clause comprises a sort connective followed by a field name. The sort connective can specify an
ascending or descending sort sequence of single or multivalued fields. If you include more than one sort criteria
clause, the processor ranks the clauses in a left to right, most to least important hierarchical sequence. The record
key is always used the as the least important sort value.
The precise sorting sequence depends on whether a field is left- of right-justified.
Default Sort Order
If you do not specify a sort criteria clause for a sorting command, the report is output in ascending order by
record key. Left or right justification of the key is specified in field 9 of the file definition (pointer) record. The
default is a left justified sort.
Sort Order of Left Justified Data
When a left-justified field is sorted, the data is compared one character at a time, left to right. For this reason, the
number 2 will follow the number 11 in an ascending sequence. The number 02 would appear before 11 in an
ascending sequence.
Sorting Single Valued Fields
The sort connectives for single valued fields sort the record order according to the value of a field.

jQL

4-10

Programmers

Reference

Manual

The two sort connectives for single valued fields are:

BY for an ascending sort
BY-DSND for a descending sort
If a single value sort connective is used with a field that contains multivalues or subvalues, only the first value in
the field will be used as the sort key
Sorting Multivalued Fields
The sort connectives for multivalued fields sort values within a field.
The two sort connectives for multivalues are:
BY-EXP for ascending sort,
BY-EXP-DSND for descending sort.
If a multiple value sort connective is used with a field that contains subvalues, only the first subvalue in each
multivalue will be used as the sort key.
Each value is treated as if it were the only value so that each value occupies a line of output in the report. This
effectively explodes a record into multiple records.
You can limit the values that are sorted and output by including a print limiter with the multivalue sort
connectives.
When using a SELECT-type command the record list will be formatted like this:
record-key]multi-value#
where multi-value-# is the position of the multivalue within the field. This value can be used by the
READNEXT statement in a jBC program.
Example 1
SORT SALES WITH S.CODE = ABC] BY S.CODE
Selects the records in the SALES file in which the S.CODE field contains values which start with ABC. Outputs
the records in S.CODE order.
Example 2
SORT SALES WITH S.CODE = ABC] BY S.CODE BY-DSND VALUE
Selects the records in the SALES file in which the S.CODE field contains values which start with ABC. Outputs
the records in descending VALUE order within S.CODE order.
Example 3
SORT SALES BY-EXP P.CODE
Selects all the records in the SALES file and outputs the detail lines in key order within P.CODE order.

Using Clause
Comprises {DICT} filename{,data-section-name}, where DICT specifies the dictionary of filename, filename
specifies a file, and data-section-name specifies a secondary data section of filename.

Output Specification Clause

The output specification clause names the fields that are to be included in the report.
Syntax
field {print-limiter}...
TOTAL field {print-limiter}...
BREAK-ON field {text}{option{option}...}{text}

Programmers Reference Manual

4-11

jQL

print-limiter has the form:

{NOT} {relational operator} value string {{logical-connective} {NOT} {relational-operator} value
string}...
Syntax Elements
TOTAL specifies that a running total of a numeric field is to be maintained.
field is the name of a data definition record.
print-limiter suppresses output of values (to subvalue level) that do not match the clause. Suppressed values are
replaced with blanks. Any detail lines that would, as a result, be left blank are suppressed. Any totals produced
include just the values that match the limiting clause.
BREAK-ON specifies that control break is to be performed and a break line displayed, each time the value of
the field changes.
text comprises any printable characters except RETURN, LINE FEED, double quotes, single quotes, or system
delimiters.
option is one or more of the following options:
B

Break. Works in conjunction with the B option of the HEADING and FOOTING modifiers to
insert the break value in the heading or footing. See HEADING and FOOTING Modifier later.

Data. Suppresses the break if only one detail line has been output since the last break.

Line. Suppresses the blank line preceding the break data line. Overrides the U option if both are
specified.

Page. Causes each break to start a new page.

Rollover. Inhibits a page break until all the data associated with the current break has been output.

Underlines. Puts underlines on the line above the accumulated totals if the TOTAL modifier was
specified. Ignored if used with the L option.

Value. Causes the value of the control-break field to be inserted at this point in the BREAK-ON
output.

Notes
The order in which you specify the field names (with their connectives) controls the order in which they appear
in the report. However, a dependent field is always printed to the right of its controlling field.
If the sentence contains an output specification clause, any default data definition records in the dictionary will
be ignored.
TOTAL Connectives
The TOTAL connective specifies that a running total of the field is to be maintained, and that the total is to be
output at each control break and at the end of the report.
Use the GRAND-TOTAL modifier in the Format Specification clause to specify any text to be displayed on the
last total line.
TOTAL can also be used in conjunction with the BREAK-ON connective to display intermediate totals at the
control breaks.
BREAK-ON Connective
The BREAK-ON connective causes the immediately following field to be monitored for change.
Up to 15 breaks are allowed in one sentence. Breaks are treated in hierarchical left to right order. The first
BREAK-ON in the sentence is the highest level.

jQL

4-12

Programmers

Reference

Manual

When a change in the value of the field is detected a blank line will be output, followed by a line with three
asterisks, and then another blank line. If the BREAK-ON clause specifies text, the text will be output in place of
the asterisks. If the text is wider than the column width, the processor applies the same justification as the named
field.
You can suppress the BREAK-ON output by setting the column width of the field to zero.
BREAK-ON is used in conjunction with the TOTAL connective to generate subtotals. If the modifier DETSUPP is used with TOTAL and BREAK-ON, only the subtotal and grand-total lines will be displayed.
Controlling and Dependent Fields
Controlling and dependent fields provide a method for creating sublists from records.
A controlling field is one which has the code D1 in field 8 of its data definition record and points to its
dependent fields. A dependent field is one which has the code D2 and points to its controlling field.
When a controlling field is found, the system will:
Look for the first field specified in the output specification clause that matches each FMC (field-mark
count) of its dependent fields and has D2 code in field 8 of the data definition item specifying the
controlling field.
Position the found fields, in the order found, to the immediate right of the controlling field for display.
Display an asterisk (*) under the column heading of each found field.
Dependent fields are output immediately to the right of their controlling field, regardless of the order in which
you specify them.
An independent field found between the controlling and dependent fields will be logically moved to the right of
the controlling and dependent fields.
Dependent fields will be ignored unless you specify the controlling field.
Example 1
SORT SALES P.CODE S.CODE = ABC
Selects all the records in the SALES file and outputs the P.CODE data. The S.CODE data will only be included
if it matches ABC - any other value will be shown as blank.
Example 2
SORT SALES BY P.CODE BREAK-ON P.CODE TOTAL VALUE
Selects all the records in the SALES file in P.CODE order. Outputs a line for each record until the P.CODE
changes. At this point a control break is triggered and the running total of VALUE will be output. At the end of
the report, a cumulative total for VALUE will be displayed.

Format Specification Clause

The format specification clause specifies the overall format of the report. You can include headings, footings,
page breaks, value breaks, and total lines.
Syntax
{HDR-SUPP} {COL-HDR-SUPP} {ID-SUPP} {DET-SUPP} {DBL-SPC} {HEADING {{text}{hfoption{hf-option}...}...}
{FOOTING {{text}{hf-option{hf-option}...}...}
{GRAND-TOTAL {text}{gt-option{gt-option}...}{text}}
{NOPAGE} {LPTR}
Syntax Elements
HDR-SUPP suppresses the default heading line at the top of the report and the summary line at the bottom of
the report. SUPP is a synonym for HDR-SUPP. You could use the H option at the end of the sentence instead
of this modifier.

Programmers Reference Manual

4-13

jQL

COL-HDR-SUPP suppresses column headings, the default page heading line (page number, time, and date),
and the summary line (n records listed) at the end of the report. You could use the C option at the end of the
sentence instead of this modifier.
ID-SUPP suppresses the record keys for the LIST and SORT commands. You could use the I option at the end
of the sentence instead of this modifier.
DET-SUPP suppresses detail output when used with the BREAK-ON and TOTAL connectives. You could use
the D option at the end of the sentence instead of this modifier.
DBL-SPC generates the report with double-spaced lines.
HEADING specifies the text and options to be output at the top of every page.
FOOTING specifies text and options to be output at the bottom of every page.
text comprises any printable characters except RETURN, LINE FEED, double quote, or system delimiters. Two
successive single quotes are displayed in the output as one single quotes.
hf-option is one or more HEADING and FOOTING options. Valid options are:
B

Functions only if a BREAK-ON modifier with a B option is also included in the sentence. The B
option can be used in either the header or the footer. When the B option is in the HEADING, the
value of the first BREAK-ON field on the page replaces the B in the header. When the B is in the
FOOTING, the last BREAK-ON value on the page replaces the B in the footer.

C{n}Centralises the heading or footing text. The text is centred according to the predefined number of
columns specified for the printer or terminal. To centre the text differently, specify the number of
columns n for the heading line on which the centre is to be based. For example, C80 positions the
text centred at character position 40. You should normally allow the centring to be determined by
the printer or terminal set-up.
D

Inserts the current date in the format: dd mmm yyyy.

Inserts the file name.

Inserts the current record key. The last record key listed on the page is inserted in the footing; the
first record key on the page is inserted in the heading.

Specifies that a new line is to start where the L appears.

Specifies that automatic paging is to be suppressed.

Inserts the current page number, left-justified, expanding to the right as the number increases.

PP Inserts the current page number right-justified in a field of four spaces.

T

Inserts the current system time and date in the format: hh:mm:ss dd mmm yyyy.

GRAND-TOTAL specifies text to replace the default asterisks in the cumulative total line at the end of the
report. CAPTION is a synonym for GRAND-TOTAL.
gt-option is one or more GRAND-TOTAL options. Valid options are:
L

Line. Suppresses the blank line preceding the GRAND-TOTAL line. Overrides the U option if both
are specified.

Page. Outputs the GRAND-TOTAL on a separate page.

Underline. Puts underlines on the line above the accumulated totals. Ignored if used with the `L
option.

NOPAGE suppresses automatic pagination. If output is to a terminal, the display will not pause at the end of
each page. You could use the N option at the end of the sentence instead of this modifier.
LPTR specifies that the report goes to the printer queue (Spooler) instead of displaying at the terminal. You
could use the P option at the end of the sentence instead of this modifier.

jQL

4-14

Programmers

Reference

Manual

Notes
Heading or footing options that specify a value should be entered in the order in which they are to appear.
Text spaces are not normally required between option codes. However, options that represent values such as
page or date, may be presented without spaces. For example: PD would be printed on the first page as:
111/11/95
In this case, enter the options with a space between them like this P D.
Example
SORT SALES BY S.CODE BREAK-ON S.CODE BL P.CODE TOTAL VALUE GRAND-TOTAL
Total HEADING Sales Code : B
DL FOOTING Page CPP LPTR
Sort the SALES file by S.CODE. Output the S.CODE, P.CODE and VALUE fields.
Control break on a change in S.CODE and suppress the LINE FEED before the break. Reserve the break value
for use in the heading (B).
Maintain a running total of the VALUE field and output it at each control break.
Put the word Total on the grand-total line.
Set up a heading for each page which comprises the words Sales Code : , the sales code (from the break), a
date and a LINE FEED. Set up a footing which contains the text Page and a page number, centred on the line.
Produce the report on the currently assigned printer.

USING Clause
The USING clause specifies a file that is to be treated as the dictionary for the data file. This file is the source of
data definition records.
Syntax
USING {DICT} filename{,data-section-name}
Syntax Elements
USING specifies that the named file is to be used as the dictionary for the data file.
DICT specifies that the dictionary of filename is to be used.
filename names a file. If the DICT modifier is not specified, the data section of the file will be used.
data-section-name specifies a secondary data section of the file with a name different from the dictionary. It
must follow filename, separated by a comma but no space.
Notes
As many USING clauses required can be specified in a jQL sentence.
One main advantage of the USING clause is that you can share a dictionary between several files where, for
example, there are common data definition records.
Example
:SORT SALES.94 USING DICT SALES
File SALES.94 will be accessed by means of the data definition records in the dictionary of file SALES (DICT
SALES).

Command Options
Command options are letters enclosed in parentheses which modify the action of the jQL command sentence.
The options described here are common to most commands. Where options are command-specific, they are
described with the command.

Programmers Reference Manual

4-15

jQL

Options for commands should not be confused with options for modifiers and connectives such as HEADING
and BREAK-ON.
Options can be separated by commas or spaces. When the options are at the end of the sentence (as is
recommended) the closing parenthesis can be omitted.
Any option which is not used by a particular command will be ignored.
Options
B

Suppress initial LINEFEED prior to output.

Suppresses column headings, page and date line at the start and summary line at the end of a report.
Equivalent to the COL-HDR-SUPP modifier.

Suppress detail output. Equivalent to the DET-SUPP modifier

Suppress page and date line at the start and summary line at the end of the report. Equivalent to the HDRSUPP modifier.

Suppress record keys. Equivalent to the ID-SUPP modifier.

Suppress automatic paging. Equivalent to the NOPAGE modifier.

Output report to the printer. Equivalent to the LPTR modifier.

Suppress summary line at the end of the report.

Example
:LIST SALES (HIP
List the SALES file (using the default data definition records) but suppress the output of a header and the record
keys. Send the output to the assigned printer.

Macros
Macros contain predefined or often-used elements of a jQL sentence. They are held on the system like Data
Definition records and are specified in the command sentence in a similar way.
When a command containing one or more macros is submitted for execution, the macro references are expanded
and included in the sentence before it is executed.
Macros can be substituted for any element of the command sentence except the command itself and the filename.
Macro definition records are searched for in the same way as Data Definition records. You should not use a jQL
keyword as the name (key) of a macro, but you can specify keys of 1, 2, 3 etc. that will be treated like the default
Data Definitions records.
The first field of a macro definition must contain the letter M. The remaining fields are either command elements
or comment lines (indicated by a leading asterisk * and a space).
Macros can be nested - a macro can refer to another macro - but the resulting command sentence must still
follow the same rules as a normal jQL sentence. When nesting macros, beware of infinite loops where, for
example, macro A calls macro B which calls macro A which calls macro B...
Example
SORT SALES BY S.CODE STD.HEADING
In this example, STD.HEADING is a macro which contains a standard heading clause:
STD.HEADING
001 M
002 * Standard heading for Sales reports
003 HEADING SALES - Company PrivateLLPage PL
004 LPTR
When the sentence is expanded, it will look like this:
jQL

4-16

Programmers

Reference

Manual

SORT SALES BY S.CODE HEADING SALES - Company PrivateLLPage PL LPTR

Programmers Reference Manual

4-17

jQL

jQL Commands
This section provides detailed descriptions of all jQL commands, in alphabetical order.
Most of the components that make up each jQL sentence have already been described in earlier sections of this
chapter. Note that not all jQL commands share a standard syntax.
The use of data definition records and data conversion techniques (for dates, times or file cross-referencing, etc.)
is discussed in later sections.

BSELECT Command
Retrieves selected records and generates a list composed of data fields from those records as specified by any
explicit or default output specifications. Each subvalue within a field becomes a separate entry within the list.
Syntax
BSELECT file-specifier {record-list} {selection-criteria} {sort-criteria} {USING file-specifier}{outputspecification} {(options}
Notes
When the command terminates, the total number of entries in the generated list is displayed and the list is made
available as if it had been generated by a SELECT, GET-LIST or other list-providing command.
If you do not specify a sort-criteria clause, the record list will be unsorted.
If you do not specify an output-specification, the default data definitions 1, 2 etc. will be used.
Examples
BSELECT SALES WITH S.CODE = ABC] P.CODE
Creates a list containing all P.CODE values from all the records in the SALES file which have an S.CODE that
starts with ABC.

COUNT Command
Reports the total number of records found in a file that match the selection criteria specified.
Syntax
COUNT file-specifier {record-list} {selection-criteria} {USING file-specifier} {(options}
Syntax Elements
options can be one or more of the following:
B

Suppress initial line-feed.

C{n} Display running counters of the number of records selected and records processed. Unless
modified by n, the counter increments after every 500 records processed or the total number of
records if less than 500.
The n specifies a number other than 500 by which to increment. For example, (C25) increments
the counter after every 25 records processed.
P

Send the report to the printer.

Examples
:COUNT SALES WITH VALUE > 1000
91 Records counted
Count the number of records in the SALES file which have a value greater than 1000.

jQL

4-18

Programmers

Reference

Manual

:COUNT SALES WITH VALUE > 1000 (C50

91 Records selected 240 Records processed
91 Records counted
Count the number of records in the SALES file which have a VALUE greater than 1000, and display a running
total of selected and processed records after each group of 50 records are processed.

EDELETE Command
Deletes selected records from a file according to record list or selection criteria clauses.
Syntax
EDELETE file-specifier [record-list | selection-criteria]
Notes
EDELETE requires an implicit or explicit record list, or selection criteria. An implicit list can be provided by
preceding the command with a SELECT, GET-LIST or other list-providing command.
EDELETE will immediately delete the specified records.
To clear all the records in a file, use the CLEAR-FILE command.
Examples
:EDELETE SALES ABC DEF
2 Records deleted
Delete the records ABC and DEF based on the explicit list of records.
:EDELETE SALES IF P.CODE = GHI]
n Records deleted
Delete all records in the SALES file in which the P.CODE field starts with GHI.
:SELECT SALES WITH S.CODE = ABC
n Records selected
>EDELETE SALES
n Records deleted
Selects all records in the SALES file in which the S.CODE field contains ABC, and deletes them.

ESEARCH Command
Generates an implicit list of records in a file if they contain (or do not contain) one or more occurrences of
specified character strings..
Syntax
ESEARCH file-specifier {record-list} {selection-criteria} {sort-criteria}
{USING file-specifier} {(options}
Syntax Elements
options can be one or more of the following:
A

ANDs prompted strings together. Records must contain all specified strings.

Displays the keys of selected records.

Saves the field numbers in which the specified strings were found. The resulting list contains the
record keys followed by multivalued line numbers. Ignores the A and N options if either or both are
specified.

Selects only those records that do not contain the specified string(s).

Suppresses the list but displays the record keys that would have been selected.

Programmers Reference Manual

4-19

jQL

Prompt
You will be prompted to supply one or more search strings:
STRING:
Enter the required character string and press RETURN. This prompt is repeated until only RETURN is pressed.
There is no limit on the number of characters that be entered.
Do not enter double quotes unless they are part of the string to search.
Notes
When the command terminates (unless the `S option is used), the total number of entries in the generated list is
displayed and the list is made available as if it had been generated by a SELECT, GET-LIST or other listproviding command.
If you do not specify a sort criteria clause, the record list will be unsorted.
Example
:ESEARCH SALES (I
STRING: ABC
STRING: DEF
KEY1
KEY2
2 Records selected
>
Generates a list of all records in the SALES file which contain the strings ABC or DEF.

LIST Command
Generates a formatted report of records and fields from a specified file.
Syntax
LIST file-specifier {record-list} {selection-criteria} {sort-criteria}
{USING file-specifier} {output-specification} {format-specification} {(options}
Notes
If an output specification clause is not provided, the system will search for default data definition records (named
1, 2 and so on) in the file dictionary and then in the file specified in the JEDIFILENAME_MD environment
variable. If default data definition records cannot be found, the only the record keys will be listed.
The records will not be sorted unless you specify a sort criteria clause.
Example 1
:LIST SALES
List all the records in the SALES file and use the default data definition records (if found) to format the output.
Example 2
:LIST SALES ABC DEF GHI
List the records from the SALES file with key values of ABC, DEF or GHI. Use the default data definition
records (if found) to format the output.
Example 3
:GET-LIST SALES.Q4
>LIST SALES GT DEF

jQL

4-20

Programmers

Reference

Manual

Get the previously saved list called SALES.Q4 and, using the list, report on the records in the SALES file which
have a key greater than DEF. Use the default data definition records (if found) to format the output.
Example 4
:LIST SALES WITH S.CODE = ABC] OR [DEF
List the records in the SALES file in which the S.CODE field contains values which start with ABC or end with
DEF. Use the default data definition records (if found) to format the output.
Example 5
:LIST SALES WITH NO S.CODE = ABC] OR [DEF (P
List the records in the SALES file in which the S.CODE field does not contain values which start with ABC or
end with DEF. Output the report to the printer. Use the default data definition records (if found) to format the
output.
Example 6
:LIST SALES BY S.CODE BREAK-ON S.CODE BL P.CODE TOTAL VALUE GRANDTOTAL Total HEADING Sales Code : B
DL FOOTING Page CPP LPTR
Sort the SALES file by S.CODE. Output the S.CODE, P.CODE and VALUE fields.
Control break on a change in S.CODE and suppress the LINE FEED before the break. Reserve the break value
for use in the heading (B).
Maintain a running total of the VALUE field and output it at each control break.
Put the word Total on the grand-total line.
Set up a heading for each page which comprises the words Sales Code : , the sales code (from the break), a
date and a LINE FEED. Set up a footing which contains the text Page and a page number, centred on the line.
Produce the report on the currently assigned printer.

LIST-LABEL Command
Outputs data in a format suitable for producing labels.
Syntax
LIST-LABEL file-specifier {record-list} {selection-criteria} {sort-criteria}
{USING file-specifier}{output-specification} {format-specification} {(options}
Prompts
You will be prompted to supply formatting criteria as follows:
COL,ROW,SKIP,INDENT,SIZE,SPACE{,C}:
COL

Number of columns required to list the data across the page.

ROW

Number of lines for each record. Each element of the output specification will be output on a separate
line, if more elements exist in the output specification than there are rows specified, the extra elements
will be ignored. If more rows are specified than elements, the output specification for these rows will
be blank.

SKIP

Number of blank lines between each record.

INDENT Number of spaces for left margin.

SIZE

Number of spaces required for the data under each column.

SPACE

Number of horizontal spaces to skip between columns.

Optional. Suppresses null or missing data. If absent, null or missing values are output as blanks. If
present the C must be upper case and not in quotes.

Programmers Reference Manual

4-21

jQL

Notes
The total number of columns specified must not exceed the page width, based on the calculation:
COLs * (SIZE + SPACE) + INDENT <= page width
ROW must be a minimum of one for each field, plus one for the record key (if not suppressed). If record keys
are not suppressed, the first row of each label will contain the record key.
If INDENT is not zero, you will be prompted to supply a series of HEADERs that will appear in the left margin
for each field. If a heading is not required for a particular line, press RETURN.
Multivalued fields appear as separate labels.
If COL-HDR-SUPP or HDR-SUPP, or the C or H options are specified, the page number, date, and time will not
be output and the report will be generated without page breaks.
The records will not be sorted unless you specify a sort criteria clause.
See also the SORT-LABEL command.
Example
LIST-LABEL SALES NAME ADDRESS STREET TOWN POSTCODE ID-SUPP (C
COL,ROW,SKIP,INDENT,SIZE,SPACE(,C): 2,5,2,0,25,4,C
NAME1
ADDRESS1
STREET1
TOWN1
POSTCODE1

NAME2
ADDRESS2
STREET2
TOWN2
POSTCODE2

NAME3
ADDRESS3
STREET3
TOWN3
POSTCODE3
.
.
.

NAME4
ADDRESS4
STREET4
TOWN4
POSTCODE4

LISTDICT Command
Generates a report of all data definition records in the first MD file found, or the specified file.
Syntax
LISTDICT {file-specifier}
Syntax Elements
file-specifier specifies a dictionary file other than a file named MD in the JEDIFILEPATH.
Notes
If you do not specify a file-name, LISTDICT will work with the first file named MD which is found in your
JEDIFILEPATH.

REFORMAT Command
REFORMAT is similar to the LIST command in that it generates a formatted list of fields, but its output is
directed to another file or the magnetic tape rather than to the terminal or printer.

jQL

4-22

Programmers

Reference

Manual

Syntax
REFORMAT file-specifier {record-list} {selection-criteria}
{USING file-specifier} {output-specification} {format-specification} {(options}
Prompt
You will be prompted to supply the destination file:
FILE:
Enter a file name, or the word TAPE for output to a magnetic tape.
Notes
Records that already exist in the destination file will be overwritten.
When you reformat one file into another, each record selected becomes a record in the new file. The first value
specified in the output specification clause is used as the key for the new records. The remaining values in the
output specification clause become fields in the new records.
When you reformat a file to tape, the values specified in the output specification clause are concatenated
together to form one tape record for each record that is selected. The record output is either truncated or padded
at the end with nulls (X00) to obtain a record the same length as specified when the tape was assigned by the TATT command.
Unless you specify HDR-SUPP or COL-HDR-SUPP, or a C or H option., a tape label containing the file name,
tape record length (in hexadecimal), the time, and date will be written to the tape first. If a HEADING clause is
specified, this will form the data for the tape label.
Record keys are displayed as the records are written to tape unless the ID-SUPP modifier or the I option is
specified.
Two EOF marks terminate the file on tape.
See also the SREFORMAT command.
Example
:REFORMAT SALES C.CODE NAME ADDRESS
FILE: ADDRESS
Creates new records in the ADDRESS file, keyed on C.CODE from the SALES file. Each record contains two
fields, one with the values from the NAME field and one with the values from the ADDRESS field.

SELECT Command
Generates an implicit list of record keys or specified fields based on the selection criteria specified.
Syntax
SELECT file-specifier {record-list} {selection-criteria} {sort-criteria} {output-criteria} {USING filespecifier} {(options}
Syntax Elements
options are:
C{n} Display running counters of the number of records selected and records processed. Unless
modified by n, the counter increments after every 500 records processed or the total number of
records if less than 500.
n specifies a number other than 500 by which to increment. For example, C25 increments the
counter after every 25 records processed.

Programmers Reference Manual

4-23

jQL

Notes
The records will not be sorted unless you specify a sort criteria clause.
See also the SSELECT command.
If you specify an output-criteria clause, the generated list will comprise the data (field) values defined by the
clause, rather than the selected record keys.
If you are in jSHELL when the command terminates, the total number of entries in the generated list is displayed
and the list is made available to the next command - as indicated by the > prompt.
If you use the BY-EXP or BY-EXP-DSND connectives on a multivalued field, the list will have the format:
record-key]multivalue#
where multivalue# is the position of the multivalue within the field specified by BY-EXP or BY-EXP-DSND.
multivalue# can be accessed by a READNEXT Var,n statement in a jBC program.
Example 1
:SELECT SALES WITH S.CODE = ABC]
23 Records selected
>LIST SALES WITH VALUE > 1000
Select all the records in SALES file with an S.CODE value that starts with ABC. Then, using the list, report on
the records in the SALES file which have a VALUE field greater than 1000.
Example 2
:SELECT SALES WITH S.CODE = ABC]
23 Records selected
>SAVE-LIST SALES.ABC
Select all the records in SALES file with an S.CODE value that starts with ABC. Then save the list as
SALES.ABC.

SORT Command
Generates a sorted and formatted report of records and fields from a specified file.
Syntax
SORT file-specifier {record-list} {selection-criteria} {sort-criteria}
{USING file-specifier} {output-specification} {format-specification} {(options}
Notes
Unless a different sort order is specified in the sort criteria, the records will be presented in an ascending order
based on the record key.
The data definition record (or the file definition record in the case of keys) determines whether a left or right sort
will be applied to the data.
If the field is left-justified, the data will be compared on a character-by-character basis from left to right, using
ASCII values. For example:
01
100
21
A
ABC
BA

jQL

4-24

Programmers

Reference

Manual

If the field is right-justified and the data is numeric, a numeric comparison will be performed and the values
ordered by magnitude.
If the field is right-justified and the data is alphanumeric, the data will be collated into an alphanumeric
sequence. For example:
A
01
123
ABCD
If a descending sequence is required, the BY-DSND modifier should be used in the sort criteria. A descending
sequence of record keys can be obtained by using the BY-DSND modifier with a data definition record that
points to field 0 ( the key).
See Sort Criteria Clause earlier for a full explanation of the sorting process.
Example 1
:SORT SALES
Sort all the records in the SALES file into key order and use the default data definition records (if found) to
format the output.
Example 2
:SORT SALES WITH S.CODE = ABC DEF GHI
Select the records in the SALES file in which the S.CODE field contains the values ABC, DEF or GHI. Sort the
records into key order.
Example 3
:GET-LIST SALES.Q4
>SORT SALES GT DEF BY S.CODE
Get the implicit list called SALES.Q4 and, using the list, report on the records in the SALES file which have a
key greater than DEF. Sort the report by S.CODE.
Example 4
:SORT SALES WITH S.CODE = ABC] OR [DEF BY-DSND S.KEY LPTR
Select the records in the SALES file in which the S.CODE field contains values which start with ABC or end
with DEF. Sort the report in descending order of S.KEY (a data definition record which points to field 0 - the
key) and output the report to the printer
Example 5
:SORT SALES BY S.CODE BREAK-ON S.CODE BL P.CODE TOTAL VALUE GRANDTOTAL Total HEADING Sales Code : B
DL FOOTING Page CPP LPTR
Sort the SALES file by S.CODE. Output the S.CODE, P.CODE and VALUE fields.
Control break on a change in S.CODE and suppress the LINE FEED before the break. Reserve the break value
for use in the heading (B). Maintain a running total of the VALUE field and output it at each control break. Put
the word Total on the grand-total line.
Set up a heading for each page which comprises the words Sales Code : , the sales code (from the break), a
date and a LINE FEED. Set up a footing which contains the text Page and a page number, centred on the line.
Produce the report on the currently assigned printer.

SORT-LABEL Command
Outputs data in a format suitable for producing labels.

Programmers Reference Manual

4-25

jQL

Syntax
SORT-LABEL file-specifier {record-list} {selection-criteria} {sort-criteria}
{USING file-specifier}{output-specification} {format-specification} {(options}
Prompts
You will be prompted to supply formatting criteria as follows:
COL,ROW,SKIP,INDENT,SIZE,SPACE(,C):
COL
ROW
SKIP
INDENT
SIZE
SPACE
C

Number of columns required to list the data across the page.

Number of lines for each record.
Number of blank lines between each record.
Number of spaces for left margin.
Number of spaces required for the data under each column.
Number of horizontal spaces to skip between columns.
Optional. Suppresses null or missing data. If absent, null or missing values are output as blanks.

Notes
The total number of columns specified must not exceed the page width, based on the calculation:
COLs * (SIZE + SPACE) + INDENT <= page width
ROW must be a minimum of one for each field, plus one for the record key (if not suppressed). If record keys
are not suppressed, the first row of each label will contain the record key. The records will be sorted in key order
unless you specify a sort criteria clause.
If INDENT is not zero, you will be prompted to supply a series of HEADERs that will appear in the left margin
for each field. If a heading is not required for a particular line, press RETURN.
Multivalued fields appear on separate lines.
If COL-HDR-SUPP or HDR-SUPP, or the C or H options are specified, the page number, date, and time will not
be output and the report will be generated without page breaks.
See also the LIST-LABEL command.

SREFORMAT Command
SREFORMAT is similar to the SORT command in that it generates a formatted list of fields, but its output is
directed to another file or the magnetic tape rather than to the terminal or printer.
Syntax
SREFORMAT file-specifier {record-list} {selection-criteria}
{USING file-specifier} {output-specification} {format-specification} {(options}
Prompt
You will be prompted to supply the destination file:
FILE:
Enter a file name, or the word TAPE for output to a magnetic tape.
Notes
Records that already exist in the destination file will be overwritten.
When you reformat one file into another, each record selected becomes a record in the new file. The first value
specified in the output specification clause is used as the key for the new records. The remaining values in the
output specification clause become fields in the new records.

jQL

4-26

Programmers

Reference

Manual

When you reformat a file to tape, the values specified in the output specification clause are concatenated
together to form one tape record for each record that is selected. The record output is either truncated or padded
at the end with nulls (X00) to obtain a record the same length as specified when the tape was assigned by the TATT command.
Unless you specify HDR-SUPP or COL-HDR-SUPP, or a C or H option., a tape label containing the file name,
tape record length (in hexadecimal), the time, and date will be written to the tape first. If a HEADING clause is
specified, this will form the data for the tape label.
Record keys are displayed as the records are written to tape unless the ID-SUPP modifier or the I option is
specified.
Two EOF marks terminate the file on tape.
See the REFORMAT command for examples.

SSELECT Command
SSELECT generates an implicit list of record keys or specified fields, based on the selection criteria specified.
Syntax
SSELECT file-specifier {record-list} {selection-criteria} {sort-criteria} {output-criteria} {USING filespecifier} {(options}
Syntax Elements
options are:
C{n} Display running counters of the number of records selected and records processed. Unless
modified by n, the counter increments after every 500 records processed or the total number of
records if less than 500.
n specifies a number other than 500 by which to increment. For example, C25 increments the
counter after every 25 records processed.
Notes
The records will be sorted in key order unless you specify a sort criteria clause.
See also the SELECT command.
If you specify an output-criteria clause, the generated list will comprise the data (field) values defined by the
clause, rather than the selected record keys.
When the command terminates, the total number of entries in the generated list is displayed and the list is made
available to the next command. This is indicated by the > prompt if you are in jSHELL.
If you use the BY-EXP or BY-EXP-DSND connectives on a multivalued field, the list will have the format:
record-key]multivalue#
where multivalue# is the position of the multivalue within the field specified by BY-EXP or BY-EXP-DSND.
multivalue# can be accessed by a READNEXT Var,n statement in a jBC program.
Example 1
:SSELECT SALES WITH S.CODE = ABC]
23 Records selected
>LIST SALES WITH VALUE > 1000
Select all the records in SALES file with an S.CODE value that starts with ABC. Sort the list into key order.
Then, using the list, report on the records in the SALES file which have a VALUE field greater than 1000.

Programmers Reference Manual

4-27

jQL

Example 2
:SSELECT SALES WITH S.CODE = ABC] BY P.CODE
23 Records selected
>SAVE-LIST SALES.ABC
Select all the records in SALES file with an S.CODE value that starts with ABC. Sort the list into P.CODE order
and then save the list as SALES.ABC.

jQL

4-28

Programmers

Reference

Manual

File Definition Records

This section starts with a review of file definition records and discusses how the content of these records can
affect the output from jQL commands - particularly with reference to sublists.
File definition records contain information that is used when formatting reports. For example, should the key
field of a file be left or right justified, and how wide a column should it occupy. You can also define sublist
codes to tell the system that a particular field is multivalued.

Record Structure
The fields of a file definition record that affect jQL reports are:
Field 7

Conversion code for key, if required. For date, time, etc.

Field 8

V code to notify a multivalued (sublist) field, if required. See Sublists - V Code following.

Field 9

Justification for key. Can be one of the following:

L Left justified
R Right justified
T Text
U Unlimited
See 'Data Definition Records' later.

Field 10

Column width for key. Default is 14 characters.

Sublists - V Code
File records which contain sublists can be accessed with the COUNT and LIST commands and the WITHIN
modifier. For the commands and the modifier to function properly, you must include the V processing code in
field 8 of the file definition record. See the File Specifiers topic in the jQL Command Sentence Construction
topic for more details.
Syntax
V;;field-no
Syntax Elements
field-no is the number of the field which contains the sublist.
Example
Consider the STOCK file used by a camera factory where each data record can represent either an assembly or a
component part.
Take as an example the record set that defines a simple camera assembly. The data records contain the following
data:
Key
001
002
003

A1
CAMERA ASSY
A21]A22]A23
10

Key
001
002
003

A21
LENS ASSY
A210]A211
15

Key
001
002
003

A22
BODY

Key
001
002
003

A23
SHUTTER ASSY
A230]A231
11

Key
001
002
003

A210
OPTICS

Key
001
002
003

A211
BARREL

10

19

Programmers Reference Manual

21

4-29

jQL

Key
001
002
003

A230
IRIS MECH

Key
001
002
003

13

A231
IRIS HOUSING
14

The key is the part number, field 1 contains the description, field 2 is a multivalued list of components that go to
make up the part, and field 3 is the current stock level.
A1
Camera Assy

A21
Lens Assy
A210
Optics

A22
Body
A211
Barrel

A23
Shutter Assy
A230
Iris Mech

A231
Film Mech

Record A1 represents assembled cameras. It points to the sub-assemblies (A21, A22 and A23) that are used to
make each camera. The sub-assemblies in turn point to their component parts; A21 points to A210 and A211,
A22 does not have any components, and A23 points to A230.
Having established the logical data relationships, we now need to ensure that the system understands that field 2
is a multivalued sublist. We do this by updating field 8 in the file definition record to read V;;2, like this:
STOCK
001 D
002
003
004
005
006
007
008 V;;2
009 L
010 10
Now all we need to do is to create three data definition records (see later) in the dictionary of STOCK - one for
each field. We will name them DESC, COMPONENTS, and QTY.
The final step is to issue a COUNT or LIST command which uses the WITHIN modifier:
:LIST WITHIN STOCK 'A1' DESC COMPONENTS QTY
PAGE 1
LEVEL STOCK

Description....

A1

CAMERA ASSY

A21

LENS ASSY

3
3
2
2

A210
A211
A22
A23

OPTICS
BARREL
BODY
SHUTTER ASSY

3
3

A230
A231

IRIS MECH
FILM MECH

Time Date
Components
A21
A22
A23
A210
A211

A230
A231

Qty
10
15
19
21
10
11
13
14

8 RECORDS LISTED

jQL

4-30

Programmers

Reference

Manual

Data Definition Records

Data definition records (sometimes known as field definition records) define the characteristics of each field in a
data file. They specify the output format and the type of processing required to generate each column of a jQL
report.
Data definition records can be used to:
Specify default output.
Associate field names with field numbers (column headings).
Perform output formatting.
Calculate new values based on the source data
Perform processing via conversion codes.
Although they are normally used to define a single physical field in a file, the data definition records can also be
used for more complex operations. For example:
to join or derive data from other fields or files.
to verify the presence (or absence) of records in other files.
to format their output in the most easily understood manner (to convert numeric 0 and 1 flags to Yes
or No, for example, or to output text like Overdue if one date field is older than another).
to generate statistical data like record sizes or counters.
The data definition records are usually located in the dictionary of the data file (but not always - see the USING
Clause and the Default Output Specification topics). You can set up any number of data definition records.
Often, there are several definitions for each field, each one used by a different set of reports which have different
output requirements.
You associate the data definition record with a particular field in the data file by specifying the target fields
FMC (field-mark count) in field 2 of the data definition record. The FMC refers to (points to) the field number
(also known as the line number) of the data within the records of the data file.

Record Layout
All data definition records are defined in the same way:
Field Description
1

D/CODE. Defines the record as a data definition record. Must be one of the following codes:
A marks a normal data definition record.
S obsolete but still supported. Was like the A type, but suppressed default column headings when
field 3 was blank. Replaced by the A type with a backslash in field 3 to defeat heading.
X forces the record to be ignored if selected as part of a default set of data definitions. Can only
be used when explicitly named. See Default Output Specification later.

FMC (field-mark count). A field number or special FMC (see Special Field-mark Counts later, for
more details). A field number refers to the corresponding field (or line) in a record.
The special FMC codes are:
0
Refers to the record key - field number 0 (zero).
9998 Ordinal number of record at output (used for numbering or counting).
9999 Size of the record in bytes (excluding the key).

Column heading. Can be heading text, null, or a backslash followed by text. If more characters are
entered here than the width in field 10 allows for, the width will be increased to accommodate the
heading text (this field wins). Column headings are not displayed if the statement uses the COL-HDRSUPP output modifier or the 'C' option.
Heading text is used as the column heading. If the text is less than the column width, it will be padded
with dots. Use spaces to produce a blank heading. Value marks, <CTRL ]>, can be used as
NEWLINE characters to place the following text on a new line.
If this field is left null, the key of the data definition record will be used as the column heading.

Programmers Reference Manual

4-31

jQL

Text following a backslash \ character will be used as the column heading. If nothing follows the
backslash, the column heading will be null.
4-6

Not used.

Input/Output conversion codes used for processing the data after sort and selection but before output.
See Conversion Codes later.
Multiple conversion codes, separated by a value marks, <CTRL ]>, will be processed from left to
right.

Pre-process conversion codes used for processing the data before sort and selection and before field 7
codes. See Conversion Codes later.
Multiple conversion codes, separated by a value marks, <CTRL ]>, will be processed from left to
right.

Format. Specifies the layout of the data within the column. Can be any of the following:
L Left justified. If the data exceeds the column width specified in field 10, the data is broken at
column width without respect to blank spaces.
R Right justify. If the data exceeds the column width specified in field 10, the data will be
truncated.
T Text. Word wrap - like L (left justified) but, where possible, lines will be broken at the blank
space between words.
U Unlimited. Data is output on one line ignoring column boundaries.

10

Width. Numeric value specifying the column width. If the number of characters in field 3 (the
heading) is greater than the number entered here, the number of characters in field 3 will be used.

Special Field-mark Counts

Three special FMCs (field-mark counts) are recognised: 0, 9998 and 9999.
FMC 0 - Record Key
Setting field 2 of the data definition record to 0 (zero), causes the system to work with the record key.
In this way, you could set up a data definition record which would allow a the record keys to be output in a
column other than the first, and to use any column heading.
Typically, you would also use the ID-SUPP modifier or the I command option to suppress output of the record
key in the first column.
FMC 9998 - Record Count/NI Operand
Setting field 2 of the data definition record to 9998, causes the system to return a record (or line) count equal to
the number of records output so far in the report.
You could also use function operators within an A or F conversion code in field 7 or 8 of the data definition
record to achieve the same result. Function code operand NI yields the same value as an FMC of 9998.
FMC 9999 - Record Size/NL Operand
Setting field 2 of the data definition record to 9999, causes the system to return the record size in bytes. The size
does not include the key but does include all field marks within the record.
You could also use function operators within an A or F conversion code in field 7 or 8 of the data definition
record to achieve the same result. Function code operand NL yields the same value as an FMC of 9999.

Default Output Specification

Default output specifications work in two ways, depending on whether the default definitions are explicit or
implicit.
jQL

4-32

Programmers

Reference

Manual

Explicit Defaults
If you specify a data definition record to be used for output, the system will search for it first in the implied
dictionary (or the dictionary specified in a USING clause), and then in the files specified in the JBCDEFDICTS
environment variable. If the record is still not located, the file defined by the JEDIFILENAME_MD
environment variable will be searched.
Implicit Defaults
If you do not explicitly specify any data definition records to be used for output, the system will search for a
predefined series of records, first in the implied dictionary (or the dictionary specified in a USING clause), and
then in the files specified in the JBCDEFDICTS environment variable. If the record is still not located, the file
defined by the JEDIFILENAME_MD environment variable will be searched.
You can therefore set up a series of data definition records that the system will use if a jQL command sentence
does not include any explicit output fields.
These default records must be named in a numeric sequence starting at 1 (1, 2, 3, and so on). The fields that
these records define will be output in the same sequence as the keys but they do not need to follow the same
sequence as the fields in the file.
When a jQL command sentence with no explicit output fields is issued, the system first looks in the dictionary
for a data definition record named 1, then for a record named 2, then 3, and so on until it fails to find a record
with the next number. If the record has a D/CODE of A, it will be used. If the record has a D/CODE of X, it will
be ignored, but it will not break the sequence.
A record with a D/CODE of X will only be skipped if it was found as the result of a search for defaults. Under
normal circumstances it can be used in the same way as any other data definition record.
This means that when you first set up a series of default data definition records, you should put an A in the
D/CODE field of each. If you subsequently need to remove one from the sequence, you can simply change the
D/CODE field to an X. This way you do not break the sequence or have to copy the remaining default records
to new names in order to fill the gap.
A data definition record with a number for a key can still be used in the same way as any other data definition
record.

Predefined Data Definition Records

Some predefined data definition records are automatically available so that, if appropriate data definition records
are not included in a file's dictionary, a report can still be generated. These records do not physically exist on the
system but are recognised when used in a jQL command sentence.
The predefined data definition records are named *A0 to *Annn. The numeric portion of the key corresponds to
the position of the field they report on and the column heading will be the same as the DDR name.

Programmers Reference Manual

4-33

jQL

Conversion Codes
This section deals with the conversion codes that you can include in fields 7 and 8 of data definition records.
Conversion codes allow you to specify a wide range of data manipulation facilities that can be applied to the data
as it is moved between the three stages of processing. Each stage implies a potentially modified data format:
stored format
intermediate format
output format
Field 8 holds pre-process conversion codes that define any processing to be performed before record selection or
sorting, as the data is moved between the stored and intermediate stages.
Field 7 holds output conversion codes that define any processing to be performed immediately before output (to
insert currency symbols, for example), as the data is moved between the intermediate and output stages.
The following table shows how and when the conversion codes are applied:
Field Specified in:

Pre-process Conversion
Field 8

Input/Output Conversion
Field 7

Selection clause

Inverse conversion
applied, if suitable, as
input conversion during
selection

Test field for Selection

Before test

Sort clause

Before sorting

Field to be Totalled

Before adding to running

total

BREAK-ON clause

Before testing for break

Print limiting clause

Before test

Output specification

Before output conversion

Output conversion
applied after pre-process
conversion but before
output

Field output on a Break

or Total line

Already applied during

processing

Output conversion
applied before output

Field 8 Codes (Pre-process)

Codes in field 8, sometimes known as correlatives or pre-processor codes, transform data from its stored to its
intermediate format. Data in intermediate format is then used for processing such as sorting or selecting.
If field 8 is null, the data is moved directly from its stored format to its intermediate format.

Field 7 Codes (Output)

Codes in field 7, sometimes known as conversions or input/output processor codes, transform data from its
intermediate format to its output format. These codes are often used to convert dates from internal to external
format or to say, add a currency sign to a numeric value.
If field 7 is null, the data is moved directly from its intermediate format to its output format.

jQL

4-34

Programmers

Reference

Manual

Field 7 Codes (Input)

If you specify a selection clause that uses explicit values in the command sentence, field 7 codes are also
inverted and applied to your input values, before they are used for comparison with data values. This is known
as input processing because the values you input are converted to internal format, rather than the data values
being are converted to external format.
Take as an example, a data definition record with a date conversion in field 7. Under normal circumstances, the
conversion is simply applied at the output stage to change the date from internal to external format.
If you now want to select records which contain a particular date in this field, you would include a selection
clause in the command sentence like this:
WITH A.DATE = 10/10/95
In this case, the system will take your explicit value and apply the inverse of the field 7 code. In other words, it
will convert 10/10/95 to its internal format. Now the system can perform a valid comparison with the data on file
(which is also in internal format).
Using the conversion code in this way allows the system to make fast, easy comparisons by only changing a
single value. By contrast, if you specify the date conversion in field 8 instead of field 7, the system will have to
change each stored value into its intermediate format before making the comparison.
Some codes, for example D (date conversion) and the Mask conversion, are automatically invertable - the output
conversion code is the same as the input conversion code. The system simply performs the inverse of the output
conversion.
Some codes, such as T (translate), have different specifications for input and output conversions. You must set
up the translate data to accommodate both conversions.
Other codes such as, A (arithmetic), F (stack manipulation) and C (concatenate), are not invertable, but you can
still specify them in field 7. In this case they are ignored during the input conversion stage and are only applied
during the output conversion.
See the individual code descriptions for any further exclusions.

Processing Code Summary

Code

Description

A
AE
B
C
CALL
D
D1

Function - evaluate algebraic expressions

Function - evaluate extended algebraic expressions
Call jBC subroutine or C function to process value
Concatenate elements
Call jBC subroutine or C function to process value
Date - convert date
Define controlling field linked to one or more dependent fields (field
8 only).
Define dependent field (field 8 only).
Function - manipulate expressions using reverse Polish notation.
Function - manipulate expressions using standard reverse Polish
notation.
Function - manipulate extended expressions using standard reverse
Polish notation.
Group - select one or more contiguous elements from a field value.
Length - returns the length of a value, or the value if it is within
specified criteria.
Mask Decimal - convert and scale numbers.
Mask Character - extract and convert characters.
Mask Metric - display scaled value with K, M or G suffix.
Mask decimal, left justified - convert and scale decimals left justified.
Mask Packed - convert packed decimals.
Mask decimal, right justified - convert and scale decimals right
justified.

D2
F
FE
FS
G
L
M
MC
MK
ML
MP
MR

Programmers Reference Manual

4-35

jQL

MS
MT
MX
R
S
T
Tfile
U

Mask Sequence - Use alternate sort sequence, defined in ERRMSG.

Mask Time - convert time.
Mask heXadecimal - convert ASCII characters to their hexadecimal
equivalents.
Range - returns a value that falls within one or more specified ranges.
Substitute - substitute one value for another.
Text - extract a contiguous string of characters from a value.
Translate file - translate values using a second file.
User exit - execute special routine to process value.

Multiple Conversion Codes

You can specify multiple conversion codes in fields 7 or 8 by separating each code with a value mark, <CTRL
]>. Multiple codes are processed left-to-right, with each code acting on the result produced by the previous code.

Print Limiter Clause

If the output specification of your jQL command sentence includes a print limiter, any pre-process conversions
in field 8 will be applied before comparison with the limiter value. If they do not match, no further processing is
attempted and the output is discarded. If there is a match, the system will perform any output processing and
output the result.

Controlling and Dependent Fields

If your jQL command sentence refers to controlling (D1) and dependent (D2) fields in an output specification
clause, the fields may not be output in the order specified in the sentence. The controlling field is output first,
followed by the dependent fields in the sequence specified by the D1 code in the controlling field's definition
record.

Selections
Selection involves the comparison of file data in internal format against input data in intermediate format.
The processing steps are:
1. Obtain value to compare from selection clause
1. Apply inverted conversion code from field 7 to value to compare
1. Obtain file data in stored format
1. Apply conversion code in field 8 to file data
1. Compare the inverted value and the converted file data

Sorts
Sorts are performed on data in intermediate format.
The processing steps are:
1. Obtain file data in stored format
1. Apply conversion code in field 8 to file data
1. Append the converted data to sort key

TOTAL Connectives
When the TOTAL connective is used in a jQL command sentence, the system initialises a counter to accumulate
the values of the specified field (as defined by field 2 of the data definition record). The system organises
multiple counters in the same left to right sequence as it found the totalled fields in the sentence. This sequence
is important because you can specify more than one counter with the same FMC.
Only the fields qualified with the TOTAL connective are assigned counters.

jQL

4-36

Programmers

Reference

Manual

Detail Lines
When processing a field specified with the TOTAL connective, the system will apply field 8 (pre-process) codes
and then add the resulting intermediate value to the counter for that field. If the data is to be output on the detail
line, the system will then apply field 7 (output) codes.
Total Line
When the processor prepares a total for output, it first applies the field 7 (output) code. However, in this case,
the system handles format and function code definitions differently.
If a format code is used, the processor applies the code to the counter accumulated for the specified field, so that
what is displayed is derived from the total for that field.
If a function code (A, AE, F, FE, or FS) is encountered, the system resolves a field reference by using the FMC
associated with each total counter, not the field specified in the sentence.
Format codes used within functions follow the rules of the function.
Notes
Function codes can be used to calculate averages. For example, the ND (number of detail lines) operand could
be used to obtain the average of a sum.
If you want to suppress the output of detail values for a particular column in the report, for example if the total of
a column is only used by a function in another column, you can suppress the output of the column by putting a
backslash in field 3 or a zero in field 10 of the data definition record.

BREAK-ON Connectives
When a BREAK-ON field is used, the system will first apply the field 8 (pre-process) conversion code to move
the data into intermediate format.
The intermediate format is then used to check for any change in data values between one record and the next. In
other words, should the break be processed.
Having completed the check at the intermediate format stage, the system will then apply field 7 (output) codes to
produce the output format.
Processing
The processing steps are:
1. Obtain file data in stored format
1. Apply conversion code in field 8 (pre-process) to file data
1. Compare converted data for this record with that of the previous record for a change in value.
Remember result.
1. Apply conversion code in field 7 (output) to intermediate format data
1. If value has changed, perform control break. If not, output the data

Programmers Reference Manual

4-37

jQL

A Code - Algebraic Functions

A codes provide many powerful features. These include arithmetic, relational, logical, and concatenation
operators, the ability to reference fields by name or FMC, the capability to use other data definition records as
functions that return a value, and the ability to modify report data by using format codes.
The A code also allows you to handle the data recursively, or nest one A code expression inside another.

Syntax Summary
The A code function uses an algebraic format. There are two forms of the A code:
A

uses only the integer parts of stored numbers unless a scaling factor is included.

AE

handles extended numbers. Uses both integer and fractional parts of stored numbers.

Syntax
A{n}{;expression}
AE;expression
Syntax Elements
n is a number from 1 to 6 that specifies the required scaling factor.
expression comprises operands, operators, conditional statements, and special functions.
Notes
The A code replaces and enhances the functionality of the F code. You will find A codes much easier to work
with than F codes.
Valid A codes formats are:
A;expression

evaluates the expression.

An

converts to a scaled integer.

An;expression

converts to a scaled integer.

AE;expression

evaluates the expression.

A;expression Format
Performs the functions specified in expression on values stored without an embedded decimal point.
An Format: Embedded Decimals
The An format converts a value stored with an embedded decimal point to a scaled integer. The stored value's
explicit or implied decimal point is moved n digits to the right with zeros added if necessary. Only the integer
portion is returned.
Field 2 of the data definition record must contain the FMC of the field that contains the data to be processed.
An;expression Format
The An;expression format performs the functions specified in expression on values stored with an embedded
decimal point. The resulting value is then converted to a scaled integer.
AE;expression Format
The AE format uses both the integer and fractional parts of stored numbers. Scaling of output must be done with
format codes.

jQL

4-38

Programmers

Reference

Manual

Examples of Numeric Results

Data Record
Field 1
Field 2
4
012
-77
-22
0.12
22.09
-1.234
-12.34
-1.234
123.45

A;1 + 2
16
-99
22
-13
122

A Code
A3;1 + 2
16000
-99000
22210
-13574
122216

AE;1 + 2
16
-99
22.21
-13.574
122.216

Input Conversion
Input conversion is not allowed.
Format Codes
You can format the result of any A code operation by following the expression with a value mark, <CTRL ]>,
and then the required format code, like this:
An;expression]format
Format codes can also be included within the expression. See Format Codes for more information.

Summary of Operands
Operands that you can use in A code expressions include: FMCs (field numbers), field names, literals, operands
that return system parameters, and special functions.
You can format any operand by following it with one or more format codes enclosed in parentheses, and
separated by value marks, <CTRL ]>, like this:
operand(format-code{]format-code}...)
See Format Codes for more information.
Field Number (FMC) Operand
The field number operand returns the content of a specified field in the data record:
field-number{R{R}}
The first R specifies that any non-existent multivalues should use the previous non-null multivalue. When the
second R is specified, this means that any non-existent subvalues should use the previous non-null subvalue.
Field Name Operand
The field name operand returns the content of a specified field in the data record:
N(field-name){R{R}}
Literal Operand
The literal operand supplies a literal text string or numeric value:
literal
System Parameter Operands
Several A code operands return the value of system parameters. They are:
D
Returns the system date in internal format.
LPV Returns the previous value transformed by a format code.
NA Returns the number of fields in the record.
NB
ND

Returns the current break level counter. 1 is the lowest break level, 255 is the GRAND TOTAL line.
Returns the number of records (detail lines) since the last control break.

NI

Returns the record counter.

Programmers Reference Manual

4-39

jQL

NL

Returns the record length in bytes

NS
NU

Returns the subvalue counter

Returns the date of last update

NV
T

Returns the value counter

Returns the system time in internal format.

Returns the previous value transformed by a format code

Special Operands
Some operands allow you to use special functions. They are:
I(expression)
R(exp1, exp2)

Returns the integer part of expression.

Returns the remainder of exp1 divided by exp2.

S(expression)
Returns the sum of all values generated by expression.
string[start-char-no, len] Returns the substring starting at character start-char-no for length len.

Summary of Operators
Operators used in A code expressions include arithmetic, relational and logical operators, the concatenation
operator, and the IF statement.
Arithmetic Operators
Arithmetic operators are:
+
Sum of operands
Difference of operands
*
product of operands
/
Quotient (an integer value) of operands
Relational Operators
Relational operators specify relational operations so that any two expressions can treated as operands and
evaluated as returning true (1) or false (0). Relational operators are:
= or EQ Equal to
< or LT
Less than
=> or GT Greater than
<= or LE
Less than or equal to
>= or GE greater than or equal to
# or NE Not equal
Logical Operators
The logical operators test two expressions for true or false and return a value of true or false. Logical operators
are:
AND
Returns true if both expressions are true.
OR
Returns true if any expressions is true.
Concatenation Operator
The concatenation operator is a colon (:)
IF Statement
The IF operator gives the A code its conditional capabilities. An IF statement looks like this:
IF expression THEN statement ELSE statement

Field Number (FMC) Operand

Specifies a field which contains the value to be used.
jQL

4-40

Programmers

Reference

Manual

Syntax
field-number{R{R}}
Syntax Elements
field-number is the number of the field (FMC) which contains the required value.
R specifies that the value obtained from this field is to be applied repeatedly for each multivalue not present in a
corresponding part of the calculation.
RR specifies that the value obtained from this field is to be applied repeatedly for each subvalue not present in a
corresponding part of the calculation.
Notes
The following field numbers have special meanings:
0
Record key
9999 Record size in bytes
9998 Sequential record count
Example 1
A;2
Returns the value stored in field 2 of the record.
Example 2
A;9999
Returns the size of the record in bytes.
Example 3
A;2 + 3R
For each multivalue in field 2 the system also obtains the (first) value in field 3 and adds it. If field 2 contains
1]7 and field 3 contains 5 the result would be two values of 6 and 12 respectively. Where 3 does not have a
corresponding multivalue, the last non-null multivalue in 3 will be used.
Example 4
A;2 + 3RR
For each subvalue in field 2 the system also obtains the corresponding subvalue in field 3 and adds it. If field 2
contains 1\2\3]7 and field 3 contains 5\4 the result would be four values of 6, 6, 7, 12 and 4 respectively.

N (Field Name) Operand

References another field defined by name in the same dictionary or found in one of the default dictionaries.
Syntax
N(field-name){R{R}}
Syntax Elements
field-name is the name of another field defined in the same dictionary or found in the list of default dictionaries
(see the JBCDEFDICTS environment variable).
R specifies that the value obtained from this field is to be applied repeatedly for each multivalue not present in a
corresponding part of the calculation.
RR specifies that the value obtained from this field is to be applied repeatedly for each subvalue not present in a
corresponding part of the calculation.

Programmers Reference Manual

4-41

jQL

Notes
If the data definition record of the specified field contains field 8 pre-process conversion codes, these are applied
before the value(s) are returned.
Any pre-process conversion codes in the specified field-name, including any further N(field-name) constructs are
processed as part of the conversion code.
N(field-name) constructs can be nested to 30 levels. The number of levels is restricted to prevent infinite
processing loops. For example:
TEST1
008 A;N(TEST2)
TEST2
008 A;N(TEST1)
Example 1
A;N(S.CODE)
Returns the value stored in the field defined by S.CODE.
Example 2
A;N(A.VALUE) + N(B.VALUE)R
For each multivalue in the field defined by A.VALUE the system also obtains the corresponding value in
B.VALUE and adds it. If A.VALUE returns 1]7 and B.VALUE returns 5, the result would be two values of 6
and 12 respectively.
Example 3
A;N(A.VALUE) + N(B.VALUE)RR
For each subvalue in the field defined by A.VALUE the system also obtains the corresponding value in
B.VALUE and adds it. If A.VALUE returns 1\2\3]7 and B.VALUE returns 5 the result would be four values of
6, 7, 8 and 12 respectively.

Literal Operand
Specifies a literal string or numeric constant enclosed in double quotes.
Syntax
literal
Syntax Elements
literal is a text string or a numeric constant.
Notes
A number not enclosed in double quotes is assumed to be a field number (FMC).
Example 1
A;N(S.CODE) + 100
Adds 100 to each value (subvalue) in the field defined by S.CODE.
Example 2
A;N(S.CODE):SUFFIX
Concatenates the string SUFFIX to each value (subvalue) returned by S.CODE.

jQL

4-42

Programmers

Reference

Manual

System Parameter Operands

Reference system parameters like date, time, the current break level, or the number of the current record.
Syntax
system-operand
Syntax Elements
system-operand can be any of the following:
D

Returns the system date in internal format.

LPV Returns the previous value transformed by a format code.

NA Returns the number of fields in the record.
NB
ND

Returns the current break level counter. 1 is the lowest break level, 255 is the GRAND TOTAL line.
Returns the number of records (detail lines) since the last control break.

NI
NL

Returns the record counter.

Returns the record length in bytes

NS
NU

Returns the subvalue counter

Returns the date of last update

NV
T

Returns the value counter

Returns the system time in internal format.

Returns the previous value transformed by a format code

Special Operands
Integer Function
The Integer Function I(expression) returns the integer portion of expression.
Example
AE;I(N(COST) * N(QTY))
Returns the integer portion of the result of the calculation.
Remainder Function
The Remainder Function R(exp1, exp2) takes two expressions as operands and returns the remainder when the
first expression is divided by the second.
Example
A;R(N(HOURS) / 24)
Returns the remainder when HOURS is divided by 24.
Summation Function
The Summation Function S(expression) evaluates an expression and then adds together all the values.
Example
A;S(N(HOURS) * N(RATE)R)
Each value in the HOURS field is multiplied by the value of RATE. The multivalued list of results is then
totalled.

Programmers Reference Manual

4-43

jQL

Substring Function
The substring function [start-char-no, len] extracts the specified number of characters from a string, starting at a
specified character.
Syntax Elements
start-char-no is an expression that evaluates to the position of the first character of the substring.
len is an expression that evaluates to the number of characters required in the substring. Use - len (minus prefix)
to specify the end point of the substring. For example, [1, -2] will return all but the last character and [-3, 3] will
return the last three characters.
Example 1
A;N(S.CODE)[2, 3]
Extracts a sub-string from the S.CODE field, starting at character position 2 and continuing for 3 characters.
Example 2
A;N(S.CODE)[2, N(SUB.CODE.LEN)]
Extracts a sub-string from the S.CODE field, starting at the character position defined by field 2 and continuing
for the number of characters defined by SUB.CODE.LEN.

Format Codes
Specifies a format code to be applied to the result of the A code or an operand.
Syntax
a-code{]format-code...}
a-operand(format-code{]format-code}...)
Syntax Elements
a-code is a complete A Code expression.
a-operand is one of the A Code operands.
format-code is one of the codes described later - G(roup), D(ate) or M(ask).
] represents a value mark <CTRL ]> that must be used to separate each format-code.
Notes
You can format the result of the complete A code operation by following the expression with a value mark and
then the required format code(s). (This is actually a standard feature of the data definition records.)
Format codes can also be included within A code expressions. In this case, they must be enclosed in parentheses,
and separated with a value mark if more than one format code is used.
All format codes will convert values from an internal format to an output format.
Example 1
A;N(COST)(MD2]G0.1) * ...
Shows two format code applied within an expression. Obtains the COST value and applies an MD2 format code.
Then applies a group extract to acquire the integer portion of the formatted value. The integer portion can then
be used in the rest of the calculation.
Could also have been achieved like this:
A;I(N(COST)(MD2)) * ...

jQL

4-44

Programmers

Reference

Manual

Example 2
A;N(COST) * N(QTY)]MD2
Shows the MD2 format code applied outside the A code expression. COST is multiplied by QTY and the result
formatted by the MD2 format code.

Operators
Operators used in A code expressions include arithmetic, relational and logical operators, the concatenation
operator, and the IF statement.
Arithmetic Operators
Arithmetic operators are:
+
Sum of operands
Difference of operands
*
product of operands
/
Quotient (an integer value) of operands
Relational Operators
Relational operators specify relational operations so that any two expressions can treated as operands and
evaluated as returning true (1) or false (0). Relational operators are:
= or EQ Equal to
< or LT
Less than
=> or GT Greater than
<= or LE
Less than or equal to
>= or GE greater than or equal to
# or NE Not equal
Logical Operators
The logical operators test two expressions for true (1) or false (0) and return a value of true or false. Logical
operators are:
AND
Returns true if both expressions are true.
OR
Returns true if any expressions is true.
The words AND and OR must be followed by at least one space. The AND operator takes precedence over the
OR unless you specify a different order by means of parentheses. OR is the default operation.
Concatenation Operator
A colon (:) is used to concatenate the results of two expressions.
For example, the following expression concatenates the character Z with the result of adding together fields 2
and 3:
A;Z:2 + 3
IF Statement
The IF statement gives the A code conditional capabilities.
Syntax
IF expression THEN statement ELSE statement
Syntax Elements
expression must evaluate to true or false. If true, executes the THEN statement. If false, executes the ELSE
statement
statement is a string or numeric value.

Programmers Reference Manual

4-45

jQL

Notes
Each IF statement must have a THEN clause and a corresponding ELSE clause.
IF statements can be nested but the result of the statement must evaluate to a single value.
The words IF, THEN and ELSE must be followed by at least one space.
Example 1
A;IF N(QTY) < 100 THEN N(QTY) ELSE ERROR!
Tests the QTY value to see if it is less than 100. If it is, output the QTY field. Otherwise, output the text
ERROR!.
Example 2
A;IF N(QTY) < 100 AND N(COST) < 1000 THEN N(QTY) ELSE ERROR!
Same as example 1 except that QTY will only be output if it is less than 100 and the cost value is less than 1000.
Example 3
A;IF 1 THEN IF 2 THEN 3 ELSE 4 ELSE 5
If field 1 is zero or null, follow else and use field 5. Otherwise test field 2. If field 2 is zero or null, follow else
and use field 4. Otherwise use field 3.
Field 3 is only used if both fields 1 and 2 contain a value.

jQL

4-46

Programmers

Reference

Manual

B Code - Subroutine Call

Provides interface for jBC subroutines or C functions to manipulate data during jQL processing. Synonymous
with CALL code.
See CALL code for more details.

Programmers Reference Manual

4-47

jQL

C Code - Concatenation
Concatenates fields, literals, and the results of a previous operation.
Syntax
C{;}n{xn}...
Syntax Elements
; is optional. It has no function other than to provide compatibility.
n can be one of the following:
a field number (FMC)
a literal enclosed in single quotes, double quotes, or backslashes
an asterisk (*) to specify the last generated value of a previous operation.
x is the character to be inserted between the concatenated elements. If you specify a semicolon (;), no separator
will be used. Any non-numeric character except a system delimiters (value, subvalue, field, start buffer, and
segment marks) is valid.
Notes
See the descriptions of the function codes (A, F, FS and their variants) for other concatenation methods.
Input Conversion
Input conversion does not invert. The concatenation is applied to the input data.
Example 1
C1;2
Concatenates the contents of field 1 with field 2, with no intervening separator character.
Example 2
C1*2
Concatenates the contents of field 1 with an asterisk (*) and then the content of field 2.
Example 3
C1*ABC 2/3
Concatenates the contents of field 1 with an asterisk (*), the string ABC, a space, field 2 a forward slash (/) and
then field 3.

jQL

4-48

Programmers

Reference

Manual

CALL Code - Subroutine Call

Provides an interface for jBC subroutines or C functions to manipulate data during jQL processing. Synonymous
with B code.
Syntax
B;{filename}subname
CALL{X} {filename}subname
Syntax Elements
filename is ignored but provided for compatibility with older systems.
subname is the name of the called subroutine (or function). This subroutine must reside in one of the libraries
defined for the user.
Notes
Use the B or CALL code when you need to perform processing that is not possible with other available codes.
All necessary variables are pre-defined in a COMMON block that you must INCLUDE in your subroutine. See
the Advanced Programmers Reference Manual for more information on constructing C functions.
Subroutine programs must start with these lines:
SUBROUTINE subname {(parameter)}
INCLUDE qbasiccommon
Option parameter is only used when the JBCEMULATE environment variable is set to AP.
qbasiccommon is a standard header file provided with jBASE. You may need to include a different
qbasiccommon block, depending on the emulation in use. If required, you can create your own version of the
code. See the Advanced Programmers Reference Manual for more information.
qbasiccommon defines the following COMMON data values:
file descriptor variables for the current file and dictionary
name of the file being processed
current record key
current record being processed - as a dynamic array
current data value (the data which will subsequently be output)
number of records processed so far
current values of the field, value and subvalue mark counts
number of detail lines output since the last break line
a value to indicate the current status of the process. One of the following
0
processing a detail line
1 - 15 processing a break line - break level is indicated by the value
127 processing a GRAND-TOTAL line
-1
processing a SORT or SELECT
Example 1
LIST SALES COMMENTS
COMMENTS
(in DICT of SALES file)
001 A
002 3
003 Comments
004

Programmers Reference Manual

4-49

jQL

005
006
007 B;comments
008
009 T
010 25
comments
(jBC subroutine in available library)
001 SUBROUTINE comments
002 INCLUDE qbasiccommon
003 * Interpret Comment code
004 IF Data = A THEN Data = Grade 1
005 IF Data = B THEN Data = Grade 2
006 RETURN
Output:
SALES........ Comments.................
ABC
DEF

jQL

Grade 1
Grade 2

4-50

Programmers

Reference

Manual

D Code - Date Conversion

Converts dates between internal and external format.
Syntax
D{p}{n}{s}
Syntax Elements
p is the special processing operator. Can be any one of the following:
D
Returns only the day of the month as a numeric value.
I
Returns only dates stored in the external format in internal format. You can use this in field 7 or 8.
J
Returns the Julian day (1 - 365, or 1 - 366 for a leap year).
M
Returns the number of the month (1 - 12).
MA Returns the name of the month in uppercase letters.
Q
Returns the number of the quarter (1 - 4)
W
Returns the day of the week as a numeric value (Monday is 1).
WA Returns the day of the week in uppercase letters (MONDAY - SUNDAY).
Y
Returns the year (up to four digits).
n is a number from 0 to 4 that specifies the how many digits to use for the year field. If omitted, the year will
have four-digits. If n is 0, the year will be suppressed.
s is a non-numeric character to be used as a separator between month, date, and year. Must not be one of the
special processing operators.
Notes
Dates are stored internally as integers which represent the number of days (plus or minus) from the base date of
December 31, 1967. For example:
Date
22 September 1967
30 December 1967
31 December 1967
01 January 1968
09 April 1968
26 September 1967
14 January 1995

Stored Value
-100
-1
0
1
100
1000
9876

If you do not specify a special processing operator (see later) or an output separator, the default output format is
two-digit day, a space, a three-character month, a space, and a four-digit year.
If you specify just an output separator, the date format defaults either to the US numeric format 'mm/dd/yyyy' or
to the international numeric format 'dd/mm/yyyy' (where / is the separator). You can change the numeric format
for the duration of a logon session with the DATE-FORMAT command.
Pre-processor Conversion
Field 8 codes are valid but, generally, it is easier to specify the D code in field 7 for input conversion. Dates in
output format are difficult to use in selection processing.
If you are going to use selection processing and you want to use a code which reduces the date to one of its parts,
such as DD (day of month), the D code must be specified in field 8.
Input/Output Conversion
Field 7 input and output conversions are both valid.
Generally, for selection processing, you should specify D codes in field 7. An exception is when you use a
formatting code, such as DM, that reduces the date to one of its parts.
If no year is specified in the sentence, the system assumes the current year on input conversion. If only the last
two digits of the year are specified, the system assumes the following years:

Programmers Reference Manual

4-51

jQL

00-29 2000-2029
30-99 1930-1999
Examples
D Code
D
D2/
DD0
DD
DI
DJ
DM
DMA
DQ
DW
DWA
DY
DY2

jQL

Internal Value
9904
9904
9904
9904
9904
11 FEB 1995
9904
9904
9904
9904
9904
9904
9904
9904

Value Returned
11 FEB 1995
11/02/95
11-02-1995
11 FEB
11
9904
41
2
FEB
1
6
SATURDAY
1995
95

4-52

Programmers

Reference

Manual

D1 / D2 Codes - Controlling and Dependent Fields

Associates controlling and dependent fields.
Syntax
D1;fmcd{;fmcd}...
D2;fmcc
Syntax Elements
fmcd is the field number (FMC) of an associated dependent field.
fmcc is the field number (FMC) of the associated controlling field.
Notes
You can logically group multivalued fields in a record by using a controlling multivalued field and associating
other fields with it. You could, for example, group the component parts of an assembly on an invoice.
The D1 code in field 8 defines the controlling field and nominates the associated dependent fields. Each
dependent field will have a D2 code in field 8.
IMPORTANT: The D1 and D2 codes must be in field 8 of the data definition record and must
be the first code specified. The code can be followed by other codes (separated by a value
mark), but it must be the first code.
The values in the dependent associative fields are output in the order in which they are specified in the field 8 of
the controlling field. The order in which the dependent fields are specified in the output specification clause is
irrelevant.
Dependent fields are marked on the output by an asterisk just below the column heading.
If the output for a controlling field is suppressed, the values in the dependent fields will also be suppressed.
Example
LIST INVOICE ABC123 PARTS QTY PRICE
The records in data file INVOICE have 3 associated, multivalued fields. The fields are named PARTS, QTY and
PRICE, and numbered 7, 2 and 5 respectively.
PARTS is the controlling field because, for each multivalue in this field there will a corresponding value in the
other fields, and also because PARTS should appear first on the report. The data definition record for PARTS
will have D1;2;5 in field 8.
The data definition records for QTY and PRICE will both have D2;7 in field 8.
The report generated by the command will look something like this:
INVOICE PART
ABC123

AAA
BBB
CCC
...

Programmers Reference Manual

QTY
*
1
11
2
..

PRICE
*
10.00
4.00
3.30
...

4-53

jQL

F Code - Mathematical Functions

F codes provide many facilities for arithmetic, relational, logical, and concatenation operations. All operations
are expressed in Reverse Polish notation and involve the use of a stack to manipulate the data.

Syntax Summary
There are three forms of the F code:
F

Uses only the integer parts of stored numbers unless a scaling factor is included. If the JBCEMULATE
environment variable is set to ROS, the operands for -, / and concatenate are used in the reverse
order.

FS Uses only the integer parts of stored numbers.

FE Uses both the integer and fraction parts of stored numbers.
Syntax
F{n};elem{;elem}...
FS;elem{;elem}...
FE;elem{;elem}
Syntax Elements
n is a number from 1 to 9 used to convert a stored value to a scaled integer. The stored value's explicit or implied
decimal point is moved n digits to the right with zeros added if necessary. Only the integer portion of this
operation is returned.
elem is any valid operator. See later.
Notes
F codes use the Reverse Polish notation system. Reverse Polish is a postfix notation system where the operator
follows the operands. The expression for adding two elements is a b +. (The usual algebraic system is an infix
notation where the operator is placed between the operands, for example, a + b).
The F code has operators to push operands on the stack. Other operators perform arithmetic, relational, and
logical operations on stack elements. There are also concatenation and string operators.
Operands that are pushed on the stack may be constants, field values, system parameters (such as data and time),
or counters (such as record counters).
The Stack
F codes work with a pushdown stack.
Operators push values onto the stack, perform arithmetic and other operations on the stack entries, and pop
values off the stack.
The term push is used to indicate the placing of an entry (a value) onto the top of the stack so that existing
entries are pushed down one level. Pop means to remove an entry from the top of the stack so that existing
entries pop up by one level.
Arithmetic functions typically begin by pushing two or more entries onto the stack. Each operation then pops the
top two entries, and pushes the result back onto the top of the stack. After any operation is complete, the result
will always be contained in entry 1.
Order of Operation
F code operations are typically expressed as F;stack2;stack1;operation. Under most emulations, this will be
evaluated as stack2 operation stack1. If JBCEMULATE is set to ROS, this example is evaluated as stack1
operation stack2, effectively reversing the order of operations.

jQL

4-54

Programmers

Reference

Manual

Note that the FE and FS codes are evaluated in the same way for all emulations.
Input Conversion
Input conversion is not allowed.
Example 1
F;C3;C5;Push a value of 3 onto the stack. Push a value of 5 onto the stack.
Take entry 1 from entry 2 (3 - 5) and push the result (-2) back onto the stack as entry 1. ROS emulations will
subtract 3 from 5 and return a result of 2.
Example 2
FS;C3;C5;Push a value of 3 onto the stack. Push a value of 5 onto the stack.
Take entry 2 from entry 1 (3 - 5) and push the result (-2) back onto the stack. This works in the same way for all
emulations.
Example 3
F;C2;C11;C3;-;/
Push a value of 2 onto the stack. Push a value of 11 onto the stack. Push a value of 3 onto the stack.
Subtract entry 1 from entry 2 (11 - 3) and push the result (8) back onto the stack. Now divide entry 2 by entry 1
(2 divided by 8) and push the result (0) back onto the stack.
Under ROS emulation, this would evaluate as 3 - 11 = -8, followed by -8 / 2 = -4.

Push Operators
A push operator always pushes a single entry onto the stack. Existing entries are pushed down one position. Push
operators are:
literal

Literal. Any text string enclosed in double or single quotes.

field-number{R{R}}{(format-code)}
field-number is the value of the field from the current record.
R specifies that the last non-null value obtained from this field is to be applied repeatedly for each
multivalue that does not exist in a corresponding part of the calculation.
RR specifies that the last non-null value obtained from this field is to be applied repeatedly for each
subvalue that does not exist in a corresponding part of the calculation.
(format-code) is one or more format codes (separated by value marks <CTRL ]>) enclosed in
parentheses. Applied to the value before it is pushed onto the stack.
Cn

Constant. Where n is a constant (text or number) of any length up to the next semicolon or system
delimiter.

Current system date.

NA

Number of fields in the record.

NB

Current break level number:

-1 = during SORT or SELECT processing
0 = detail line
1 = lowest break level
255 = GRAND-TOTAL line

ND

Number of records since the last BREAK on a BREAK data line. Equal to the record counter on a
GRAND-TOTAL line. Used to compute averages.

Programmers Reference Manual

4-55

jQL

NI

Record counter. The ordinal position of the current record in the report.

NL

Length of the record, in bytes. Includes all field marks but not the key.

NS

Subvalue counter. The ordinal position of the current subvalue within the field.

NV

Value Counter. The ordinal position of the current multivalue within the field.

P or "

Duplicate of entry 1 is pushed onto the stack.

System time in internal format.

V or LPV Previous Value. The value from the previous format code is to be used.

Arithmetic Operators
The arithmetic F code operators work on just the top stack entry or the top two stack entries. They are:
+

Add the top two stack entries together and push result into entry 1.

Subtract stack entries and push result into entry 1:

F
subtract entry 1 from entry 2
FS, FE subtract entry 1 from entry 2
ROS emulation:
F
subtract entry 2 from entry 1

*{n} Multiply the top two stack entries and push result into entry 1. If n is specified, the
divided by 10 raised to the power of n.
/

result

is

Divide stack entries and push quotient into entry 1:

F
divide entry 2 by entry 1
FS, FE divide entry 2 by entry 1
ROS emulation:
F
divide entry 1 by entry 2

Compute remainder from the top two stack entries and push result into entry 1:
F
remainder of entry 2 / entry 1
FS, FE remainder of entry 2 / entry 1
ROS emulation:
F
remainder of entry 1 / entry 2

Return the integer part of entry 1 to the top of the stack.

Replace the multivalued entry 1 with the sum of the multivalues and subvalues.

Miscellaneous Operators
Miscellaneous operators control formatting, exchanging stack entries, popping the top entry, concatenation, and
string extraction. They are:
_

Exchange the top two entries.

Pop last entry from the stack and discard. All other entries are pushed up.

(format-code) Perform the specified format code on last entry and replace last entry with the result.
:

Concatenate stack entries:

F
Concatenates Entry 1 to the end of Entry 2
FS, FE Concatenates Entry 1 to the end of Entry 2
ROS emulation:
F
Concatenates Entry 2 to the end of Entry 1

[]

jQL

Extract a substring from stack entry 3. The starting column is specified in stack entry 2 and
the number of characters is specified in entry 1.

4-56

Programmers

Reference

Manual

Relational Operators
Relational operators compare stack entries. The result is pushed onto stack entry 1 and is either 1 (true) or 0
(false). Relational operators are:
=

Equal to

<

Less than:
F
entry 2 < entry 1
FS, FE entry 2 < entry 1
ROS emulation:
F
entry 1 < entry 2

>

Greater than:
F
entry 2 > entry 1
FS, FE entry 2 > entry 1
ROS emulation:
F
entry 1 > entry 2

Less than or equal to:

F
entry 2 [ entry 1
FS, FE entry 2 [ entry 1
ROS emulation:
F
entry 1 [ entry 2

Great than or equal to:

F
entry 2 ] entry 1
FS, FE entry 2 ] entry 1
ROS emulation:
F
entry 1 ] entry 2

Not equal.

Logical Operators
Logical operators include a logical AND test and a logical inclusive-OR test.
Logical operators are:
&

AND stack entries 1 and 2. If both entries contain non zero, a 1 is pushed onto stack entry 1,
otherwise, a 0 is pushed.

OR stack entries 1 and 2. If either of the entries contains non zero, a 1 is pushed onto stack entry
1; otherwise, a 0 is pushed.

Multivalues
A powerful feature of F and FS code operations is their ability to manipulate multivalues. Individual multivalues
can be processed, one-by-one, or you can use the R (or RR) modifier after a field number, to repeat a value and
thus combine it with each of a series of multivalues.
Field operands may be valued and subvalued. When mathematical operations are performed on two multivalued
lists (vectors), the result is also multivalued. The result has an many values as the longer of the two lists. Zeros
are substituted for the null values in the shorter list if the R option is not specified.
Repeat Operators
To repeat a value for combination with multivalues, follow the field number with the R operator. To repeat a
value for combination with multiple subvalues, follow the FMC with the RR operator.

Programmers Reference Manual

4-57

jQL

Format Codes
Format codes can be used in three ways. One transforms the final result of the F code, another transforms the
content of a field before it is pushed on the stack, and the third transforms the top entry on the stack.
Syntax
f-code{]format-code...}
field-number(format-code{]format-code}...)
(format-code{]format-code}...)
Syntax Elements
f-code is a complete F Code expression.
field-number is the field number in the record from which the data is to be retrieved.
format-code is any valid format codes.
] represents a value mark <CTRL ]> that must be used to separate each format-code.
Notes
To process a field before it is pushed on the stack, follow the FMC with the format codes enclosed in
parentheses.
To process the top entry on the stack, specify the format codes within parentheses as an operation by itself.
To specify more than one format code in one operation, separate the codes with the value mark, <CTRL ]>.
All format codes will convert values from an internal format to an output format.
Example
F;2(MD2]G0.1);100;Obtain the value of field 2. Apply an MD2 format code. Then apply a group extract to acquire the integer
portion of the formatted value, and push the result onto the stack. Subtract 100 from the field 2 value. Return this
value. Note that under ROS emulation, the value returned would be the result of subtracting the integer value
from the group extract, from 100. In other words:
100 - OCONV(OCONV(Field2, MD2), G0.1).

jQL

4-58

Programmers

Reference

Manual

G Code - Group Extraction

G codes extract one or more contiguous strings (separated by a specified character), from a field value.
Syntax
G{m}xn
Syntax Elements
m is the number of strings to skip. If omitted or zero, extraction begins with the first character.
x is the separation character.
n is the number of strings to be extracted.
Notes
The field value can consist of any number of strings, each separated by the specified character. The separator can
be any non-numeric character, except a system delimiter.
If m is zero or null and the separator x is not found, the whole field will be returned. If m is not zero or null and
the separator x is not found, null will be returned.
Input Conversion
Input conversion does not invert. It simply applies the group extraction to the input data.
Example 1
G0.1
If the field contains 123.45, 123 will be returned. You could also use G.1 to achieve the same effect.
Example 2
G2/1
If the field contains ABC/DEF/GHI, GHI will be returned.
Example 3
G0,3
If the field contains ABC,DEF,GHI,JKL, ABC,DEF,GHI will be returned. Note that the field separators are
included in the returned string.

Programmers Reference Manual

4-59

jQL

L Code - Length
L codes return the length of a value, or the value if it is within specified criteria.
Syntax
L{{min,}max}
Syntax Elements
min specifies that the process is to return an element if its length is greater than or equal to the number min.
max specifies that the process is to return an element if its length is less than or equal to the number max.
Notes
The L code by itself returns the length of an element.
When used with max, or min and max, the L code returns the element if it is within the length specified by min
and/or max.
Input Conversion
Input conversion does not invert. It simply applies the length processing to the input data.
Example 1
L
Assuming a value of ABCDEF, returns the length of the value - in this case, 6.
Example 2
L4
If JBCEMULATE is set to ROS, L4 is translated as return the value if its length is less than or equal to 4 - the
equivalent of L0,4. Assuming a value of ABCDEF, L4 will return null - the value is longer than 4 characters.
If JBCEMULATE is not set to ROS, L4 is translated as return the value if its length is exactly equal to 4 - the
equivalent of L4,4. Assuming a value of ABCDEF, L4 will return null - the value is longer than 4 characters.
Example 3
L4,7
L4,7 is translated as return the value if its length is greater than or equal to 4 and less than or equal to 7.
Assuming a value of ABCDEF, L4,7 will return ABCDEF.

jQL

4-60

Programmers

Reference

Manual

MC Codes - Mask Character

MC codes include facilities for:

Changing characters to upper or lower case.

Extracting a class of characters.
Replacing characters
Converting ASCII character codes to their hexadecimal or binary representations and vice versa.
Converting a hexadecimal values to their decimal or binary equivalents and vice versa.
Converting a decimal value to its equivalent in Roman numerals and vice versa.

One source of confusion when using MC codes is that input conversion does not always invert the code. For
most MC codes, if they are used in field 7 of the data definition record, the code will be applied in its original
(un-inverted) form to the input data. For this reason you should always try to put MC codes into field 8 of the
data definition record. The exceptions to this, where input conversion is effective, are clearly indicated in the
following sections.

Summary
MC codes are:
MCA

Extract only alphabetic characters

MC/A

Extract only non-alphabetic characters.

MCAB{S}

Convert ASCII character codes to binary representation. Use S to suppress spaces.

MCAX or MX

Convert ASCII character codes to hexadecimal representation.

MCB

Extract only alphabetic and numeric characters.

MC/B

Extract only special characters that are neither alphabetic nor numeric.

MCBA

Convert binary representation to ASCII characters.

MCBX

Convert a binary value to its hexadecimal equivalent.

MCC;x;y

Change all occurrences of character string x to character string y.

MCDR

Convert a decimal value to its equivalent Roman numerals. Input conversion is effective.

MCDX or MCD Convert a decimal value to its hexadecimal equivalent. Input conversion is effective.
MCL

Convert all upper case letters (A-Z) to lower case.

MCN

Extract only numeric characters (0-9).

MC/N

Extract only non-numeric characters.

MCNP{c}

Convert paired hexadecimal digits preceded by a tilde or character c to ASCII code.

MCP{c}

Convert each non-printable character (X'00' - X'IF', X'80' - X'FE') to a tilde (~) or to character
c.

MCPN{c}

Same as MCP but insert the two-character hexadecimal representation of the character
immediately after the tilde or character c.

MCRD or MCR Convert Roman numerals to the decimal equivalent. Input conversion is effective.
MCT

Convert all upper case letters (A-Z) in the text to lower case, starting with the second character
in each word. Change the first character of each word to upper case if it is a letter.

MCU

Convert all lower case letters (a-z) to upper case.

MCXA or MY

Convert hexadecimal representation to ASCII characters.

MCXB{S}

Convert a hexadecimal value to its binary equivalent. Use S to suppress spaces between each
block of 8 bytes.

MCXD or MCX Convert a hexadecimal value to its decimal equivalent. Input conversion is effective.

Programmers Reference Manual

4-61

jQL

Changing Case
The MC codes that can be used to transform text from upper to lower case and vice versa are:
MCL

Convert all upper case letters (A-Z) to lower case

MCT

Convert all upper case letters (A-Z) in the text to lower case, starting with the second character in
each word. Change the first character of each word to upper case.

MCU

Convert all lower case letters (a-z) to upper case.

Input Conversion
Input conversion does not invert. The conversion code will be applied to the input data.
Example 1
MCL
Assuming a source value of AbCdEf, MCL will return abcdef.
Example 2
MCT
Assuming a source value of AbC dEf ghi, MCT will return Abc Def ghi.
Example 3
MCU
Assuming a source value of AbCdEf, MCU will return ABCDEF.

Extracting Characters
The MC codes that can be used to extract characters from a string are:
MCA

Extract only alphabetic characters.

MC/A

Extract only non-alphabetic characters.

MCB

Extract only alphanumeric characters.

MC/B

Extract only special characters that are neither alphabetic nor numeric.

MCN

Extract only numeric characters (0-9).

MC/N

Extract only non-numeric characters.

Input Conversion
Input conversion does not invert. The original code will be applied to input data.
Example 1
MCA
Assuming a source value of ABC*123!DEF, MCA will return ABCDEF.
Example 2
MC/A
Assuming a source value of ABC*123!DEF, MC/A will return *123!.
Example 3
MCB
Assuming a source value of ABC*123!DEF, MCB will return ABC123DEF.
jQL

4-62

Programmers

Reference

Manual

Example 4
MC/B
Assuming a source value of ABC*123!DEF, MC/B will return *!.
Example 5
MCN
Assuming a source value of ABC*123!DEF, MCN will return 123.
Example 6
MC/N
Assuming a source value of ABC*123!DEF, MC/N will return ABC*!DEF.

Replacing Characters
Some MC codes replace one set of characters with other characters. These codes can:

exchange one character string for another;

replace non-printable characters with a marker character;
replace non-printable characters with a marker character and the character's hexadecimal
representation;
replace the marker and hexadecimal representation with the ASCII code.

The codes are:

MCC;x;y

Change all occurrences of character string x to character string y.

MCP{c}

Convert each non-printable character (X'00' - X'IF', X'80' - X'FE') to character c, or tilde (~) if c is
not specified.

MCPN{c}

Same as MCP but insert the two-character hexadecimal representation of the character
immediately after character c, or tilde (~) if c is not specified..

MCNP{c}

Convert paired hexadecimal digits preceded by a tilde or character c to ASCII code. The opposite
of the MCPN code.

Input Conversion
Input conversion does not invert. The original code will be applied to input data.
Example 1
MCC;X5X;YYY
Assuming a source value of ABC*X5X!DEF, MCC will return ABC*YYY!DEF.
Example 2
MCPN.
Assuming a source value of ABC]]DEF where ] represents a value mark, <CTRL ]>, MCPN will return
ABC.FC.FCDEF.

Converting Characters
The MC codes that convert ASCII character codes to their binary or hexadecimal representations or vice versa
are:
MCAB{S}

Convert ASCII character codes to binary representation (Use S to suppress spaces).

MCAX or MY Convert ASCII character codes to hexadecimal representation

MCBA

Convert binary representation to ASCII characters.

MCXA or MX Convert hexadecimal representation to ASCII characters.

Programmers Reference Manual

4-63

jQL

Notes
The MCAB and MCABS codes convert each ASCII character to its binary equivalent as an eight-digit number.
If there is more than one character, MCAB puts a blank space between each pair of eight-digit numbers.
MCABS suppresses the spaces.
When converting from binary to ASCII characters, MCBA uses blank spaces as dividers, if they are present.
MCBA scans from the right-hand end of the data searching for elements of eight-bit binary strings. If it
encounters a space and the element is not eight binary digits long, it prepends zeros to the front of the number
until it contains eight digits. This continues until the leftmost digit is reached. Zeros are again prepended, if
necessary. Each eight-digit element is then converted to its ASCII character equivalent.
Input Conversion
Input conversion does not invert. The original code will be applied to input data.
Example 1
MCAX
Assuming a source value of ABC, MCAX will return 414243.
Example 2
MCXA
Assuming a source value of 414243, MCXA will return ABC.
Example 3
MCAB
Assuming a source value of AB, MCAB will return 01000001 01000010.
Example 4
MCABS
Assuming a source value of AB, MCABS will return 0100000101000010.
Example 5
MCBA
Assuming a source value of 01000001 1000010, MCBA will return AB. Note the missing binary digit at the start
of the second element of the source value.
Example 6
MCBA
Assuming a source value of 0100000101000010, MCBA will return AB.

Converting Numeric Values

The MC codes that convert numeric values (as opposed to characters), to equivalent values in other number
schemes are:
MCBX{S}

Convert a binary value to its hexadecimal equivalent. Use S to suppress spaces.

MCDR

Convert a decimal value to its equivalent Roman numerals. Input conversion is effective.

MCDX or MCD Convert a decimal value to its hexadecimal equivalent. Input conversion is effective.
MCRD or MCR Convert Roman numerals to the decimal equivalent. Input conversion is effective.
MCXB{S}

Convert a hexadecimal value to its binary equivalent. Use S to suppress spaces.

MCXD or MCX Convert a hexadecimal value to its decimal equivalent. Input conversion is effective.
jQL

4-64

Programmers

Reference

Manual

Notes
These codes convert numeric values rather than individual characters. For example, a decimal value of 60 would
be converted to X'3C' in hexadecimal, or LX in Roman numerals. The value 60 is converted, not the characters
"6" and "0".
With the exception of MCBX{S} which will handle spaces, all these codes will stop if they encounter a
character that is not a digit of the source number system. The value up to the invalid character will be converted.
With the exception of MCDR, if the conversion fails to find any valid digits, a zero will be returned. MCDR will
return null.
If you submit an odd number of hexadecimal digits to the MCXB code, it will add a leading zero (to arrive at an
even number of characters) before converting the value.
The MCXB and MCXBS codes convert each pair of hexadecimal digits to its binary equivalent as a eight-digit
number. If there is more than one pair of hexadecimal digit, MCXB puts a blank space between each paid of
eight-digit numbers. MCXBS suppresses the spaces.
When converting from binary to hexadecimal digits, MCBX uses blank spaces as dividers if they are present.
MCBX effectively scans from the right-hand end of the data searching for elements of eight-bit binary digits. If it
encounters a space and the element is not a multiple of eight binary digits, it prepends zeros to the front of the
number until contains eight digits. This continues until the leftmost digit is reached. Zeros are again prepended,
if necessary. Each eight-digit element is then converted to a hexadecimal character pair.
Input Conversion
Input conversion is effective for MCDR, MCDX, MCRD and MCXD.
Input conversion is not inverted for the other codes. The original code will be applied to input data.
Example 1
MCBX
Assuming a source value of 01000001 1000010, MCBX will return 4142. Would return the same value if there
was no space between the binary source elements.
Example 2
MCRD
Assuming a source value of MLXVI, MCRD will return 1066.
Example 3
MCDX
Assuming a source value of 1066, MCDX will return 42A.

Programmers Reference Manual

4-65

jQL

MD Code - Mask Decimal without Justification

The MD code transforms integers by scaling them and inserting symbols, such as a currency sign, thousands
separators, and a decimal point. The ML and MR codes are similar to MD but have greater functionality.
Syntax
MDn{m}{Z}{,}{$}{ix}{c}
Syntax Elements
n is a number from 0 to 9 that specifies how many digits are to be output after the decimal point. Trailing zeros
are inserted as necessary. If n is omitted or 0, the decimal point is not output.
m is a number from 0 to 9 which represents the number of digits that the source value contains to the right of the
implied decimal point. m is used as a scaling factor and the source value is descaled (divided) by that power of
10. For example, if m=1, the value is divided by 10; if m=2, the value is divided by 100, and so on.
If m is omitted, it is assumed to be equal to n (the decimal precision). If m is greater than n, the source value is
rounded up or down to n digits. The m option must be present if the ix option is used and both the Z and $
options are omitted. This to remove ambiguity with the ix option.
Z suppresses leading zeros. Note that fractional values which have no integer will have a zero before the decimal
point. If the value is zero, a null will be output.
, specifies insertion of the thousands separator symbol every three digits to the left of the decimal point. The type
of separator (comma or period) is specified through the SET-THOU command. (Use the SET-DEC command to
specify the decimal separator.)
$ appends an appropriate currency symbol to the number. The currency symbol is specified through the SETMONEY command.
ix aligns the currency symbol by creating a blank field of 'i' number of columns. The value to be output
overwrites the blanks. The 'x' parameter specifies a filler character that can be any non-numeric character,
including a space.
c appends a credit character or encloses the value in angle brackets (< >). Can be any one of the following:
-

Appends a minus sign to negative values. Positive or zero values are followed by a blank.

Appends the characters CR to negative values. Positive or zero values are followed by two blanks.

<

Encloses negative values in angle brackets (< >).

Input Conversion
Input conversion works with a number that has only thousands separators and a decimal point.
Examples
MD Code
MD2
MD2,
MD2,$
MD2,$12*
MD2,$12 MD42Z,$
MD42Z,$15 <

jQL

Source Value

Returned Value

1234567
1234567
1234567
1234567
-1234567
001234567
-001234567

12345.67
12,345.67
12,345.67
**12,345.67
12,345.6712,345.6700
< 12,345.6700>

4-66

Programmers

Reference

Manual

MK Code - Mask Metric

The MK code allows you to display large numbers in a minimum of columns by automatically descaling the
numbers and appending a letter to represent the power of 10 used. The letters and their meanings are:
K

10 /3

(Kilo)

10 /6

(Mega)

10 /9

(Giga)

Syntax
MKn
Syntax Elements
n is a number that represents the field width. This will include the letter and a minus sign, if present.
Notes
If a number will fit into the specified field width, it will not be changed.
If the number is too long but includes a decimal fraction, the MK code first attempts to round the fractional part
so that the number will fit the field. If the number is still too long, the code rounds off the three low-order integer
digits, replacing them with a K. If the number is still too long, the code rounds off the next three digits, replacing
them with an M. If that is still too long, the code rounds off three more digits, replacing them with a G. If the
number still does not fit the specified field, the code displays an asterisk.
If the field size is not specified or is zero, the code outputs null.
Input Conversion
Input conversion does not invert. It simply applies the metric processing to the input data.
Examples
Source Data

MK3

1234
123456789
123456789012345
999.9
-12.343567
-1234.5678
-0.1234

1K
*
*
1K
-12
-1K
-.1

Programmers Reference Manual

Code/Output
MK4
MK5
1234
123M
*
1000
-12
-1K
-.12

1234
123M
*
999.9
-12.3
-1235
-.123

4-67

MK7
1234
123457K
123457G
999.9
-12.344
-1234.6
-0.1234

jQL

ML/MR Codes - Mask Decimal with Justification

ML and MR codes format numbers and justify the result to the left or right respectively. The codes provide the
following capabilities:
Decimal precision and scaling
Zero suppression
Thousands separator
Credit codes
Currency symbol
Inclusion of literal character strings.
Syntax
ML{n{m}}{Z}{,}{c}{$}{fm}
MR{n{m}}{Z}{,}{c}{$}{fm}
Syntax Elements
ML provides left justification of the result.
MR provides right justification of the result.
n is a number from 0 to 9 that defines the decimal precision. Specifies the number of digits to be output
following the decimal point. The processor inserts trailing zeros if necessary. If n is omitted or is 0, a decimal
point will not be output.
m is a number that defines the scaling factor. The source value is descaled (divided) by that power of 10. For
example, if m=1, the value is divided by 10; if m=2, the value is divided by 100, and so on. If m is omitted, it is
assumed to be equal to n (the decimal precision).
Z suppresses leading zeros. Note that fractional values which have no integer will have a zero before the decimal
point. If the value is zero, a null will be output.
, is the thousands separator symbol. It specifies insertion of thousands separators every three digits to the left of
the decimal point. You can change the display separator symbol by invoking the SET-THOU command. (Use the
SET-DEC command to specify the decimal separator.)
c appends a credit character or encloses the value in angle brackets (< >). Can be any one of the following:
C
Print the literal CR after negative values.
D
Print the literal DB after positive values.
E
Enclose negative values in angle brackets <>.
M
Print a minus sign after negative values.
N
Suppresses embedded minus sign.
If a value is negative and you have not specified one of these indicators, the value will be displayed with a
leading minus sign. If you specify a credit indicator, the data will be output with either the credit characters or an
equivalent number of spaces, depending on its value.
$ specifies that a currency symbol is to be included. A floating currency symbol is placed in front of the value.
The currency symbol is specified through the SET-MONEY command.
fm specifies a format mask. A format mask can include literal characters as well as format codes. The format
codes are as follows:

jQL

Code

Function

#{n}

Spaces. Repeat space n times. Output value is overlaid on the spaces created.

*{n}

Asterisk. Repeat asterisk n times. Output value is overlaid on the asterisks created.

%{n}

Zero. Repeat zeros n times. Output value is overlaid on the zeros created.

4-68

Programmers

Reference

Manual

&x

Format. x can be any of the above format codes, a currency symbol, a space, or literal text. The
first character following & is used as the default fill character to replace #n fields without data.
Format strings may be enclosed in parentheses ( ).

Notes
The justification specified by the ML or MR code is applied at a different stage from that specified in field 9 of
the data definition record. The sequence of events starts with the data being formatted with the symbols, filler
characters and justification (left or right) specified by the ML or MR code. The formatted data is then justified
according to field 9 of the definition record and overlaid on the output field - which initially comprises the
number of spaces specified in field 10 of the data definition record.
Input Conversion
Input conversion works with a number that has only thousands separators and a decimal point.
Examples
Code
MR2#10
MR2#10
ML2%10
MR2%10
ML2*10
MR2*10
MR2,$#15
MR2,&$#15
ML2,&*$#15
MR2,& $#15
MR2,C&*$#15
ML& ###-##-####
ML& #3-#2-#4
ML& Text #2-#3
ML&((Text#2) #3)

Source
Value
1234
1234
1234
1234
1234
1234
12345678
12345678
12345678
12345678
-12345678
123456789
123456789
12345
12345

DDR Fields
10
9
L
R
L
R
L
R
L
L
L
L
L
L
L

15
15
15
15
15
15
20
20
20
20
20
12
12

Returned Value (Columns)

12345678901234567890
12.34
12.34
12.3400000
0000012.34
12.34*****
*****12.34
123,456.78
123,456.78
123,456.78*****

123,456.78
***123,456.78CR
123-45-6789
123-45-6789
Text 12-345
(Text12) 345

In the last example, the leading and trailing parenthesis are ignored.

Programmers Reference Manual

4-69

jQL

MP Code - Masked Packed Decimal

MP codes convert packed decimals to unpacked decimal representation for output or decimal values to packed
decimals for input.
Syntax
MP
Notes
The MP code most often used as an output conversion. On input, the MP processor combines pairs of 8-bit
ASCII digits into single 8-bit digits as follows:

The high order four bits of each ASCII digit are stripped off.
The low order four bits are moved into successive halves of the stored byte.
A leading zero will be added (after the minus sign if present) if the result would otherwise yield an
uneven number of halves.
Leading plus signs (+) are ignored.
Leading minus (-) signs are stored as a four-bit code (D) in the upper half of the first internal digit.

When displaying packed decimal data, you should always use an MP or MX code. Raw packed data is almost
certain to contain control codes that will upset the operation of most terminals and printers.
Input Conversion
Input conversion is valid. Generally, for selection processing you should specify MP codes in field 7 of the data
definition record.
Examples
OCONV -1234 MP
yields 0x D01234
ICONV

0x D01234 MP

yields -01234

jQL

4-70

Programmers

Reference

Manual

MS Code - Mask Sequence

The MS code allows an alternate sort sequence to be defined for sort fields.
Syntax
MS
Notes
Use of the MS code is only relevant when used in a field 8 pre-process code and applied to a field that is
specified in a sort clause. In all other cases it will be ignored.
The sort sequence to be used is defined in a special record named SEQ that you must create in the ERRMSG
file. Field 1 of this record contains a sequence of ASCII characters that define the order for sorting.
Example
SEQ (defined in ERRMSG file)
001 aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyY
zZ9876543210 ,.?!;:+-*/^=()[]{}<>@#$%&`~\|
INV.CODE (data definition record)
001 A
.
.
008 MS
SORT SALES BY INV.CODE INV.CODE ID-SUPP
SALES....
AbC789
ABC789
ABC788
dEF123

Programmers Reference Manual

4-71

jQL

MT Code - Mask Time

The MT code is used to convert time notations such as 01:40:30 or 1:30 AM between internal and external
format.
Syntax
MT{H}{S}
Syntax Elements
H specifies 12-hour format. If omitted, 24-hour format will be used.
S specifies that seconds are to be included.
Notes
Time is stored internally as the number of seconds since midnight. The stored value can be output in 12 hour or
24 hour (international) format.
12:00PM is defined as noon and 12:00AM is defined as midnight.
For output conversions, AM and PM designators are automatically displayed. For example: 09:40AM and
06:30PM.
Input Conversion
Input conversion is valid. Generally, for selection processing you should specify MT codes in field 7 of the data
definition record.
AM or PM designators are taken into account.
Examples
Input Conversion
Code

Input

MT
MTH
MT
MT
MTH
MTH
MT
MTH
MTS

00:00
12:00AM
01:00AM
01:00
01:00
01:00AM
01:00PM
01:00PM
01:00:30

Result
0
0
3600
3600
3600
3600
46800
46800
3630

Output Conversion

jQL

Code

Source Value

Result

MTS
MTHS
MT
MTH
MT
MTS
MTH
MTHS

0
0
3600
3600
46800
46800
46800
46800

00:00:00
12:00:00AM
01:00
01:00AM
13:00
13:00:00
01:00PM
01:00:00PM

4-72

Programmers

Reference

Manual

P Code - Pattern Matching

The P code returns a value if it matches one of the specified patterns. Patterns can be combinations of numeric
and alphabetic characters and literal strings.
Syntax
P{#}(element){;(element)}...
Syntax Elements
# returns null if the source matches the pattern, or the source if it does not.
element is one or more of the following:
nA

tests for n alphabetic characters

nC

tests for n alphabetic or numeric characters

nN

tests for n numeric characters

nP

tests for n printable characters

nX

tests for n characters

literal

tests for the presence of the literal.

Notes
If the value does not match any of the patterns, a null will be returned.
Input Conversion
Input conversion does not invert. It simply applies the pattern matching to the input data.
Example 1
P(2A*3N/2A)
Will match and return AA*123/BB or xy*999/zz. Will fail to match AAA*123/BB or A1*123/BB, and will
return null.
Example 1
P(2A*3N/2A);(2N-2A)
Will match and return AA*123/BB, xy*999/zz, 99-AA or 10-xx. Will fail to match AA&123/BB, A1*123/BB,
9A-AA or 101-xx, and will return null.

Programmers Reference Manual

4-73

jQL

R Code - Range Check

The R code returns a value that falls within one or more specified ranges.
Syntax
Rn,m{;n,m}...
Syntax Elements
n is the starting integer of the range. Can be positive or negative.
m is the ending integer of the range. Can be positive or negative, but must be equal to or greater than n.
Notes
If the value does not fall within the range(s), a null will be returned.
Input Conversion
Input conversion does not invert. It simply applies the range check to the input data.
Example 1
R1,10
Will return any value that is greater than or equal to 1 and less than or equal to 10.
Example 2
R-10,10
Will return any value that is greater than or equal to -10 and less than or equal to 10.
Example 3
R-100,-10
Will return any value that is greater than or equal to -100 and less than or equal to -10.

jQL

4-74

Programmers

Reference

Manual

S Code - Substitute
The S code substitutes one value for another.
Syntax
S;Var1;Var2
Syntax Elements
Var1 specifies the value to be substituted if the referenced value is not null or zero. Can be a quoted string, an
FMC (field number), or an asterisk. An asterisk indicates that the value of the referenced field should be used.
Var2 specifies the value to be substituted if the referenced value is null or zero. Can be a quoted string, an FMC
(field number), or an asterisk.
Example 1
S;*;NULL VALUE!
If the referenced field is null, this example will return the string NULL VALUE!. Otherwise it will return the
referenced value.
Example 2
S;*;3
If the referenced field is null, this example will return the content of field 3 of the data record. Otherwise it will
return the referenced value.
Example 3
S;4;5
If the referenced field is null, this example will return the content of field 5 of the data record. Otherwise it will
return the content of field 4.

Programmers Reference Manual

4-75

jQL

T Code - Text Extraction

The T code extracts a character substring from a field value.
Syntax
T{m,}n
Syntax Elements
m specifies the starting column number.
n is the number of characters to be extracted.
Notes
If m is specified, the content of field 9 of the data definition record has no effect - characters are counted and
extracted from left to right, for n characters.
If m is not specified, the content of field 9 of the data definition record will control whether n characters are
extracted from the left or the right-hand end of the value. If field 9 does not contain an R, the first n characters
will be extracted from the value. If field 9 does contain an R (right justify), the last n characters will be extracted
from the value.
Input Conversion
Input conversion does not invert. It simply applies the text extraction to the input data.
Examples

jQL

Code

Source
Value

T3,4
T3,4
T2
T3
T3

ABCDEFG
ABCDEFG
ABCDEFG
ABCDEFG
ABCDEFG

DDR
Field 9
L
R
L
R
T

Result
CDEF
CDEF
AB
EFG
ABC

4-76

Programmers

Reference

Manual

Tfile Code - Translation

Tfile codes provide a method for retrieving data fields from any other file to which the user has access.
Syntax
T[*|DICT]file-specifier;c{n};{i-fmc};{o-fmc}
Syntax Elements
* or DICT indicates that the dictionary of the specified file is to be used, rather than the data section.
file-specifier identifies the reference file by name in the format file-name{,data-section-name}.
c specifies a translation code. Can be any one of the following:
C
If reference record does not exist or the specified FMC is null, output the value unchanged.
I
Input verify. Functions as a C code for output and as a V code for input.
O
Output verify. Functions as a C code for input and as a V code for output.
V
Reference record must exist and the specified FMC must contain a translatable value. If the
record does not exist or the FMC contains a null, an error message will be output.
X
If reference record does not exist or the specified FMC is null, return a null.
n specifies a value mark count to return one specific value from a multivalued field. If omitted, all values are
returned.
i-fmc is the field number for input translation. If omitted or the value is null, no input translation takes place.
o-fmc is the field number for output translation. If the value is null, no output translation takes place.
Notes
The current data value is used as the record key for searching the specified reference file.
A data field, or a single value from a data field, is returned from the record.
Tfile codes can be used in fields 7 or 8 of the data definition record. Use field 8 if translation of a multivalued
field or comparisons and sorts are required.
If selection criteria might be applied, you can either use field 8, or you can use field 7 and set up special records
in the reference file to perform any input translation you require.
The special records in the reference file have as record keys values that the field subject to translation may be
compared with in a jQL sentence. Field i-fmc within these records contains the translate value that will be
compared to values on file. Typically, values in a jQL sentence are output values, so that the special input
translation records are effectively the inverse of the output translation records.
Tfile codes can be embedded in other conversion codes but you must still follow the syntactical conventions of
the host code. For example, if you include a Tfile code in an F code conversion, the Tfile code must be
enclosed in parentheses.
Input/Output Conversion
Output conversion is valid. The Tfile code has a parameter (o-fmc) that specifies the field in the translation
record to use for output conversion.
Input conversion is valid. The Tfile code has a parameter (i-fmc) that specifies the field in the translation record
to use for input conversion.
Example 1
TSALES;X;;2
Using this Tfile code in field 8 of a data definition record, which also has a 0 in field 2, will cause the key of the
current record to be used as the key when accessing the reference file SALES. If the record cannot be found, a
null will be returned. If the record is found, the value of field 2 will be returned.

Programmers Reference Manual

4-77

jQL

Example 2
TSALES;C;;2
Using this Tfile code in field 8 of a data definition record, which also has a 6 in field 2, will cause the content of
field 6 from the current record to be used as the key when accessing the reference file SALES. If the record
cannot be found, or if found, field 2 is null, the content of field 6 of the current record will be returned. If the
record is found, and field 2 contains a value, that value will be returned.
Example 3
A;3(TSALES;X;;2)
Using this embedded Tfile code in field 8 of a data definition record will cause field 3 of the current record to be
used as the key when accessing field 2 of the reference file SALES. If the record cannot be found a null will be
returned. If the record is found, the value of field 2 will be returned.

jQL

4-78

Programmers

Reference

Manual

U Code - User Exit

The U code is used to execute a system subroutine to process values.
Syntax
Uxxxx
Syntax Elements
xxxx is the hexadecimal identity of the routine.
Notes
jBASE user exits are customised routines specially produced to perform extraordinary processing.
Input Conversion
Routine dependent.

Programmers Reference Manual

4-79

jQL

Chapter 5: List Processing

Introduction
jBASE includes an extensive range of list processing facilities. Most are provided in the form of specialised
commands which can be used to build and maintain lists of record keys (selection lists). These commands are
available directly from the command level, others are integral parts of the various jBASE languages.
A select list can either be active or saved. A list is said to be active if it will be used to modify the effect of
the next command you issue. In jSHELL, an active list is indicated by a special system prompt (>) on the
command line.
A saved list is a list that has been written away to a file for repeated use later. Typically, when a command is
processed under an active list, the list will no longer be active when the command has been completed. You
would then need to reprocess the potentially lengthy selection again to recreate the list. By saving the list while it
is still active, you can tell the system to make it the active list as often as you need.
If you do not want to use a specific file to store the lists, the system will maintain a special area for you. In the
same way, if you do not want to use a specifically named list, the system will maintain a default list name for
you.
Lists are generally stored in a common file but are private to the generating account. This is achieved by
automatically suffixing the list names with the name of the account from which they were created.
Saved lists are static data - they will not reflect changes to the data files after they are saved. Also, saved lists can
take up significant space on the system. Regular housekeeping routines are required to ensure that you recover
the space when the lists are no longer required.

Programmers Reference Manual

5-1

List Processing

Command Level List Processing

The list processing facilities available from the command level include the SEARCH facility which looks for
specified text strings, and various Select List facilities such as FORM-LIST, GET-LIST and SORT-LIST.
Select lists are held in a special area of the database and are used to hold lists of record keys or other information
for later use by a program or command.

COPY-LIST
Copies a saved list to another list or to another file.
Syntax
COPY-LIST {from_listname} {from_accountname} {(options}
TO: {to_spec}
Syntax Elements
from_listname specifies the source list. If you do not specify from_listname, the default list will be used.
from_ accountname specifies the source account if different to the current account.
options can be one or more of the following:
O Overwrite destination list or record if it already exists.
D Delete source list after successfully copying it.
L Synonymous with S option.
N Suppresses auto paging. Only used with T.
P Sends the list to the printer.
S Suppresses line numbers. Only used with T or P.
T Sends the list to the screen.
X Outputs in hexadecimal notation. Only used with T or P.
to_spec specifies the destination list. Can be:
{to_listname} {to_accountname}
or
({DICT }to_filename {to_record_key}
Use the first variant if you want to copy the list or change the account its attached to.
Use the second variant if you want to copy the list to a data file Each key becomes a separate field in the
list record. Note use of the left parenthesis before to_filename.
If you do not specify to_spec, the list will be copied to the default list.
Example 1
: COPY-LIST A.SALES (O
TO: B.SALES
List A.SALES copied to 'B.SALES'
Copies A.SALES (a previously saved list) to B.SALES, and overwrites if necessary.
Example 2
: COPY-LIST A.SALES
TO: A.SALES ACCOUNTS
List A.SALES copied to 'A.SALES ACCOUNTS'

List Processing

5-2

Programmers Reference Manual

Copies A.SALES (a previously saved list belonging to the current account) to A.SALES, and marks it as
belonging to the ACCOUNTS account.
Example 3
: COPY-LIST A.SALES
TO: (SALES.LISTS APRIL.SALES
List A.SALES written to record 'APRIL.SALES' in file SALES.LISTS
Copies A.SALES (a previously saved list) to record APRIL.SALES, in file SALES.LISTS.

DELETE-LIST
Deletes a saved list.
Syntax
DELETE-LIST {listname {account-name}}
Syntax Elements
listname specifies the name of the list to be deleted. If you do not specify listname, the default list will be
deleted.
account-name is the name of the account from which the list was saved. If you do not specify account-name, the
current account is assumed.
Example
: DELETE-LIST A.SALES
List 'A.SALES' deleted

EDIT-LIST
Invokes an ED editor session to allow you to create, modify, merge or delete a select list.
Syntax
EDIT-LIST {list-name {account-name}} {(options}
Syntax Elements
list-name specifies the name of the list to be edited. If the list does not already exist it will be created. If you do
not specify a list name, the default list will be used.
account-name is the name of the account from which the list was saved. If you do not specify account-name, the
current account name will be used.
options can be:
ED=editor

editor is the name of the editor you want to use. Default is ED.

Notes
The EDIT-LIST command is used when you want to edit the contents of a new or existing saved list. The
command will convert the list into an editable record and pass it to the editor. When the edit session is finished,
the record will be reconverted to a list and stored under its original name.
You can specify an editor other than ED by naming the editor in the ED option.
Example
EDIT-LIST A.SALES
.jBASE.el.portnumber
TOP

Programmers Reference Manual

5-3

List Processing

FORM-LIST
Creates a select list from a record in a file.
Syntax
FORM-LIST filename record-key {(n}
Syntax Elements
filename is the name of the file which contains record-key.
record-key is the name of the record to be converted into a select list.
n is the field number in the record from which the list is to start. If n is omitted the list will start from field 1.
Notes
If you issue the FORM-LIST command without specifying a record key, you will be prompted to supply one.
The command will open file filename, read the record record-key and create a select list using each field in the
record as a separate element for the list. The list formed becomes the active select list and will be inherited by
the next jBASE command or program.
Examples
:FORM-LIST SALES.LISTS APRIL.SALES
200 records SELECTED
>LIST CUSTOMERS
A record named APRIL.SALES in file SALES.LISTS contains a list of customer keys. Each key occupies a
separate field. The FORM-LIST command generates an active list of customers. You can then issue a subsequent
command such as LIST CUSTOMERS which will use the active list .

GET-LIST
Retrieves a previously stored list from the common area and makes it the current active (default) list.
Syntax
GET-LIST {list-name {account-name}}
Syntax Elements
list-name specifies the name of the list to be retrieved. If you do not specify a list name, the default list will be
used.
account-name is the name of the account from which the list was saved. If you do not specify account-name, the
system will use the current account name.
Notes
The GET-LIST command is used to retrieve a list previously stored using the SAVE-LIST command. If the list
is retrieved successfully, it will become the current active (default) list and will be inherited by the next jBASE
command or program.
Example
:GET-LIST A.SALES
200 Records selected
>LIST SALES

List Processing

5-4

Programmers Reference Manual

Retrieves a list named A.SALES and generates an active list. You can then issue a subsequent command such as
LIST SALES which will use the active list .

LIST-LISTS
Displays a list of all select lists currently available in the common area.
Syntax
LIST-LISTS

NEW-GET-LIST
Retrieves a previously stored list from a file or the common area and makes it the current active (default) list.
Syntax
NEW-GET-LIST {file-name} list-name
Syntax Elements
file-name specifies the name of the file which contains the saved list. If you do not specify a file-name the system
will use the common area.
list-name is the name of the saved list.
Notes
The NEW-GET-LIST command is used to retrieve a list previously saved to a file using the NEW-SAVE-LIST
command. If the list is retrieved successfully, it will become the current active (default) list and will be inherited
by the next jBASE command or program.
Example
:NEW-GET-LIST SALES.LISTS APRIL.SALES
200 records selected
>LIST CUSTOMERS
Retrieves a list named APRIL.SALES from file SALES.LISTS and generates an active list. You can then issue a
subsequent command such as LIST CUSTOMERS which will use the active list .

NEW-SAVE-LIST
Saves a list to a specified file and leaves the list as the active list.
Syntax
NEW-SAVE-LIST file-name list-name
Syntax Elements
file-name specifies the name of the file which is to contain the list.
list-name is the name (key) of the saved list.
Notes
If the specified list already exists, it will be overwritten.
Example
:FORM-LIST SALES.LISTS APRIL.SALES
200 records selected
>SELECT CUSTOMERS WITH POST.CODE = MK]

Programmers Reference Manual

5-5

List Processing

40 records selected
>NEW-SAVE-LIST SALES.LISTS APRIL.SALES.MK
>LIST CUSTOMERS NAME ADDRESS (P
A record named APRIL.SALES in file SALES.LISTS contains a list of customer keys. Each key occupies a
separate field.
The FORM-LIST command generates an active list of customers. This list is then refined by using it to access
the CUSTOMER file and return only those records with a POST.CODE that starts with MK.
NEW-SAVE-LIST is then used to save the refined list to APRIL.SALES.MK in file SALES.LISTS.
The list remains active and can be used by the next command, in this case, to list the customer names and
addresses to the printer.

NEW-SORT-LIST
Sorts a list previously saved by NEW-SAVE-LIST.
Syntax
NEW-SORT-LIST file-name list-name
Syntax Elements
file-name is the name of the file which contains the saved list.
list-name is the name (key) of the saved list.
Example
>SELECT CUSTOMERS WITH POST.CODE = MK]
400 records selected
>NEW-SAVE-LIST SALES.LISTS SALES.MK
>NEW-SORT-LIST SALES.LISTS SALES.MK
:

QSELECT
Generates a select list from the fields of specified items and makes it the current active (default) list.
Syntax
QSELECT {{file-name} record-list} {(n}
Syntax Elements
file-name specifies the source file name.
record-list is a list of record keys, or an asterisk (*) to signify all records.
n is the field number in each record, from which the list is to be created. If n is not specified, all the fields in the
source records will be used to generate the list elements.
Notes
If you issue the QSELECT command without specifying an record list, you will be prompted to supply one.
QSELECT is similar to the FORM-LIST command but has the additional capability of creating a list from more
than one source record. Also, FORM-LIST creates a list from all the attributes of a single record, QSELECT can
create a list from multiple records, and you can specify that each record is only to contribute one field.

List Processing

5-6

Programmers Reference Manual

Example 1
:QSELECT SALES * (3
4000 records selected
>SAVE-LIST CUSTOMERS
Creates a list containing the values from field 3 of all the records in the SALES file. The list is then saved as
CUSTOMERS.
Example 2
:QSELECT SALES ABC DEF GHI (3
3 records selected
>SAVE-LIST CUSTOMERS
Creates a list containing the values from field 3 of records ABC, DEF and GHI in the SALES file. The list is
then saved as CUSTOMERS.

SAVE-LIST
Saves the currently active select list to a named list record.
Syntax
SAVE-LIST {list-name}
Syntax Elements
list-name specifies the name under which the list is to be stored. If you do not specify a list name, the default list
will be used
Notes
The SAVE-LIST command is used to store the currently active (default) select list under a permanent list name.
If the specified list name already exists, it will be overwritten.
Example
:SSELECT CUSTOMERS WITH POST.CODE = MK]
40 records selected
>SAVE-LIST CUSTOMERS.MK
:
Sorts and selects records from the CUSTOMER file which have a POST.CODE value that starts with MK. Saves
the list as CUSTOMERS.MK.

SEARCH Command
The SEARCH command is used to create a list of all records in a file which contain one or more text sequences.
Syntax
SEARCH filename
Fist String to search for : string
Second String to search for : string
...
Syntax Elements
filename is the name of the file to be searched.

Programmers Reference Manual

5-7

List Processing

string is the text string to search for. You will be prompted for any number of strings to search for. Press the
<ENTER> key only to finish entering search strings.
Notes
The SEARCH command will scan the file specified by filename looking for records which contain the specified
text string(s). If it finds any records that match the criteria, it will create a select list containing the record keys.
This list then becomes the default select list and will be inherited by the next jBASE command or program.

SORT-LIST
Sorts a saved select list.
Syntax
SORT-LIST {list-name{account-name}}
Syntax Elements
list-name specifies the name under which the list is to be stored.
account-name is the name of the account from which the list was saved. If you do not specify account-name, the
system will use the current account name.
Notes
The SORT-LIST command will sort a list previously saved with the SAVE-LIST command.
SORT-LIST is useful for sorting lists which have modified by EDIT-LIST, or for avoiding an extra SSELECT
when working with a large file.
Example
:SELECT CUSTOMERS
4000 records selected
>SAVE-LIST CUSTOMERS.MK
:SORT-LIST CUSTOMERS.MK
Selects records from the CUSTOMER file which have a POST.CODE value that starts with MK. Saves the list
as CUSTOMERS.MK and then sorts it using the SORT-LIST command.

XSELECT
Generates a select list (or display) of all keys in a file which do not match given selection criteria.
Syntax
XSELECT file-name
Syntax Elements
file-name specifies the name of the file to be searched.
Notes
If you issue the XSELECT command while a select list is active, the process will return with a list of all the
records in the file which are not in the active list.
If you issue the XSELECT command without an active select list, you will be prompted initially for the name of
a saved list to use. If you supply a list name the process will return with a list of all the records in the file which
are not in the named list. If you do not supply a list name but press <RETURN> to this prompt, you will be
asked to supply selection criteria (in normal jQL format) which will identify all the records in the file that you do
not want in the returned list.

List Processing

5-8

Programmers Reference Manual

In all cases, providing the returned list contains one or more record keys, you will be asked for a new name to
save the list to. If you do not supply a list name but only press <RETURN> to this prompt, the list of record keys
will be displayed on the terminal screen.
Example 1
:GET-LIST CUSTOMERS.MK
>XSELECT CUSTOMERS
Input save list name: CUSTOMERS.NOT.MK
GET-LIST makes the CUSTOMERS.MK list active. XSELECT then creates a list of all the records in the
CUSTOMERS file which are not in the active list, and save it as CUSTOMERS.NOT.MK.
Example 2
:XSELECT CUSTOMERS
Input list name: CUSTOMERS.MK
Input save list name: CUSTOMERS.NOT.MK
XSELECT first prompts for the name of a list to use. It then creates a list of all the records in the CUSTOMERS
file which are not in the specified list, and save the new list as CUSTOMERS.NOT.MK.
Example 3
:XSELECT CUSTOMERS
Input list name: <RETURN>
Input selection criteria: WITH POST.CODE = MK]
Input save list name: CUSTOMERS.NOT.MK
XSELECT first prompts for the name of a list to use. Because a list name is not supplied, it prompts for the antiselection criteria to use. A list is then created which contains all the keys of the CUSTOMERS file where the
records do not match the selection criteria. The new list is saved as CUSTOMERS.NOT.MK.

Programmers Reference Manual

5-9

List Processing

jBC List Processing

The two main jBC list processing statements are READLIST and WRITELIST. However, if there is a currently
active (default) list outstanding when you start a jBC program, you can also use the READNEXT command to
extract elements from the external list.
See the jBC chapter for more details.

List Processing

5-10

Programmers Reference Manual

jCL List Processing

The two list processing commands which are used with jCL programs are PQ-SELECT and PQ-RESELECT.
See the jCL chapter for more details.

Programmers Reference Manual

5-11

List Processing

jQL List Processing

The four list processing commands which follow jQL command syntax are BSELECT, ESEARCH, SELECT
and SSELECT. See the jQL chapter for more details.

List Processing

5-12

Programmers Reference Manual

Chapter 6: jBASE Editors

jBASE Editors
jBASE is supplied with its own fully featured screen editor that can be used for creating, modifying, or deleting
records. The jED editor has been designed for ease of use, easy personal configuration and is especially suited to
the editing of jBC programs.
jBASE also provides a limited version of an ED editor to enable the easy transition of users who are only
familiar with the old style line editors.
The first part of this chapter describes the screen editor jED, and the second part describes ED, the line editor.

Programmers Reference Manual

6-1

jBASE Editors

jED Editor
The jED editor is a full screen, context sensitive, screen editor. It has been specifically designed so that users
will find it easy to learn and use and is the preferred editing tool for the jBASE operating environment.
The features provided in jED will be familiar to users of many other editors. It incorporates many powerful
facilities for manipulating text and data, and contains all the features that programmers have come to expect of a
good editor.
jED has full screen access to jBASE file records and UNIX files - a feature which is not provided by other
editors.
The command keystrokes are fully configurable by each user, as is the keyboard. jED can therefore be
customised to mimic many operations of other editors and provide a familiar environment for new users.
Keyboard and command independence make jED the most versatile and powerful editing tool available for all
jBASE editing requirements.

Editor Screen
A typical jED editor session might look like this:
*File PROGS, Record cust_rep.b
Insert
10:45:55
Command->
001
002
003
-----------------End of Record--------------------------------------

The screen is divided into three sections; the editor status line at the top, followed by the command line and then
the data editing area which fills the rest of the screen.

Invoking jED
Call the jED editor from the UNIX command line.
Syntax
jed pathname {pathname..}
jed {DICT} filename{,filesection} {record-list} {(options)}}
If you simply issue the command jed, the editor will open the last file that was used, and the cursor will be
positioned wherever it was when the last edit session was closed. In other words, you can carry on from exactly
where you left off.
The command, jed pathname, will either open an existing file or create a new one if the file referenced by
pathname does not exist. The will contents of the file will be displayed in the edit window. If you specify a list
files, the editor will present the next file as you finish with each one.
When the editor is supplied with the name of a file resident in a database (such as a j-file), it scans the rest of the
command line looking for a list of records keys. If no record keys were specified, the jED editor will prompt for
a list. Otherwise the list of record keys will be edited one after the other.
Note that because the editor uses the jEDI interface to access the records, it can be used to edit records in any
file system that jEDI recognises.

jBASE Editors

6-2

Programmers

Reference

Manual

Command Elements for Database Resident Files

DICT

This modifier is only required if you wish to edit records in the DICTionary of a j-file.

filename

This is the name of the "file" containing the records.

filesection

This is the file section name, as used in a j-file.

record-list

It is possible to furnish a list of records to be successively edited. This can be a list of

records separated by a space, or \* to indicate all records in the file. Note that the \ is the
shell escape character to stop the * being treated as a wild card that would otherwise be
expanded.
Additionally, the record-list can be fed to this command by preceding the jed command
with a jBASE list generating command such as SELECT or SSELECT. In this case, the
record-list is ignored.

Command Line Options

Options available when executing the jed command are as follows:
Bnn{,mm} Performs automatic indentation on the record to be edited. This will be of use when creating jBC
programs.
The nn parameter specifies the number of spaces to indent by for each indentation level (default is 4
spaces).
The optional mm parameter is the number of times the nn indent value should be applied at the start
of each line. If mm is 2 and nn is 3, each line will be indented initially by 6 spaces and each
subsequent indent level will be 3 further spaces.
E

Uses the default keyboard command set-up at installation, rather than that which may have been set
up exclusively for the port.

Does not lock the file or record being edited. This allows simultaneous edit access from elsewhere.

Allows READ ONLY access to the record or file.

Tnn

Sets tab stops every nn spaces for use within the editor.

Examples
jed test.b
Opens the test.b file for editing, initially in insert mode with automatic indentation turned on. If the file does not
exist, it is created and the text New Record is shown at the top of the screen.
jed test.b (B5,2
The jBC program test.b is edited with automatic indentation set. The initial indent is set at 10 spaces for all lines,
and each additional indentation level is set at 5 spaces.
jed invoices.b subs.c
The jBC program invoices.b will be edited, followed by the 'C' program subs.c.
jed BP menu1.b menu1.1.b
The jBASE file records menu1.b and menu1.1.b are successively edited. Record locks are taken on the records
as they are edited to prevent multiple edits on the same record.
JED ORDERS 0012753 0032779 (R
The records 0012753 and 0032779 from the file ORDERS will be successively edited in read-only mode.
:SSELECT ORDERS WITH CUST.NAME = "UPA"
>JED ORDERS
The orders of the customer UPA will be successively edited in sorted order. Record locks will be automatically
set during the editing period to prevent simultaneous updates by other users.
jed -F BP \*

Programmers Reference Manual

6-3

jBASE Editors

All the records in the jBASE file BP are set up to be edited one after the other. Note the use of the shell escape
character (\) before the *.
jed -F BP STXFER.b \(T10
The record STXFER.b in file BP is opened for editing. A tab stop is set at column 10 for use in this session.

Using the jED Editor

The jED editor is used in two different modes:
Command mode for entering editor commands, and
Edit mode for entering or modifying data.
The current mode is displayed at the top of the screen.
Command Mode
When the editor is invoked, the record or text file is displayed, and the user is placed in input mode with the
cursor at the input position.
To change to command mode simply press the <ESC> key on the keyboard.
The cursor now moves to the top portion of the screen and the editor awaits input of a command. Once a valid
command has been executed, control passes back to the Edit mode if appropriate.
Edit Mode
Edit mode is used when entering or modify data. This is the default mode for an editor session.
Keyboard control sequences are available to perform a variety of functions such as cursor positioning, scrolling
and marking text for a subsequent action.
Some command line operations are also available from keyboard control sequences.

Keyboard Personalisation
The jED editor allows a considerable number of functions and commands to be performed whilst in edit mode,
mostly by combining the <CTRL> key and one other key.
Most keys have a default value (which can be reset using the E option when invoking jED). These can be
reconfigured for each command. The keystroke sequence can be chosen to suit the keyboard, the installation
environment or personal preference.
The keystroke environment is usually be set up by modifying the UNIX terminfo file parameters. This is
described in more detail later in the chapter.
jED Default Key Commands
The default keystroke sequences available from jED are shown below. If the system administrator has
reconfigured these for a particular port, they can be re-assigned by using the E option when starting a jED
session. The execution of a command is relative to the current cursor position.
<F1>

Scrolls the screen up one line.

<F2>

Scrolls the screen down one line.

<F3>

Scrolls the screen up half a page.

<F4>

Scrolls the screen down half a page.

<F5>

Scrolls the screen up one page.

<F6>

Scrolls the screen down one page.

<F7>

Displays the first page of the record or file.

<F8>

Displays the last page of the record or file.

jBASE Editors

6-4

Programmers

Reference

Manual

<F9>

Pressing <F9> when the cursor is positioned on a line of source code that begins a structured
statement (IF, BEGIN CASE etc.), will cause the editor to locate the closing statement for the
structure. If the cursor line is an IF statement then the editor will attempt to find the END
statement that closes this structure. If there is no matching END statement then the editor will
display a message to this effect.

<F10>

The <F10> key is complement of the <F9> key. Therefore if the cursor is positioned on an
END statement, then the editor will attempt to find the start of the structure that it is currently
terminating. If the END has been orphaned (it matches no structure), then the editor will
display a message to this effect.

<CTRL A>

Moves cursor to start of the current line.

<CTRL E>

Moves the cursor to the end of the current line.

Moves the cursor one character position to the left.

Moves the cursor one character position to the right.

Moves the cursor to the previous line.

Moves the cursor to the following line.

<TAB>

Moves the cursor to the start of the next tab position on the line.

<SHIFT TAB>

Moves the cursor to the previous tab position on the line.

<ESC>

Moves the cursor to the COMMAND LINE.

<CTRL W>

Deletes from the cursor to the end of the word, including the following whitespace
characters.

<CTRL K>

Clears text to the end of the line. If the cursor is situated at the end of the text line, then this
command will join the following line with the current line.

<BACKSPACE> Performs a destructive backspace.

<DEL>

Deletes the character under the current cursor position.

<CTRL D>

Deletes the current line.

<CTRL G>

Sets the start or end position for marking a block of text. The first <CTRL G> will mark the
start of a block or mark a single line the second <CTRL G> with the cursor on a different line
will mark a complete block. The block can be unmarked by pressing <CTRL G> a third time.

<CTRL L>

Inserts a blank line below the current line and positions the cursor on it.

<CTRL N>

Locates the next occurrence of a previously located string.

<CTRL O>

Toggles between the Overwrite and Insert data entry modes.

<CTRL R>

Redisplays the screen and discards the most recent updates (since the last carriage return).

<CTRL T>

Changes the case of the alphabetic character beneath the cursor.

<CTRL V>

Performs jBC program indentations on the current screen window.

<CTRL X>

Exits the current record without writing away any updates. If the record has been changed
within the current editing session then the editor will ask for confirmation to exit the
modified record.

<CTRL ]>

Inserts the field value delimiter character.

<CTRL \>

Inserts the field sub-value delimiter character.

<RETURN>

Opens a new line. Any characters on the current line after the current cursor position are
moved to the start of the new line.

Programmers Reference Manual

6-5

jBASE Editors

Command Line Operations

To enter the command line from the jED edit mode, press the <ESC> key, or one that has been reconfigured to
perform the same action.

Leaving the Editor

There are several options available for exiting a file or record being edited. It can be deleted, stored in its latest
form, keeping all the changes made in the current editing session, or it can be stored as it existed before the edit
session began.
Abandon Edit and Start New Session
The E command will abandon the current edit (you will be asked to verify leaving a changed record) and edit the
specified record(s).
The command syntax is as follows:
E unixfile
E filename record
If the form filename record is used, then the filename should be the name of a jBASE file. You can also specify
the pathname of a standard UNIX file with the unixfile form. Note that wildcard characters such as asterisk (*)
are not expanded by the E command, and that you must the jBASE file name again, even if you are currently
editing a record from within that file.
Delete File or Record
The command syntax is as follows:
FD {options}
options can be K, T and/or O. See the Command Options topic for details.
This command deletes the file or record and releases any lock set. Before it does so, the user is prompted for
confirmation. The edit session then terminates, or continues with the next record if this choice is in effect.
Exit and Update
The command syntax is as follows:
FI {options} {unixcommand}
FI writes the updated version of the file or record back to disk and releases any lock set. The edit session then
terminates, or continues with the next record, if this choice is in effect.
options are B, K, R and T. See the Command Options topic for details.
unixcommand specifies a UNIX command to ,be executed on exiting the editor.
Exit and Discard
The command syntax is as follows:
EX {options}
EX leaves the file or record as it was at the start of the session, and releases any lock set. If updates have been
made you will be prompted for confirmation before the updates are discarded. The edit session then terminates,
or continues with the next record, if this choice is in effect.
options are K, T and O. See the Command Options topic for details.
Update without Exit
The command syntax is as follows:
FS {options} {unixcommand}
jBASE Editors

6-6

Programmers

Reference

Manual

This command writes the updated file or record to disk, then returns to the editing session at the point where it
left off.
options are B and R. See the Command Options topic for details.
unixcommand specifies a UNIX command to ,be executed on exiting the editor.
Command Options
R specifies that, after the file has been written to disk, it should be executed. Additional parameters can be added
to this option and passed to the program. The editor issues the command filename {parameters} to execute the
program. Note that the .b suffix is removed.
K or T option specifies that if the editor was working from a list of records, the list should be discarded and that
the editor should exit directly to the shell (or to the calling process).
O specifies that the confirmation request normally issued with the FD and EX commands should be suppressed.
The R option is particularly useful to jBC programmers.
Examples
FIK
Exits the record and writes it to disk. If in the middle of a list of records being edited, the list is abandoned and
the editing session is terminated.
FDO
Delete the current record being edited. The normal confirmation of this action is not given.

Locating Strings
The editor allows the user to search and locate any string held in the body of the text being edited.
There is also a keystroke command sequence (default <CTRL N>) to allow the user to find the next occurrence
of the string used in the previous locate command.
The locate command syntax is as follows:
L{nnn}dstring{doption}
nnn is the numeric value of the number of lines to search from the cursor position. If omitted, the search
continues to the end of the file or record. If this optional parameter has been specified then all occurrences of the
string will be located over the specified number of lines. If only a single occurrence is found then the cursor is
placed at this point in the file. If multiple occurrences of the string are found then each one is listed below the
editing screen.
d is the delimiter used to enclose the string to be located. It can be any character that does not form part of the
string.
string is the string to locate.
option can be one or more of the following:
F specifies that the search is to begin at the start of the file or record.
C performs a case insensitive search. Otherwise the search defaults to match the cases as provided in the
string.
Examples
L/report
Searches the record from the current position for the string 'report' and halts at the first occurrence found, with
the cursor at the start.
L9 FORM

Programmers Reference Manual

6-7

jBASE Editors

Search the next 9 lines and locate all occurrences of the string 'FORM'.
L/STARS/F
Searches from the first line of the file to find the first occurrence of the string 'STARS'. This line is placed at the
top of the screen.
L/stock/C
Locates the first occurrence of the string 'stock' with the letters in upper or lower case.

Replacing Strings
The editor allows the user to replace any occurrence of a string on any line with another from the command line.
This is in addition to the overwrite mode.
The command syntax is as follows:
R{U}{nnn}dstring1dstring2{doption}
U replaces ALL occurrences of string1 with string2 on the current line only.
nnn is a numeric value for the number of lines, starting from the current one, over which to perform the replace
operation. If this optional parameter is specified and more than a single occurrence of string1 is found then all
replacements are listed beneath the current editing screen.
d is the delimiter character used to separate the string values. It can be any character not in either of the strings.
string1 is the string that is to be replaced.
string2 is the replacement string. This can be shorter or longer than the original.
option can be one or more of the following:
F

executes the replace command from the first line of the file or record.

replaces ALL occurrences of string1 with string2 on the current line.

nnn

numeric value for the number of times to repeat the replace operation on the current line.

Examples
R/ABC/DEF
Replaces the first occurrence (reading from the left) of ABC in the current line with DEF.
R9/*/!
Replace on the next 9 lines, the first occurrence on the line of '*' with a '!'. The changed lines are displayed
before moving on.
RU9/*/!
Replace any occurrence of '*' with '!' over 9 lines (the current line and the next 8).
R999//*/F
Place a '*' character at the start of every line starting from the first. All lines changed are shown before returning
to the original line.
R/^/AM/*
All occurrences of the '^' character on the line are replaced with 'AM'.
R9/*//
Removes (replaces with null) the first occurrence of '*' on the next 9 lines.
R/x//10
Removes the first 10 'x' characters on the current line.

jBASE Editors

6-8

Programmers

Reference

Manual

Copying, Pasting and Cutting Blocks of Text

The editor allows the user to copy or move blocks of text from one location to another within the current record
being edited. It is also possible to copy from another UNIX file or jBASE record.
Before a block can be moved or copied, it has to be marked or highlighted. Marked lines have their line numbers
replaced by the characters ++++.
Marking Text
Text can be marked whilst in edit mode by using the appropriate keystroke command (default <CTRL G>) to
mark the start and end of the block.
To highlight a block, move the cursor to the first line to be highlighted and press <CTRL G> (or the reassigned
ones). Then move the cursor to the last line to be highlighted and again press the <CTRL G>. The start and end
lines can be marked in any order.
To cancel the marked text, simply press <CTRL G> again, which will remove the markers.
Once the text is marked the cursor should be positioned on the line to which the text is to be copied or moved
before invoking the command line or key sequence required.
Copying Marked Text
Once marked, text can be copied by moving the cursor to the target line, entering command mode, then using the
copy commands provided. To copy text to the line before the current one, use the CB command. To copy to the
line following the current one, use the CA command.
The syntax for both commands is the same:
CB{nn}
CA{nn}
The optional nn parameter is a numeric value that gives the number of copies of the marked text to transfer. This
is particularly useful for the creation of a large quantity of repetitive text.
Moving Highlighted Text
Commands used to move highlighted text are MB to move to the line before the current one, and MA to move to
the line following the current one.
The syntax for both commands is the same:
MB
MA
The text will be physically deleted from the original position. It is not valid to move text within the highlighted
block.
Merging Text from Another Record
Using the jED editor it is possible to merge data from any file or record into the current one.
The command to achieve this is:
MERGE
This is achieved by the following command sequence:
1. Position the cursor one line above the desired position of the merged text.
1. Spawn a new editor session using the ! command (detailed later). For example, !jed record, or any
other valid jed syntax. This will execute another editing session, placing the current one in the
background.
1. Mark the block of text you wish to merge, then from the command line, issue the MERGE command.

Programmers Reference Manual

6-9

jBASE Editors

1. The newly spawned editing session will be exited and control will be passed back to the original edit
session. The merged text will then be copied into the record before the current line.
Deleting Marked Text
The command DB deletes the marked text. The position of the cursor or portion of the record being displayed
has no effect on the action.

jBC Line Indentation

The jED editor has the capability of formatting lines of jBC program code with appropriate indentation and so
make it more readable. The commands available and their syntax are described below.
BI{nn}
Formats the entire record as jBC code by adding indentations in appropriate places. The value nn gives the
number of space characters per indentation (maximum 20), and defaults to 3 if omitted.
BION{nn}
Turns on the automatic indentation for jBC source code. Equivalent to using the B option with the jed command.
The value nn gives the number of space characters per indentation, and defaults to the value used with the B
option, or the value used in the last BI command.
BIONA{nn}
This command is the same as the BION command, except that an alternative form of indentation is used for the
CASE statement. It is equivalent to using the A option with the jed command when opening an editing session.
BIOF{F}
Turns off the automatic indentation for jBC source code. It is equivalent to not using an indent option when
opening an editing session.

Miscellaneous Commands
DE{nnn}

Deletes the number of lines specified by nnn, starting from the current cursor position. If nnn is
omitted it defaults to a value of one line.

?S or S?

Displays the size of the record being edited in bytes. It includes field delimiter marks in the body
of the record.

!{command}

Executes command. Can be any valid UNIX or jBASE command.

!!

Re-executes the command specified in the most recent ! command executed.

U{nn}

Scrolls the screen up by nn lines. If omitted, nn defaults to one line.

D{nn}

Scrolls the screen down by nn lines. If omitted, nn defaults to one line.

I{nn}

Inserts nn blank lines after the line holding the cursor. If omitted, nn defaults to one line.

nn

Positions the cursor on line nn, which is positioned at the top of the screen if the number of
remaining lines still allows a screens worth of data to be displayed.

IN

Equivalent to the <F10> key.

IP

Equivalent to the <F9> key.

Displays the main help screen menu.

jBASE Editors

6-10

Programmers

Reference

Manual

Changing jED Command Keys

The keystrokes used for jED editor commands are configured using the UNIX terminfo terminal characteristic
database.
Terminfo for Altering jED Keystrokes
Terminfo is a UNIX database that describes the capabilities of terminals and their keyboards. Terminal
capabilities are defined for how operations are performed, any padding requirements, and the initialisation
sequences required for each function. The terminfo system is comprehensively documented within the standard
UNIX documentation.
The terminfo data is used by utilities such as vi and jED to allow them to work on entirely different terminals
without needing to set up or change parameters for each one.
The terminfo data can usually be found in the /usr/lib/terminfo directory.
Terminfo entries consist of a number of fields delimited by a comma. Embedded whitespace characters are
ignored.
The first line of each description gives one or more names (separated by a | character) by which the terminal is
known. Names should not contain space characters and at least the first 14 characters should be unique. The first
name in the list is normally the shortest and is used when defining the terminal to UNIX, e.g. in setting the
TERM environment variable.
The terminal name is followed by a list of capabilities that describe the functionality available with it.
There are three types of terminfo definitions:
Booleans to indicate what features of the terminfo system the particular terminal supports such as:
margin; colour; erase; tabs.
Numerics to indicate magnitudes such as numbers of columns per line, numbers of lines in the display.
Strings For example, cursor, italics, carriage return, keyboard definitions.
The jED editor is affected mainly by the definitions of key strokes in the strings section. If the terminfo
definition for your terminal does not define the keyboard sequences for the jED editor (F1 - F10 keys, Cursor
keys, etc.), you may change the definition yourself like this:
TERM=myterm ; export TERM
infocmp >termdef.myterm
vi termdef.myterm
........add the new keystrokes and write back the new record
tic termdef.myterm
Note that on many systems you will need to have superuser permissions to execute the tic command.
Although terminfo is documented extensively it can become quite complex. JAC would be pleased to help you to
define terminfo entries for terminals. However, in most circumstances, the jkeys program described below will
provide all functionality required.
jkeys
The jkeys program provides a method of defining keystrokes for terminfo databases. It is invoked by typing
jkeys at the shell prompt.
The jkeys menu allows you to list the terminfo string names and define values for them. Option 2 from the menu
will ask for the name of a terminal (which must exist in the terminfo database), to use as the basis for your new
definition. The program will then allow the definition of any or all keyboard sequences for the terminfo entry.
When you have specified a parameter to be changed a countdown timer will be displayed and you will prompted
to hit the key (or keys) sequence that you wish to be stored in the database for this sequence. You may continue
to define as many terminfo strings as you wish. When you have finished defining keyboard strings you should
type in .q to leave the definition screen.

Programmers Reference Manual

6-11

jBASE Editors

To file the changed definition in the database you should enter .X to exit the program. You will be prompted to
enter a name for the terminfo definition you have configured. You may overwrite an existing entry or choose a
new name for a personalised keyboard. The jkeys program will then file your definition in the terminfo database.

jBASE Editors

6-12

Programmers

Reference

Manual

ED Editor
The ED editor provided with jBASE is a limited version of the familiar (but now superseded) ED editors.
You are strongly advised to use the jED editor in preference to ED - so strongly that we have not included any
operating instructions here for the ED editor.
If you are only familiar with the old style ED editor, by all means continue to use it in your accustomed fashion but please find a few minutes to review the operation of jED. You will find that the transition from ED to jED is
very simple and you will be amply rewarded by adopting the much more efficient and friendly environment
provided by jED.

Programmers Reference Manual

6-13

jBASE Editors

Chapter 7: jBASE Commands

jBASE Commands
The following lists detail all the jBASE commands and indicate where they are documented.

Account Management
These commands are documented in the Maintenance chapter of the System Administrators Manual:
ACCOUNT-RESTORE

ACCOUNT-SAVE

Editing
These commands are documented in the Editors chapter of the Programmers Reference Manual:
ED

EDIT

JED

File Management and Searching

These commands are documented in the File Management chapter of the System Administrators Manual:
CLEAR
CLEAR-FILE
COPY
CREATE-FILE

DELETE
DELETE-FILE
jchmod
jrf

jgrep
jstat
SEL-RESTORE

General
These commands are documented in the General Utilities chapter of the System Administrators Manual:
ADDD
ADDX
BKOFF
BKON
BREAK-KEY-ENABLE
BREAK-KEY-OFF
BREAK-KEY-ON
CP
CT
DATE-FORMAT
DIVD
DIVX

DTX
ECHO
ECHO-OFF
ECHO-ON
ENABLE-BREAK-KEY
HUSH
LISTDICTS
LISTF
LISTU
LOGOFF
MSG
MULD

MULX
NOHUSH
OFF
SLEEP
SUBD
SUBX
TERM
TERMINAL
TIME
WHERE
WHO
XTD

Internationalisation
These commands are documented in the Internationalisation and General Utilities chapters of the System
Administrators Manual:
DATE-FORMAT
SET-DEC

SET-LANG
SET-MONEY

SET-THOU

jBC
These commands are documented in the jBC chapter of the Programmers Reference Manual:
BASIC
CATALOG

DECATALOG
DELETE-CATALOG

RUN

jBTP
These commands are documented in the jBTP chapter of the System Administrators Manual:
LIST-JOB
PH-ALLOCATE
PH-CLEAR
PH-DELETE
PH-KILL

Programmers Reference Manual

PH-LINES
PH-RESUME
PH-START
PH-STATUS
PH-SUSPEND

STARTSCHED
STOPSCHED
Z
ZH

7-1

jBASE Commands

jCL
These commands are documented in the jCL chapter of the Programmers Reference Manual:
PQ-RESELECT

PQ-SELECT

jQL
These commands are documented in the jQL chapter of the Programmers Reference Manual:
BSELECT
COUNT
EDELETE
ESEARCH
LIST

LISTDICT
LIST-LABEL
REFORMAT
SELECT
SORT

SORT-LABEL
SREFORMAT
SSELECT

These commands use the jQL command syntax but are documented in the Tape Operations chapter of the
System Administrators Reference Manual:
T-DUMP

T-LOAD

jLP Spooler
These commands are documented in the jLP Spooler chapter of the System Administrators Manual:
:REST-SPOOLER
:SP-NEWTAB
LISTPEQS
LISTPTR
PORT-DESPOOL
SP-ALIGN
SP-ASSIGN
SP-CLEAR
SP-CLOSE
SP-COPIES
SP-CREATE
SP-DELETE

SP-DEVICE
SP-EDIT
SP-EJECT
SP-FORM
SP-FQDELETE
SP-JOBS
SP-KILL
SP-LOOK
SP-MOVEQ
SP-OPEN
SP-OPTS
SP-PRIORITY

SP-PURGEQ
SP-RESUME
SP-SKIP
SP-STATUS
SP-STOP
SP-SUSPEND
SP-SWITCH
SP-TAPEOUT
SP-TRANSLATE
SP-TYPE

List Processing
These commands are documented in the List Processing chapter of the Programmers Reference Manual:
COPY-LIST
DELETE-LIST
EDIT-LIST
FORM-LIST
GET-LIST

LIST-LISTS
NEW-GET-LIST
NEW-SAVE-LIST
NEW-SORT-LIST
QSELECT

SAVE-LIST
SEARCH
SORT-LIST
XSELECT

These statements are documented in the jBC chapter of the Programmers Reference Manual:
READLIST

READNEXT

WRITELIST

These commands are documented in the jCL chapter of the Programmers Reference Manual:
PQ-RESELECT

PQ-SELECT

These commands are documented in the jQL chapter of the Programmers Reference Manual:
BSELECT
ESEARCH

SELECT
SSELECT

Migration
This command is documented in the Migration chapter of the Programmers Reference Manual. See also the
Advanced Migration chapter of the Advanced Programmers Reference Manual:

jBASE Commands

7-2

Programmers Reference Manual

PORTBAS

System Housekeeping and Tuning

These commands are documented in the Configuration and Maintenance chapters of the System Administrators
Manual:
jbackup
jbcconnect

jPML
JRLA

jrestore
jspprint

Tape Operation
These commands are documented in the Tape Operations chapter of the System Administrators Manual:
T-ATT
T-BCK
T-CHK
T-DET
T-DUMP

Programmers Reference Manual

T-ERASE
T-FWD
T-LOAD
T-RDLBL
T-READ

T-RETENSION
T-REW
T-STATUS
T-UNLOAD
T-WEOF

7-3

jBASE Commands

Chapter 8: Environment Variables

Introduction
jBASE uses a number of environment variables to modify jBASE behaviour. Suitable defaults apply to most of
them. The only variables that must be set are the PATH and LD_LIBRARY_PATH (LIBPATH on AIX) - as
explained in the Configuring jBASE Users topic of the Configuration chapter in the System Administrators
Manual.
Although most environment variables can be set any time, the best place to do it is in the .profile script.
The list below shows all possible environment variables, how they are set, what the defaults are and so on.

Variable: JBASETMP
Description: jBASE programs make use of a work file for various internal processes such as passing STOP
codes to calling programs, SAVE-LISTs, etc. The name of the work file can be changed by
modifying this environment variable. Note though that this variable is provided for JAC support
purposes and is unlikely to need changing by the programmer.
Values:

Valid file path.

Default:

$JBCRELEASEDIR/tmp/jBASEWORK

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBASETMP=/home/alternative/workfile
export JBASETMP

Variable: JBC_ENDRESTART
Description: Enables the Break/End Restart feature.
Values:

Restart Program.

Default:

Break/End Restart feature disabled.

Setting:

Create the JBC_ENDRESTART environment variable in the .profile before the jbcconnect
program is executed. The environment variable should contain the UNIX command string to
execute when the debugger is entered/exited.
To later enable the feature, use the BITSET(-3). To later disable the feature, use the BITRESET(3).

Variable: JBC_TCLRESTART
Description: Enables the Command Level Restart feature.
Values:

Restart Program.

Default:

Command Level Restart feature disabled.

Setting:

Create the JBC_TCLRESTART environment variable in the .profile before the jbcconnect is
executed. The environment variable should contain the UNIX command string to execute when the
user would otherwise go to a shell prompt.
To later enable the feature, use the BITSET(-2). To later disable the feature, use the BITRESET(2).

Programmers Reference Manual

8-1

Environment Variables

Deleted: .

Variable: JBCDEFDICTS
Description: When importing legacy applications, this variable tells the compiler what system it originally ran
on. Note that programs and subroutines imported from different systems may be freely mixed.
Values:

Colon separated file paths.

Default:

None

Setting:

Normal UNIX environment variable. Can be set at any time by the commands:
JBCDEFDICTS=path:path
export JBCDEFDICTS

Variable: JBCEMULATE
Description: When importing legacy applications, this variable tells the compiler what system it originally ran
on. Note that programs and subroutines imported from different systems may be freely mixed.
Values:

ROS, R83, PRI, ULT, ADS, FUJ, UNV, UND, AP

Default:

The default is R83, which will suit most imported applications.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands:
JBCEMULATE=Value
export JBCEMULATE

Variable: JBCERRFILE
Description: Default error messages are held in the file $JBCRELEASEDIR/jbcmessages. This may be
overridden by the JBCERRFILE variable - only useful if you wish to customise the error messages
for your own application.
Values:

Valid file path.

Default:

$JBCRELEASEDIR/jbcmessages

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCERRFILE=/home/alternative/errmsgfile
export JBCERRFILE

Variable: JBCGLOBALDIR
Description: Defines the global directory for the jBASE system locks. Config file for jPML, jRLA, jBTP,
jBASEWORK, tape device status.
Values:

Valid file path.

Default:

/usr/jbc

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCGLOBALDIR=/usr/jbc
export JBCGLOBALDIR

Environment Variables
Manual

8-2

Programmers

Reference

Variable: JBCIDLEN
Description: Sets the display column length for record keys when using the jQL language. On older systems this
was defined by field 10 of the file definition record (D-pointer) in the MD and had a default value
of 14.
Values:

Decimal number

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCIDLEN=10
export JBCIDLEN

Variable: JBCLOGNAME
Description: The account name as perceived by commands such as WHO or conversions such as U50BB will
normally be returned as the login name of the UNIX user (LOGNAME variable). However, if you
want users to login with personal id's but execute as if they were all on the same account you can
set this variable to override the default. The account name will be returned from this environment
variable.
Values:

Any character string.

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCLOGNAME=PAYROLL
export JBCLOGNAME

Variable: JBCOBJECTLIST
Description: Defines the directory in which user shared object libraries of user subroutines are located.
Values:

Colon separated file paths.

Default:

$HOME/lib.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCOBJECTLIST=$HOME/lib:$ANOTHERHOME/lib
export JBCOBJECTLIST

Variable: JBCPORTNO
Description: Defines your current port number. Can be very useful when particular users need to keep the same
port number whenever they log on. It takes a sensible default defined by UNIX, but note that this
default may change if you modify the UNIX configuration.
Values:

Decimal port number.

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCPORTNO=1000
export JBCPORTNO

Programmers Reference Manual

8-3

Environment Variables

Variable: JBCPRINTER_DEPTH
Description: Specifies page depth for paged spooler output. Overrides the value specified by the TERM type.
Values:

Decimal number

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCPRINTER_DEPTH=112
export JBCPRINTER_DEPTH

Variable: JBCPRINTER_WIDTH
Description: Specifies page width for paged spooler output. Overrides the value specified by the TERM type.
Values:

Decimal number

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCPRINTER_WIDTH=112
export JBCPRINTER_WIDTH

Variable: JBCRELEASEDIR
Description: Defines the release directory for jBASE system executables and libraries.
Values:

Valid file path.

Default:

/usr/jbc.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCRELEASEDIR=/usr/jbc
export JBCRELEASEDIR

Variable: JBCSCREEN_DEPTH
Description: Specifies page depth for paged terminal output. Overrides the value specified by the TERM type.
Values:

Decimal number

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCSCREEN_DEPTH=10
export JBCSCREEN_DEPTH

Variable: JBCSCREEN_WIDTH
Description: Specifies page width for paged terminal output. Overrides the value specified by the TERM type.
Values:

Decimal number

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCSCREEN_WIDTH=132
export JBCSCREEN_WIDTH

Environment Variables
Manual

8-4

Programmers

Reference

Variable: JBCSPOOLDIR
Description: Defines the directory which contains the jBASE spooler entries.
Values:

Valid file path.

Default:

/usr/jspooler.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCSPOOLERDIR=/home/alternative/jspooler
export JBCSPOOLERDIR

Variable: JBCTTYNAME
Description: Defines your UNIX TTY name. If this variable is not defined, jBASE will use the UNIX system
call ttyname() to define it. On some systems this function call is very slow and the use of this
variable will greatly improve execution start-up times.
Values:

Any character string.

Default:

None.

Setting:

Normal UNIX environment variable. Should be set in the .profile before the jbcconnect command:
JBCTTYNAME=JimTerm.
export JBCTTYNAME

Variable: JEDIFILENAME_MD
Description: Use this variable if you want the MD file to hold Qpointers, jCL programs or entries for the jQL
language. If you have loaded an account-save into your home directory then you will probably
need to set this variable.
Once the variable is set, you can:
Execute jCL programs directly from the MD (using jsh, EXECUTE, CHAIN, etc.).
Support Qpointers in the
JBCFILENAME_SYSTEM).

MD

file

(you

may

also

need

to

set

Create cross reference records for executables (from original name to new name) to
support systems which have a 14 character filename limit.
Values:

Valid file path.

Default:

None.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :
JEDIFILENAME_MD=./MD
export JEDIFILENAME_MD

Variable: JEDIFILENAME_SYSTEM
Description: If you are using Qpointers in a defined MD file, you may well need to create a SYSTEM file to
define the home directories of other accounts. By default, Qpointers are resolved by using the
$JBCRELEASEDIR/src/SYSTEM file. This can be changed by setting the
JEDIFILENAME_SYSTEM variable to an alternative hash file or directory.
Values:

Valid file path.

Default:

None.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :
JEDIFILENAME_SYSTEM=/home/alternative/SYSTEM
export JEDIFILENAME_SYSTEM

Programmers Reference Manual

8-5

Environment Variables

Variable: JEDIFILEPATH
Description: This variable is specific to jBASE. It tells executables built by the jbc command where they can
find data files for OPEN statements. For security, you may wish to set this path explicitly otherwise the default together with any other data directories will be sufficient.
Values:

Colon separated file paths.

Default:

${HOME}:.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :
JEDIFILEPATH=.
export JEDIFILEPATH

Variable: LIBPATH
Description: This variable is specific to AIX systems only. It should always be set to /usr/jbc/lib.
Values:

Colon separated library file paths.

Default:

None.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/jbc/lib
LD_LIBRARY_PATH

export

Variable: LD_LIBRARY_PATH
Description: This variable is specific to SVR4 systems only. It should always be set to /usr/jbc/lib.
Values:

Colon separated library file paths.

Default:

None.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/jbc/lib
LD_LIBRARY_PATH

export

Variable: PATH
Description: Contains a list of all directories that hold executable programs. As a minimum, this should contain
the shell default value and the /usr/jbc/bin path so that jBASE commands can be found by the
shell. You will also need to add the path of your application executable directory - such as
${HOME}/bin.
Values:

Any directory the user has privileges for.

Default:

Depends on your particular UNIX system and how it has been set up.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :
PATH=$PATH:/usr/jbc/bin
export PATH

Variable: TERM
Description: Set this variable to your terminal type as defined by the UNIX terminfo database.
Values:

Any valid terminfo database entry.

Default:

Depends on your particular UNIX system and how it has been set up.

Setting:

Normal UNIX environment variable. Can be set at any time by the commands :
TERM=vt220
export TERM

Environment Variables
Manual

8-6

Programmers

Reference

Programmers Reference Manual

8-7

Environment Variables

Chapter 9: Migrating to jBASE

Overview
jBASE provides the developer with a number of migration tools to allow applications developed on older
systems to be imported.
BEFORE EMBARKING ON AN APPLICATION IMPORT, YOU SHOULD READ THE WHOLE OF THIS
CHAPTER.
There are two ways in which you can port your application to jBASE:
1. Maintain your existing development methodology (BASIC and CATALOG);
2. Use the vastly more powerful UNIX and jBASE development methodology.

Compiling Using your Existing Methodology

The following mechanism is used to port to jBASE and continue to use your existing methods of compilation
and application development:
1.

Create a new UNIX user for your development account.

2.

Login as the new user and use the iju command (see later) to set up the account to use jsh as the login
shell.

3.

Produce an ACCOUNT-SAVE of your Application accounts on your old system. You must choose a
Media that is supported on the target jBASE machine.

4.

T-ATT the device containing the account save (see earlier).

5.

Type ACCOUNT-RESTORE .

6.

When the account restore has finished, compile your programs exactly as you did on your previous
system. I.E. BASIC BP * and CATALOG BP *, or any method you have already developed to build
your application.

7.

Run your application in the same way you always did.

Allowing Other Users to Run Your Application

If other users are to run your applications then you should do the following:
1.

As the root user create two global directories such as

2.

/usr/myapp/bin

3.

/usr/myapp/lib

4.

Change the permissions of these directories using the following command sequence:

chmod a+rwx /usr/myapp/bin /usr/myapp/lib

chown bin /usr/myapp/bin /usr/myapp/lib
5.

Login to your development user and copy the libraries and binaries to your new directory.

This chapter also assumes a certain basic knowledge of compilation mechanisms in UNIX. You should either
read the relevant UNIX documentation before this chapter or have attended a training course on the subject. The
general mechanism is as follows:
1.

Create a new UNIX user for your development account.

2.

Configure the shell environment if necessary and update .profile (command iju).

3.

Produce an ACCOUNT-SAVE of your Application accounts. You must choose a Media that is
supported on the target jBASE machine.

4.

Choose a directory into which to load the account. This is normally the home directory of a UNIX
user.

5.

ACC-RESTORE the tape.

Programmers Reference Manual

9-1

Migrating to jBASE

6.

Identify the files containing BASIC code or include code.

7.

Run the totalmake utility from the directory you restored the account into (base directory) to produce
Makefiles, or hand craft your own using supplied templates.

8.

Build the programs in each jBC code directory by running make from the base directory.

9.

Run the programs (development mode).

Once this mechanism is in place, it may be used by the developer time and again as the application is enhanced.

Migrating to jBASE

9-2

Programmers Reference Manual

Importing Accounts
Note that the following instructions assume use of UNIX SVR4, users of SVR3.2 will have received a
supplement or replacement to this chapter.
The first step in migrating any application to the jBASE system is to create and then import an ACCOUNTSAVE of each account involved in the application.
The developer should select a media for the save(s) that is supported by both the original development system
and the new UNIX system. jBASE will support any device configurable within UNIX. Unless you select an
unusual device you should already find that a jBASE device name has been configured for your selected device.
Consult the release supplement for the particular version of UNIX you are migrating to. The rest of this chapter
assumes that the user is importing via a 60 or 150MB tape cartridge.
The first step in importing an account is to create or select a target directory to restore the account. The easiest
way of doing this is to create a UNIX user using the sysadm command (or equivalent) with the same name as the
original account. UNIX normally requires user names to be specified in lower case. The sysadm command will
create a home directory for this user. If your system is supplied with the Korn shell (ksh) then select this as the
users shell.
Now log on as the UNIX user. You will find that by default the user does not have paths configured for the
jBASE system. You will therefore need to add /usr/jbc/bin to your PATH environment variable:
PATH=PATH:/usr/jbc/bin
You should add this to the .profile in the home directory as this will then set up the PATH on subsequent logins.
You can modify the default template on your UNIX system to include this as a default. On many systems the
default template is held in the file /etc./stdprofile but you should consult the documentation for your particular
version of UNIX. You can add almost any command to the .profile file. You may find it easiest to configure the
account using the iju utility, which will configure .profile based on your answers to a number of questions
(described later).
The tape can now be loaded. Firstly, attach the tape device to the jBASE system using:
T-ATT SCT0 SIZE=nnnn
This will establish a link between the jBASE tape drivers and (in this example), the cartridge drive. The value
nnnn should be the block size in bytes the original tape was saved at. The command T-STATUS will provide
information about the tape system.
The account restore can now commence. The jBASE system is supplied with the command ACC-RESTORE,
which will load the data on the tape. From the home directory issue the command:
acc-restore .
The '.' character indicates to the program that all files should be loaded in to the current directory, which is the
home directory of this user. The restore should now proceed.
The ACC-RESTORE may detect files in the current directory. If it does it will prompt you with a message
allowing you to quit, continue or list the files it found. Unless you have issued the command from the wrong
directory you should continue with the restore.
The restore will load every file on the account to a j-file in the home directory. When the restore has finished you
can check this with the ls -C command. If your version of UNIX is SVR4 or a compatible system then the files
created will be j2 files, otherwise they will be j1 files. The exception to this rule is that files with a modulo of 1
will be created as j1 files on all versions of UNIX.
You may now repeat the process for any other accounts you wish to import.

Programmers Reference Manual

9-3

Migrating to jBASE

Moving BASIC to jBC

Migrating BASIC Source Code Files
The first step in importing your code is to identify all the files containing BASIC source code. You will then
convert them to jBC source code directories or j-files. You should note the names of all the program files in the
account and create a save list (any name) using the EDIT-LIST listname command. You should then create a
similar list of all files that contain INCLUDE records. Any file that contains both include records and programs
should be added to the list of program files.

The totalmake Command

The command totalmake will take a SELECT list of all the file names and perform the Portbas program
(described below) on all the files. The totalmake will then build Makefiles for each file using the makemake
command (also described below) with special options
Inexperienced UNIX users should use this command to port their applications. It will ask a number of questions
about include files and subroutines that it is unable to find. If you choose to run this command then you may
ignore the explanations of Portbas and makemake although they will be useful reading as background
knowledge.
Experienced users may run the Portbas utility against each file in turn and build Makefiles manually if they
desire by following the instructions below regarding Portbas and makemake.
Before running totalmake you should have prepared the two SELECT lists described in the previous chapter.
Then ensure you are in the directory where you restored the account and issue the totalmake command as
follows:
totalmake
You should provide the command with the names of your SELECT lists when prompted and then leave the rest
to totalmake. This process may take some time if you have a very large number of programs in the account.
However, when the command is complete you can immediately compile your programs by issuing the make
command as so:
make all
This will build all your subroutines and all your executable programs. Your subroutines are placed in libraries in
a directory called lib. Your executable programs are placed in a directory called bin. You should ensure that
{HOME}/bin is placed in your PATH environment variable or you will not be able to execute your programs.
You can examine this variable by typing:
echo PATH
If the variable does not contain the entry for the bin directory you can add it using:
PATH={HOME}/bin :PATH
Note that when you inspect the PATH variable you will not see the string {HOME} as this is
translated into the path name of your home directory (base directory of your UNIX account).
You can determine the path name of your home directory by typing:
pwd
Note also that these commands should be issued using ksh. If you are using jsh then you can
change to ksh by typing F2 (function key 2).
Your application migration is now complete and you may proceed to test its functionality.

Portbas
jBASE is supplied with a tool for converting a BASIC source code file into a jBC directory. This tool is called
Portbas and is run against each file in turn.

Migrating to jBASE

9-4

Programmers Reference Manual

Issue the command Portbas from the directory containing your BASIC source code files. The command will the
prompt you for the name of source code file. Supply this at the prompt and then press return. The portbas
command will proceed to scan every BASIC program and prepare it for the jBC compiler. There are very few
changes required to BASIC source code to make it compatible with the jBC compiler. The changes required are
executed by portbas program and the procedure is as follows:
1) A UNIX directory is created for the converted code. This directory will be the capitalised version of
the original file name. For instance the programs in a file BP will converted to jBC programs in the
directory Bp. The original file will remain untouched for reference purposes.
2) Each BASIC program in turn is scanned for the use of keywords as variable names, which is not
allowed in the jBC language. Portbas will not change the variable name in this instance but will
capitalise the name. Thus the variable names LOOP, DATE, DATA become Loop, Date, Data
respectively. This allows the program to be read in its original context.
3) The BASIC program is formatted according to the standard jBC formatting recommendations
described in this manual.
4) If the source file is a SUBROUTINE then the name supplied as the subroutine argument is forced to
be the same as the source file name. The compiler uses this to name the subroutine rather than the file
name.
Note: Because of certain ambiguities in the original language specification, it is sometimes impossible for
portbas to decide whether the use of a keyword is correct or not. In certain cases it may wrongly decide that a
valid keyword is being used as a variable name and change it. However, it gets this right far more than it gets it
wrong and will save you a great deal of work. The jBC compiler will trap any mistakes made by portbas and you
may then change them manually.
As the portbas program runs, it will list the number of the current source file followed by the number of source
code lines it contains and the newly created filename. It will report the number of jBC programs ported at the
end of the run.
Note: You should take care to ensure that only BASIC code exists in the file before using the portbas
utility. Portbas cannot readily distinguish between BASIC code and any other type of data so you should
use the COPY or DELETE commands to remove records that do not contain BASIC source code. The
tool will ignore records whose name begins with a as these are assumed to contain BASIC object
code, which is no longer required.
Finally, the program will have renamed any include files with the suffix .b as it cannot see that they are to be
INCLUDEd in another source code. You should use the UNIX mv command to rename any INCLUDE records
by removing the .b suffix. However, if you are intending to use the makemake utility (described next) to build
your Makefiles, then you may leave this utility to rename included source records.
You have now completed the migration of the BASIC source code file to the jBASE system

Building Makefiles
If you have used the totalmake utility to build your makefiles then you may ignore this section, if you ran
Portbas manually then read on. At this stage you have one or more directories containing jBC source files but no
means to compile them other than manually. The best way to control application compilation in UNIX
environments is to use the make utility described in the UNIX manuals.
The make utility requires a file in the source code directory, which describes the relationship between all the
component parts of the application. This file is (by default) called Makefile or makefile although it may be
named otherwise.
You may wish to use the template supplied in the file /usr/jbc/src/Makefile as the basis to build your Makefile as
this is a relatively straightforward process. By building your Makefile manually, you will learn all about
compiling on UNIX systems and have a very neat Makefile.
Building Makefile manually can be a tedious process however, so the jBASE system is supplied with a tool
called makemake, which will build a Makefile for you. As Makefiles can be complicated for the unfamiliar user
you may wish to seek assistance with this aspect of your port. JAC and their VARs will be pleased to provided
help in this area.

Programmers Reference Manual

9-5

Migrating to jBASE

Before using the makemake utility you should ensure that all source code has been imported and the all include
records are present in either the source code directory itself or in a separate directory that contains all your
include files.
The makemake tool will now scan all the .b files in the requested directory and attempt to build a Makefile for
the current directory. As it analyses the code, it may be unable to locate subroutines or include files in the current
directory. If this is the case you will be issued a prompt showing the source code line where the reference was
made.
This prompt will allow to specify another directory to search for missing components, ignore the program
altogether or ignore the error in order to resolve manually later. The makemake utility may report an obviously
spurious error such as the word INCLUDE used within a string that it cannot view in context. If this is the case
you may select the ignore error option. You should allow makemake to search other directories if you know
where they are or resolve the problem later. You should only ignore the program if you know it to be obsolete.
Once the makemake process is complete, you will find a new file in the current directory called Makefile. You
should now be able to compile the programs in this directory by issuing the make command. By default the make
utility will search for the Makefile in the current directory and use the rules within it to compile your application.
If the makemake found problems that it was unable to resolve, you should now resolve them manually. If your
source code was already organised fairly well, then you will find that there are very few problems with the
Makefile produced. You may find that the process of building a Makefile causes you to tidy up the directory,
removing obsolete programs and removing references to subroutines that no longer exist.
If you have a complex application with more than one source code directory then you will need to run
makemake one level further up the directory chain in order to create unique names for the libraries required for
each directory. This will ensure that library names do not clash in the {HOME}/lib directory. You may also
need to include references to these separate libraries in the Makefiles produced for each directory.

Maintaining Makefiles
Once a Makefile has been generated it will remain fairly static. As the application is developed however, there
will be additions and deletions to the source records in each directory. When this happens you will need to
update the Makefile to reflect the changes.
In most cases this maintenance will be very simple. If you are deleting a source record then you need only
remove its reference in the Makefile. If you are adding a standalone program then you need only add an entry for
it in the relevant make rule. A cursory inspection of the Makefile will show the changes required.
If you are adding a new subroutine to the application you will need to choose a library to archive the subroutine
within. You will then need to ensure that all programs calling this subroutine link with the relevant library. It
usually a good idea to place the new subroutine in a library that the prospective callers already link with.
However, it is possible to create a new library and update the list of dependencies to ensure that this library is
linked to all calling programs.
On SVR3.2 systems (or equivalent), when a subroutine is changed and recompiled, then all programs calling that
subroutine must be relinked with the library. By default the Makefile produced will cause all programs to be
recompiled when the subroutines they are dependant on are changed. On SVR4 systems all application libraries
are compiled as dynamic libraries, which means that programs dependant upon the libraries need only be
recompiled if the subroutine parameters have changed. You may change the Makefile to reflect this if you wish,
but must consider that all programmers should be aware of the necessary implications.
Once the application has been successfully compiled the PATH environment variable for the current user should
be updated to include the {HOME}/bin directory. Compiled jBC programs may then be invoked from the shell
prompt by typing in their name. The .profile in the {HOME} directory should be updated to accommodate this.

Migrating to jBASE

9-6

Programmers Reference Manual

Importing jCL Programs

If you intend to use the JAC command shell jsh and maintain a file called MD in which jCL programs are kept
then you may choose to ignore this section as no changes are required to jCL programs in this situation.
The jBASE system provides support for enhanced jCL programs and a programming tool to migrate the jCL
programs into the UNIX environment.
jCL programs imported to the jBASE system are interpreted by the jpqn jCL interpreter. This interpreter is
invoked using standard UNIX methodology and requires a single line change to jCL programs. The jCL
programs are migrated into UNIX directories and their attributes are changed to make them executable files.
This migration is performed automatically by the makeproc utility provide with the system.
The user must first identify the jCL programs within the system. In many applications the applications are held in
the MD of the account. Any jCL programs held here must first be copied into another j# file before makeproc
can be run against them. The suggested method for this is to create a file called MDJCLS using the CREATEFILE command. You may then select all the jCL programs in MD using a command similar to:
SELECT MD WITH *A1 = "PQ]"
nn items selected
COPY MD
:(MDJCLS
The makeproc utility requires that only jCL records reside in a j-file before the makeproc tool is run against the
file. The makeproc utility performs the following operations:
1) makeproc creates the file ./tmp
2) All the jCL programs in the specified j-file will have the PQ{N} line replaced with the line #!
/usr/jbc/bin/jpqn.
3) Each jCL program will be copied from the j-file into the ./tmp directory. If the jCL program name exceeds
any file name length limits, the user will be prompted to rename the jCL program before the copy occurs.
4) The UNIX command chmod +x will be executed on the jCL program to turn into an executable text file.
When all jCL programs have been processed the original j-file will be deleted and a UNIX directory of the same
name created in its place. The jCL programs residing in the ./tmp directory will be moved to newly created
directory and the ./tmp file will then be deleted.
The new first line in the jCL program indicates to the shell that the executable text file should be interpreted by
the program specified here. The #! convention is a standard UNIX method of invoking interpreters and is used
by all shells to execute shell script files. This is the only change required to execute jCL programs within the
jBASE system.
The PATH environment variable should now include the path names of all directories containing jCL programs
so that the shell can locate them when they are invoked by command line prompts or EXECUTE/PERFORM
statements. The .profile file in the {HOME} directory of the user should be updated to reflect this.

Programmers Reference Manual

9-7

Migrating to jBASE

Directory Layouts
UNIX prefers the user to organise the application system into logically separate directories. Once you have
migrated your BASIC and jCL program files into UNIX directories you should consider reorganising the data
files in the {HOME} directory.
If you have a small number of data files then this organisation may be as simple as moving all the data files into
a subdirectory of the {HOME} directory called data. If you have very many files then you may wish to create
subdirectories beneath the data directory to hold logical groups of data files. This makes the application system
more manageable as it is easier to navigate around the application system.
In order to move the data files you must first create the target ./data directory. The command:
mv * data
will then move all the data files into the ./data directory. You will notice that this command does not move
directories, only the j-files and UNIX files in the {HOME} directory. The mv command will inform the user
that it is ignoring subdirectories in the move.
If you have decided to use subdirectories under the data directory you may wish to use regular expressions in the
mv command instead of * to move to the subdirectory beneath ./data. Your UNIX documentation explains the
mv command and regular expressions in more detail.
Once the data files have been moved to the ./data subdirectory you need to set a new environment variable to
indicate their new location to the jBASE system. You must issue the following command at the shell prompt:
JBCFILEPATH=./data:./data/invoices .... ; export JBCFILEPATH
If your development system consists of more than one account you might wish to consider amalgamating them
into different directories within the same UNIX user.
In order to do this you should create a directory for each account you will restore. Then issue the ACCRESTORE from the home directory of the user specifying the target directory rather than the '.' directory. Repeat
this process with each account you wish to restore. The PATH environment variable may then be updated to
include the paths of all jCL programs contained in the system.

Migrating to jBASE

9-8

Programmers Reference Manual

Development and Live Environments

Release Mechanisms to Live and Test Environments
Until this point we have shown only how to produce an executing application in the development environment.
This chapter shows how to produce releases to testing and live environments.
A test environment will normally comprise of a standalone UNIX user with its own {HOME}/bin and
{HOME}/lib directories. The executable binaries and application libraries are copied from the development
directories to the test directories by implementing a new rule in the application Makefile called testrelease.
This rule will be very similar to the following:
TESTTD=/usr/apptest/lib
TESTETD=/usr/apptest/bin
TD= /usr/apptest/bin
ETD=/usr/app/bin
testrelease:
cp (TD)/* (TESTTD)
cp (ETD)/* $(TESTETD)
chmod a+xr $(TESTETD)/*
chmod a+r $(TESTTD)
The developer may also wish to change the owning group and various permissions according to the security
policy of the company.
A live environment may either consist of a standalone live account or a globally available directory on the
system. A new rule is created either in a Makefile in the test directory or again in the development Makefile.
Whether the target directory for the live system is a globally available directory such as /usr/applic or a
standalone user is entirely at the discretion of the developer. The new rule liverelease: is entered into the
Makefile, which will execute cp and chmod commands in the same way as the testrelease: rule. The way in
which live users login to the application is covered in the next topic.

Account Vs User
The jBASE developer may allow users access to the live application in a number of ways. It is likely that the
existing application is executed from a single ACCOUNT that all users login to. This is, of course, still possible
within the jBASE scenario. All users may login to the same UNIX user, with the .profile file in the {HOME}
directory invoking the start up program of the application. The UNIX user name will normally be a lower case
version of the original account name.
Some applications rely on the account name to implement their own user security routines and it may be that the
account name has been hard coded in Upper case characters. The jBASE system allows the effective login (or
ACCOUNT name) to be changed as far it is concerned by setting a new environment variable to the old
ACCOUNT name. This is achieved by issuing the shell commands:
JBCLOGNAME=ACCNAME ; export JBCLOGNAME
These commands should be added into the .profile file of the login user.
UNIX systems are able to implement security routines on a user by user basis. It is therefore worth considering
creating a UNIX user for each application user on the system. They may all utilise the same {HOME} directory
and by using the JBCLOGNAME environment variable they will all appear to be logged on to the same account.
However, different users may then be granted individual group and execution permissions providing useful
security checks in the application.

Programmers Reference Manual

9-9

Migrating to jBASE

User Port Numbers

The .profile file is just a special type of UNIX shell script and can therefore contain sophisticated logic as can
any other shell script. One of the functions of the .profile script could be to determine the login PORT number of
the user.
Many applications make use of the port number in application security routines and rely on the consistency of
the port number to implement these systems. The user is automatically given a unique PORT number by the
jBASE system at login time. However, networked systems and terminal server based systems MAY cause
jBASE to assign a different port number for every login session, which is difficult to cater for in security
routines. The consistency of the PORT number can be guaranteed by setting the environment variable
JBCPORTNO in the .profile script according to the name of the user who logged on. Again, this environment
variable must be exported so that it is seen by the jBASE system.
The command iju may be used from the home directory of a newly created user to install the various commands
needed to set environment variables in the .profile. It is used as follows:
PATH=/usr/jbc/bin:PATH
export PATH
iju
You will be asked a series of simple questions by this command, which are fully explained as they are asked.
Answer these questions and follow the instructions given to automate the configuration of a new user.

Migrating to jBASE

9-10

Programmers Reference Manual

Index
$
$HOME, 8-3
(
( ) jCL command, 3-11, 3-14
.
.el file, 2-11
.o files, 2-11
.profile script, 8-1, 8-2, 8-3, 8-4, 8-5
.profile script file, 2-12
.so files, 2-11
:
:REST-SPOOLER, 7-2
:SP-NEWTAB, 7-2
@
@ function, 2-43
@(ScreenCode) function, 2-43
[
[ ] jCL command, 3-15
[ ] jCL command, 3-11
+
+ jCL command, 3-15
A
A code, 4-38
A jCL command, 3-17
A jCL command, 3-11
ABORT, 2-44, 2-110, 2-111
ABS, 2-45, 2-106
ACCOUNT-RESTORE, 7-1, 9-1
ACCOUNT-SAVE, 7-1, 9-1, 9-3
Active Input Buffer, 3-6
Active Output Buffer, 3-6

ADDD, 7-1
ADDX, 7-1
ALPHA, 2-45
arithmetic expressions, 2-30
Arithmetic Operators, 3-12
arrays, 2-39
ASCII function, 2-46
ASSIGNED, 2-46, 2-116
assigning variables, 2-28
assignment statement, 2-28
B
B code, 4-47
B jCL command, 3-18
B jCL command, 3-11
BASIC, 2-3, 2-10, 7-1, 9-1, 9-4, 9-5, 9-8
BASIC to jBC, 9-4
BITCHANGE, 2-47
BITCHECK, 2-47
BITLOAD, 2-48
BITRESET, 2-48, 8-1
BITSET, 2-49, 8-1
BKOFF, 7-1
BKON, 7-1
BO, 3-7
BO jCL command, 3-11, 3-19
BREAK, 2-37, 2-47, 2-49, 2-56, 2-66, 2-71, 2-82,
2-112
BREAK OFF, 2-15, 2-49
BREAK ON, 2-49
BREAK-KEY-ENABLE, 7-1
BREAK-KEY-OFF, 2-15, 7-1
BREAK-KEY-ON, 7-1
breakpoint table, 2-15, 2-16, 2-19, 2-20, 2-22
BSELECT, 3-7, 3-61, 4-4, 4-5, 5-12, 7-2
BSELECT jQL command, 4-18
Buffer References, 3-8
C
C, 1-1, 2-1, 2-2, 2-3, 2-4, 2-5, 2-6, 2-10, 2-27, 231, 2-60, 2-61, 2-67, 4-35, 4-47, 4-49, 6-3
C code, 4-48

Index

C functions, 2-38, 2-61

C jCL comment, 3-19
C programs, 2-1
C++, 1-1
CALL, 2-24, 2-38, 2-50, 2-105, 2-111, 4-47, 4-49
CASE, 2-37, 2-51, 6-5, 6-10
CATALOG, 2-11, 7-1, 9-1
CHAIN, 2-51, 2-55, 2-59, 3-3, 3-5, 3-6
CHANGE, 2-52, 2-57
CHAR, 2-52
CHDIR, 2-14, 2-53, 2-71
CHECKSUM, 2-53
CHECK-SUM, 4-4
CLEAR, 2-53, 7-1
CLEARFILE, 2-54
CLEAR-FILE, 4-19, 7-1
CLOSE, 2-54
COL1( ) & COL2( ), 2-55
COLLECTDATA, 2-56, 2-66
Command Level Restart, 8-1
command syntax, 2-27, 5-12
comment lines, 2-34
COMMON, 2-25, 2-26, 2-38, 2-39, 2-50, 2-51, 255, 2-63, 2-64, 2-111, 4-49
Conditional Operations, 3-12
constants, 2-28
CONTINUE, 2-37, 2-56, 2-71, 2-82
conversion codes, 2-36, 4-34
CONVERT, 2-57
CONVERT function, 2-57
COPY, 7-1
COPY-LIST, 5-2, 7-2
COS, 2-57
COUNT, 2-50, 2-58, 4-4, 4-29, 4-30, 7-2
COUNT jQL command, 4-18
CP, 7-1
CREATE-FILE, 2-90, 7-1
CRT, 2-35, 2-58, 2-70, 2-74, 2-93
CT, 7-1
D
D code, 4-51
D jCL command, 3-20
D1 / D2 codes, 4-53
DATA, 2-59, 3-6
data definition records, 4-31
Data Movement Commands, 3-11
data records, 2-28
DATE, 2-59, 2-88, 3-9
DATE-FORMAT, 4-51, 7-1
DCOUNT, 2-60
DE jCL command, 3-20
DEBUG, 2-13, 2-60
debug facilities, 2-3
DEBUG jCL command, 3-21
DEBUG jCL command, 3-13
DEBUG statement, 2-13

Index

debugger, 2-1, 2-2, 2-4, 2-13, 2-31, 2-54, 2-60, 267, 2-99, 2-105, 2-117, 2-119
Debugging, 3-13
DECATALOG, 2-12, 7-1
DEFC, 2-38, 2-60
DEL, 2-61
DELETE, 2-62, 7-1
DELETE-CATALOG, 2-12, 7-1
DELETE-FILE, 7-1
DELETELIST, 2-62
DELETE-LIST, 5-3, 7-2
development and live environments, 9-9
development tools, 1-1
DIMENSION, 2-39, 2-62
dimensioned arrays, 2-39, 2-41, 2-55
directory layouts, 9-8
DIVD, 7-1
DIVX, 7-1
DTX, 2-63, 7-1
dynamic arrays, 2-39, 2-40, 2-68, 2-105
E
EBCDIC, 2-63
ECHO, 2-64, 7-1
ECHO OFF, 2-64
ECHO ON, 2-64
ECHO-OFF, 7-1
ECHO-ON, 7-1
EDELETE, 4-1, 4-4, 7-2
EDELETE jQL command, 4-19
EDIT-LIST, 5-3, 5-8, 7-2, 9-4
Editor
command line operations, 6-6
key commands, 6-4
Editors, 6-1
ENABLE-BREAK-KEY, 7-1
ENTER, 2-64
environment variables, 2-1, 2-10, 2-11, 2-12, 2-71,
2-72, 2-92, 2-96, 4-1, 8-1, 9-10
EQUATE, 2-63, 2-65
ESEARCH, 3-7, 3-61, 4-4, 4-5, 5-12, 7-2
ESEARCH jQL command, 4-19
EXECUTE, 2-2, 2-56, 2-59, 2-65, 2-93, 2-96, 2106, 2-112, 3-3, 3-5, 3-6, 9-7
EXIT, 2-37, 2-50, 2-56, 2-66
EXP, 2-67
export list, 2-11
EXTRACT, 2-67
F
F code, 4-54
F jCL command, 3-21
F jCL command, 3-11
FB, 3-7
FB jCL command, 3-27
FB jCL command, 3-12
F-C jCL command, 3-23

F-C jCL command, 3-12

F-CLEAR jCL command, 3-23
F-CLEAR jCL command, 3-12
F-D jCL command, 3-23
F-D jCL command, 3-12
F-DELETE, 3-24, 3-26
F-DELETE jCL command, 3-23
F-DELETE jCL command, 3-12
F-F jCL command, 3-24
F-F jCL command, 3-12
F-FREE, 3-26
F-FREE jCL command, 3-24
F-FREE jCL command, 3-12
FIELD, 2-55, 2-68, 2-73
field definition records, 4-31
File Buffers, 3-7
file definition records, 4-29
file handling, 2-41
File Operations, 3-12
file systems, 1-1
FIND, 2-68, 2-69, 2-81
FINDSTR, 2-69, 2-81
F-K jCL command, 3-24
F-K jCL command, 3-12
F-KLOSE, 3-25
F-KLOSE jCL command, 3-24
F-KLOSE jCL command, 3-12
FLOAT, 2-60
F-O jCL command, 3-25
F-O jCL command, 3-12
FOOTING, 2-70, 2-92, 2-112, 4-12, 4-14
F-OPEN, 3-12, 3-23, 3-24, 3-26, 3-27, 3-28
F-OPEN jCL command, 3-25
F-OPEN jCL command, 3-12
FOR, 2-37, 2-56, 2-70, 2-73
formatting variables, 2-35
FORM-LIST, 3-7, 3-61, 4-5, 5-2, 5-4, 5-6, 7-2
F-R jCL command, 3-25
F-R jCL command, 3-12
F-READ, 3-28
F-READ jCL command, 3-25
F-READ jCL command, 3-12
F-UR jCL command, 3-26
F-UR jCL command, 3-12
F-UREAD, 3-12, 3-24, 3-27
F-UREAD jCL command, 3-26
F-UREAD jCL command, 3-12
F-W jCL command, 3-27
F-W jCL command, 3-12
F-WRITE, 3-24, 3-26
F-WRITE jCL command, 3-27
F-WRITE jCL command, 3-12
G
G code, 4-59
G jCL command, 3-28
GETCWD, 2-71
GETENV, 2-71

GETLIST, 2-72, 2-98

GET-LIST, 3-7, 3-56, 3-61, 4-2, 4-3, 4-5, 4-6, 418, 4-19, 4-20, 5-2, 5-4, 7-2
G-F jCL command, 3-30
GO B, 3-12, 3-46, 3-47
GO B jCL command, 3-29
GO B jCL command, 3-12
GO F, 3-12, 3-46, 3-47
GO F jCL command, 3-30
GO F jCL command, 3-12
GO jCL command, 3-28
GO jCL command, 3-11
GO{TO}, 2-73
GO-B jCL command, 3-29
GOSUB, 2-17, 2-24, 2-36, 2-37, 2-38, 2-72, 2-90,
2-105, 2-111, 3-15, 3-38, 3-53, 3-54
GOSUB jCL command, 3-31
GOSUB jCL command, 3-12
GOTO, 2-8, 2-36, 2-37, 2-73, 2-90
GOTO B jCL command, 3-29
GOTO F jCL command, 3-30
GOTO jCL command, 3-28
GOTO jCL command, 3-11
GROUP, 2-73
H
H jCL command, 3-32
H jCL command, 3-11
HEADING, 2-70, 2-74, 2-92, 2-112, 4-2, 4-12, 414, 4-16, 4-23, 4-27
HUSH, 7-1
I
IBH, 3-6, 3-42
IBH jCL command, 3-33
IBH jCL command, 3-11
IBN, 3-6, 3-35, 3-43, 3-44
IBN jCL command, 3-34
IBN jCL command, 3-11
IBP, 3-34, 3-43, 3-44
IBP jCL command, 3-35
IBP jCL command, 3-11
ICONV, 2-36, 2-75
IF, 2-36, 2-37, 2-75, 3-17, 3-28, 4-40, 4-45, 6-5
IF (masked) jCL command, 3-38
IF (multivalued) jCL command, 3-37
IF ... THEN, 2-37
IF E, 3-5
IF E jCL command, 3-39
IF E jCL command, 3-12
IF jCL command, 3-36
IF jCL command, 3-12
IF S jCL command, 3-40
IFN, 3-12, 3-36
IFN jCL command, 3-41
IH, 3-6, 3-33
IH jCL command, 3-41
IH jCL command, 3-11

Index

Importing Accounts, 9-3

Importing jCL, 9-7
IN, 2-76, 3-34, 3-35, 3-44
IN jCL command, 3-43
IN jCL command, 3-11
INCLUDE, 2-38, 4-49, 9-4, 9-5, 9-6
include files, 2-4, 2-10, 9-4, 9-5, 9-6
INDEX, 2-76
INHIBIT-BREAK-KEY, 2-15
INPUT, 2-35, 2-77, 2-78, 3-6
Input Buffer Commands, 3-11
Input/Output Buffer Operations, 3-11
INPUTNULL, 2-78
INS, 2-78, 2-79
INSERT, 2-79
INT, 2-60, 2-79
IP, 3-6, 3-34, 3-35, 3-43
IP jCL command, 3-44
IP jCL command, 3-11
IT jCL command, 3-45
IT jCL command, 3-11
J
j1, 1-1, 2-9, 9-3
j2, 1-1, 2-9, 9-3
j3, 2-9
jbackup, 1-1, 7-3
JBASETMP, 8-1
jBC, 1-1, 2-1, 2-30, 3-3, 3-4, 3-5, 3-6, 3-56, 3-57,
4-5, 4-11, 4-24, 4-27, 4-35, 4-47, 4-49, 5-10, 61, 6-3, 6-5, 6-7, 6-10, 7-1, 7-2, 9-2, 9-5, 9-6
JBC_ENDRESTART, 8-1
JBC_TCLRESTART, 8-1
jbcconnect, 7-3, 8-1, 8-2, 8-3, 8-4, 8-5
JBCDEFDICTS, 8-2
JBCEMULATE, 8-2
JBCERRFILE, 8-2
JBCGLOBALDIR, 8-2
JBCIDLEN, 8-3
JBCLOGNAME, 8-3
JBCOBJECTLIST, 8-3
JBCPORTNO, 8-3
JBCPRINTER_DEPTH, 8-4
JBCPRINTER_WIDTH, 8-4
JBCRELEASEDIR, 8-4
JBCSCREEN_DEPTH, 8-4
JBCSCREEN_WIDTH, 8-4
JBCSPOOLDIR, 8-5
JBCTTYNAME, 8-5
jBTP, 2-113, 7-1, 8-2
jchmod, 7-1
jCL, 1-1, 2-52, 2-65, 2-94, 2-95, 2-110, 3-1, 4-5, 511, 7-2, 8-5, 9-7, 9-8
F, 3-22
jCL commands, 3-11
jED, 2-3, 2-6, 2-7, 2-40, 2-42, 3-3, 3-6, 6-2
jEDI, 1-1, 2-5, 2-11, 2-40, 6-2

Index

JEDIFILENAME_MD, 8-5
JEDIFILENAME_SYSTEM, 8-5
JEDIFILEPATH, 8-6
jfb command, 2-7, 2-8
jgrep, 7-1
jLP, 1-1, 3-46, 7-2
jPML, 7-3, 8-2
jQL, 1-1, 2-107, 3-5, 3-22, 3-33, 3-42, 3-45, 3-46,
3-52, 3-56, 3-57, 4-1, 7-2, 8-3, 8-5
jQL command sentence, 4-3
jrestore, 1-1, 7-3
jrf, 7-1
jRLA, 8-2
JRLA, 7-3
jsh, 8-5
jSHELL, 2-3, 3-3, 3-4, 4-3, 4-24, 4-27, 5-1
jspprint, 7-3
jstat, 7-1
Jump and Branch Operations, 3-11
L
L code, 4-60
L jCL command, 3-45
LD_LIBRARY_PATH, 8-1, 8-6
LEN, 2-80
LIBPATH, 8-1, 8-6
line continuation, 2-34
linked libraries, 2-3
LIST, 4-1, 4-4, 4-14, 4-23, 4-29, 4-30, 7-2
LIST jQL command, 4-20
LISTDICT, 7-2
LISTDICT jQL command, 4-22
LISTDICTS, 7-1
LISTF, 7-1
LIST-JOB, 7-1
LIST-LABEL, 4-4, 7-2
LIST-LABEL jQL command, 4-21
LIST-LISTS, 5-5, 7-2
LISTPEQS, 7-2
LISTPTR, 7-2
LISTU, 7-1
LN, 2-80
LOCATE, 2-80
LOCK, 2-41, 2-81, 2-117
logical operators, 2-31
Login jCL Programs, 3-4
LOGOFF, 7-1
LOOP, 2-37, 2-56, 2-73, 2-78, 2-81
looping constructs, 2-37
M
M jCL command, 3-46
M jCL command, 3-12
makefiles, 2-3, 2-5, 2-10, 9-2, 9-4, 9-5, 9-6
building, 9-5
maintaining, 9-6
makeproc, 9-7

MAT, 2-82, 2-111

MATBUILD, 2-83, 2-84
MATCH{ES}, 2-82
MATPARSE, 2-84
MATREAD, 2-39, 2-85
MATREADU, 2-39, 2-42, 2-85, 2-120
MATWRITE, 2-42, 2-86, 2-87, 2-100, 2-102, 2120, 2-121
MATWRITEU, 2-42, 2-87, 2-100, 2-102, 2-121
MC codes, 4-61
MD code, 4-66
MD file, 8-5
migration, 9-1
MK code, 4-67
ML/MR codes, 4-68
MOD, 2-88
MP code, 4-70
MS, 3-5
MS code, 4-71
MS jCL command, 3-47
MS jCL command, 3-11
MSG, 7-1
MT code, 4-72
MULD, 7-1
MULX, 7-1
MV, 3-6, 3-8, 3-19, 3-23, 3-34, 3-43, 3-55, 3-56
MV jCL command, 3-47
MV jCL command, 3-11
MVA jCL command, 3-49
MVA jCL command, 3-11
MVD jCL command, 3-50
MVD jCL command, 3-11
N
naming conventions, 2-8
NEW-GET-LIST, 5-5, 7-2
NEW-SAVE-LIST, 5-5, 5-6, 7-2
NEW-SORT-LIST, 5-6
NOHUSH, 7-1
NOT, 2-31, 2-88
NULL, 2-88
NUM, 2-89
numeric strings, 2-31

P
P code, 4-73
P jCL command, 3-51
PAGE, 2-92
PATH, 8-1, 8-6
pattern matching, 2-35
PERFORM. See EXECUTE
PH-ALLOCATE, 7-1
PH-CLEAR, 7-1
PH-DELETE, 7-1
PH-KILL, 7-2
PH-LINES, 7-1
PH-RESUME, 7-1
PH-START, 7-1
PH-STATUS, 7-1
PH-SUSPEND, 7-2
PICK, 2-2
port number, 8-3
Portbas, 9-4, 9-5
PORTBAS, 7-3
PORT-DESPOOL, 7-2
PQ and PQN Differences, 3-63
PQ-RESELECT, 3-7, 3-61, 5-11, 7-2
PQ-RESELECT jCL command, 3-61
PQ-SELECT, 3-7, 3-32, 3-61, 5-11, 7-2
PQ-SELECT jCL command, 3-61
PRECISION, 2-50, 2-67, 2-93, 2-108, 2-110, 2111, 2-113
Primary Input Buffer, 3-5
Primary Output Buffer, 3-5
PRINT, 2-35, 2-93, 2-94
PRINTER ON|OFF|CLOSE, 2-94
PRINTERR, 2-94
PROCREAD, 2-94, 2-95, 3-5
PROCWRITE, 2-95, 3-5
PROGRAM, 2-95
program and library files, 2-4
program files, 2-35
program memory requirements, 2-11
PROMPT, 2-96, 2-113
PUTENV, 2-72, 2-96
PWR, 2-96
Q

O
O jCL command, 3-51
OCONV, 2-36, 2-59, 2-75, 2-89
OFF, 2-17, 7-1
ON .... GOSUB, 2-37
ON...GOSUB, 2-90
ON...GOTO, 2-90
OPEN, 2-41, 2-54, 2-62, 2-85, 2-86, 2-87, 2-91, 297, 2-100, 2-101, 2-102, 2-103, 2-118, 2-119,
2-120, 2-121
OUT, 2-92
Output Buffer Commands, 3-11

QSELECT, 3-7, 3-61, 4-5, 5-6, 7-2

R
R code, 4-74
READ, 2-40, 2-91, 2-97
READLIST, 2-72, 2-98, 2-118, 5-10, 7-2
READNEXT, 2-98, 2-107, 4-11, 4-24, 4-27, 5-10,
7-2
READT, 2-99
READU, 2-40, 2-42, 2-97, 2-100, 2-120
READV, 2-40, 2-101
READVU, 2-40, 2-42, 2-101
record locking, 2-41

Index

REFORMAT, 4-4, 4-27, 7-2

REFORMAT jQL command, 4-23
REGEXP, 2-102
relational expression, 2-33
RELEASE, 2-42, 2-100, 2-102, 2-103, 2-120, 2121
REM, 2-34, 2-88
REMOVE, 2-103
REPLACE, 2-104
reserved words, 2-29
RETURN, 2-36, 2-37, 2-38, 2-105, 2-111
REWIND, 2-105
RI, 3-6, 3-34, 3-43
RI jCL command, 3-52
RI jCL command, 3-11
RND, 2-105
RO, 3-19, 3-56
RO jCL command, 3-53
RO jCL command, 3-11
RQM. See SLEEP
RSUB, 3-31
RSUB jCL command, 3-53
RSUB jCL command, 3-12
RTN, 3-15
RTN jCL command, 3-54
RTN jCL command, 3-12
RTNDATA, 2-66, 2-106
RUN, 7-1
RUN command, 2-12
run-time components, 1-1
S
S code, 4-75
S jCL command, 3-55
S jCL command, 3-11
SAVE-LIST, 2-62, 2-72, 2-98, 5-4, 5-7, 5-8, 7-2
SEARCH, 3-7, 3-61, 4-5, 5-2, 5-7, 7-2
Secondary Input Buffer, 3-5
Secondary Output Buffer, 3-6
SELECT, 2-72, 2-99, 2-106, 3-7, 3-40, 4-1, 4-2, 43, 4-4, 4-5, 4-6, 4-11, 4-18, 4-19, 4-20, 4-27, 512, 6-3, 7-2, 9-4
SELECT jQL command, 4-23
Select Registers, 3-7
SEL-RESTORE, 7-1
SENTENCE, 2-107
SEQ, 2-107
SET-DEC, 4-66, 4-68, 7-1
SET-LANG, 7-1
SET-MONEY, 4-66, 4-68, 7-1
SET-THOU, 4-66, 4-68, 7-1
shared libraries, 2-5, 2-11
shared library objects, 2-11, 2-12
SIN, 2-108
SLEEP, 2-106, 2-108, 7-1
SORT, 2-109, 4-3, 4-4, 4-14, 4-26, 7-2
SORT jQL command, 4-24

Index

SORT-LABE, 7-2
SORT-LABEL, 4-4
SORT-LABEL jQL command, 4-26
SORT-LIST, 3-56, 5-2, 5-8, 7-2
SOUNDEX, 2-109
SPACE, 2-110
SP-ALIGN, 7-2
SP-ASSIGN, 2-93, 3-46, 7-2
SP-CLEAR, 7-2
SP-CLOSE, 7-2
SP-COPIES, 7-2
SP-CREATE, 7-2
SP-DELETE, 7-2
SP-DEVICE, 7-2
SP-EDIT, 7-2
SP-EJECT, 7-2
SP-FORM, 7-2
SP-FQDELETE, 7-2
SP-JOBS, 7-2
SP-KILL, 7-2
SP-LOOK, 7-2
SP-MOVEQ, 7-2
spooler, 1-1, 3-10, 4-4, 4-15, 8-4, 8-5
SP-OPEN, 7-2
SP-OPTS, 7-2
SP-PRIORITY, 7-2
SP-PURGEQ, 7-2
SP-RESUME, 7-2
SP-SKIP, 7-2
SP-STATUS, 7-2
SP-STOP, 7-2
SP-SUSPEND, 7-2
SP-SWITCH, 7-2
SP-TAPEOUT, 7-2
SP-TRANSLATE, 7-2
SP-TYPE, 7-2
SQL, 1-1, 2-1
SQL Database, 2-1
SQRT, 2-110
SREFORMAT, 4-4, 4-23, 7-2
SREFORMAT jQL command, 4-26
SSELECT, 2-98, 2-107, 3-7, 3-61, 4-4, 4-5, 4-24,
5-8, 5-12, 6-3, 7-2
SSELECT jQL command, 4-27
STARTSCHED, 7-1
statements and statement labels, 2-34
STOFF, 3-6
STOFF jCL command, 3-55
STOFF jCL command, 3-11
STON, 3-6, 3-56
STON jCL command, 3-56
STON jCL command, 3-11
STOP, 2-110, 2-111, 2-112
STOP codes, 8-1
STOPSCHED, 7-1
STR, 2-110
strings and string operations, 2-32
structured coding, 2-8

SUBD, 7-1
SUBROUTINE, 2-50, 2-105, 2-111, 4-49, 9-5
subroutine objects, 2-11
subroutines, 2-38, 2-111
SUBX, 7-1
SVR4, 8-6
symbol tables, 2-26
SYSTEM, 2-43, 2-64, 2-99, 2-105, 2-111, 2-117,
2-119
SYSTEM file, 8-5
T
T code, 4-76
T jCL command, 3-56
TAN, 2-113
tape devices, 2-99, 2-117, 2-119
T-ATT, 2-99, 2-119, 4-23, 4-27, 7-3, 9-1, 9-3
T-BCK, 7-3
T-CHK, 7-3
T-DET, 7-3
T-DUMP, 4-4, 4-5, 7-2, 7-3
T-ERASE, 7-3
TERM, 2-112, 6-11, 7-1, 8-4, 8-6
TERMINAL, 7-1
Tfile code, 4-77
T-FWD, 7-3
TIME, 2-114, 3-9, 7-1
TIMEDATE, 2-59, 2-114
T-LOAD, 4-4, 7-2, 7-3
totalmake Command, 9-4
TR jCL command, 3-58
trace table, 2-15, 2-16, 2-17, 2-18, 2-19, 2-20, 2-21,
2-22, 2-24
TRANSABORT, 2-114, 2-115
TRANSEND, 2-114, 2-115
TRANSQUERY, 2-115
TRANSTART, 2-115
T-RDLBL, 7-3
T-READ, 7-3
T-RETENSION, 7-3
T-REW, 7-3
TRIM, 2-115, 2-116
TRIMB, 2-116
TRIMF, 2-116
T-STATUS, 7-3, 9-3

T-UNLOAD, 7-3
T-WEOF, 7-3
U
U code, 4-79
U jCL command, 3-59
UNASSIGNED, 2-116
UNIX, 1-1, 1-2, 2-1, 2-2, 2-3, 2-4, 2-5, 2-6, 2-7, 29, 2-11, 2-15, 2-18, 2-50, 2-51, 2-61, 2-65, 267, 2-71, 2-93, 2-95, 2-102, 2-103, 2-112, 2113, 3-2, 3-3, 3-12, 3-51, 3-52, 6-2, 6-4, 6-6, 67, 6-9, 6-10, 6-11, 8-1, 8-3, 8-5, 8-6, 9-1, 9-3,
9-4, 9-5, 9-7, 9-8, 9-9, 9-10
UNIX directory, 2-53
UNLOCK, 2-41, 2-81, 2-117
V
VAR, 2-60
variables, 2-28
W
WEOF, 2-117
WHERE, 7-1
WHO, 7-1, 8-3
Windows, 1-1, 1-2
WRITE, 2-42, 2-91, 2-100, 2-102, 2-103, 2-117, 2120, 2-121
WRITELIST, 2-62, 2-72, 2-98, 2-118, 5-10, 7-2
WRITET, 2-119
WRITEU, 2-42, 2-100, 2-102, 2-118, 2-119, 2-121
WRITEV, 2-42, 2-100, 2-102, 2-120, 2-121
WRITEVU, 2-42, 2-120, 2-121
X
X jCL command, 3-60
XSELECT, 5-8, 7-2
XTD, 2-121, 7-1
Z
Z, 7-1
ZH, 7-1

Index