Professional Documents
Culture Documents
+ 1
K
MANUAL OF LANGUAGE HBL
0 !+ 2
K
1. CHAPTER 1: INTRODUCTION TO LANGUAGE
HBL
Page 1
0 !+ 3
K
1.1. System Philosophy
The time to be spent by user to change his program is only when the
K System Philosophy;
Page 2
original application is created expressively for a particular operating
system and he will be helped by facilities available only in that system.
Compiler
Runtime
KComponents of System;
Page3
Method of Access Sequential with Index (ISAM)
The user can create a file to store, restore and update the
information basing on one or more key fields of data of the
record.
For example, the information utilized can be stored in
a file ISA by using the number to identify any record done.
Debug Symbolical
This chapter gives general information about HBL language and about
the structure of HBL programs, introduces the instructions used to
construct the programs and describes the basic elements of language.
Numerical : 0, 1, 2, 3, 4, 5, 6, 7, 8 e 9.
Alpha: all ASCII characters, except those that control the devices of I/O
(i.e. carriage return, line feed and form feed).
KAssemblage of Characters ;
0 !+ 3
K
2.2. Organization of a Program
The Data Division defines the data structures that will be used,
instead the Procedure Division defines the algorithms.
K Organization of a Program;
Outline of major features of a program:
SUBROUTINE (Instruction)
Instructions of Data Division
.
.
PROC (Instruction)
Instructions of Procedure Division
.
.
END (Instruction)
0 !+ 3
K
2.3. Types of Instructions
Instructions of I/O
PROC
Ends the Division Data and starts the Procedure
Division.
END
Marks the end of program.
KTypes of Instructions;
2.3.2. Instructions of Data Division
COMMON
Is similar to instruction RECORD in a main program, in fact
both define data of type record and the field associated.
Records and defined fields can be used both by main
program and by subroutine programs.
The data is part of main program.
In a subroutine program COMMON defines the references to
areas of data defined in the main program.
Differing from instruction RECORD, however, it will not be
defined a new space of data.
GLOBAL
Specifies that all definitions RECORD following the
instruction
GLOBAL must be spaces of data allocated in regions of
memory particular having a name instead of in the region
that normally the compiler uses.
RECORD
Defines the disposition of a data type record and defines his
data field.
Data field in record are defined from left to right in
sequence as they show themselves up.
Only the program that is defining it can access to a data of
kind record (and to his associated fields).
VRECORD
Defines a record VIRTUAL, to build in RUN-TIME.
Inside of a VRECORD we can define pointers to other field
already defined, to obtain a different data grouping.
SUBROUTINE
Identifies the program to compile like a subroutine more than
as
a main program
The instruction SUBROUTINE defines also the parameters
by which the information are passed from the calling
program and subroutine program.
2.3.3. Instructions to Manipulate Data
CLEAR
Initializes one or more variables both by blank (for variables
alpha) and zeros (for decimals variables)
DECR
Decreases of one a decimal variable specified.
INCR
Increases of one a decimal variable specified.
LOCASE
Converts all capital characters of a variable alpha into small
characters.
UPCASE
Converts all small characters of a variable alpha into
capital
characters.
2.3.4. Instructions for Control of Program
CALL
Does transfer the control to a label of program. The control
backs when a command of RETURN is done, ending the
function.
GOTO
Does transfer the control of execution to a specified label.
can be used both non conditioned form or calculated form;
the last one selects a label from a ordered labels list.
IF
Performs an instruction if the logic condition in TRUE.
OFFERROR
Disables the errors trapping (management) set by
ONERROR instruction.
ONERROR
Permits program to manage errors trapping.
The program is stopped immediately when detects the
specified error and restarts at the instruction following the
error label.
RETURN
Completes the execution of a function internal to program or
subroutine program.
The execution backs to the instruction following CALL or
XCALL that invokes the function or the subroutine.
SLEEP
Stand by the execution for a specified number of seconds.
STOP
Finishes the execution of current program.
Are foreseen two forms: one unconditioned, that backs the
control to system control, the other one is a linking form that
backs the control of execution to another program.
XCALL
Transfers the execution control to a subroutine program
external.
DELETE
Deletes a record with key from a ISAM file.
DISPLAY
Writes on file a sequence of one or more characters
(generally on terminal)
FIND
Detects the position of a record in file ISAM to be next
record read by instruction of READS.
FORMS
Controls line or page shift on output file (i.e. printer)
GET
Gets a fixed length binary record from a specified point of
file.
This is an operation binary that is not giving importance to
ASCII characters received.
GETS
Is similar to instruction GET except that the access is
sequential
instead of casual. The record follows immediately last
information exchanged with the files.
OPEN
Connects an I/O device to the internal channel HBL.
Once that this association is done, the instructions of I/O can
work in this channel till done CLOSE or till program ending.
PUT
Writes a binary record of fixed length in a point of file
specified. This is an operation of binary writing and no
record terminator is affixed (unlike of WRITE)
PUTS
Is similar to instruction PUT except that the access is
sequential
instead of casual. The record is placed in file in the current
position.
READ
Obtains a record ASCII of variable length, from a specified
point of file. The information is accepted until encounters a
record terminator.
READS
Is like the instruction of READ not including that the access
is sequential instead of casual. The record follows last
information exchanged with the files.
READB
Is valid only for files ISAM, does permit to read sequentially
backward. It gives back the record previous to last
exchanged
with the files. This instruction is not in DIBOL-11
RECV
Receives a queued message by an instruction SEND
previously
executed by current program or by some other program in
the same session.
SEND
It does put a message in queue. We can get it later by
instruction: RECV.
STORE
Memorizes a record into a file ISAM based on one or more
keys
that are internally to the record.
UNLOCK
Unlocks blocked records (automatically) from the current
program.
WRITE
Transmits a record ASCII of variable length to a point
specified
of file. The information transmitted is affixed with a record
terminator.
WRITES
Is like WRITE instruction except the access that is
sequential. The record is inserted in file after last record
exchanged with the files.
0 !+ 3
K
2.4. Format of Instruction Lines
Because is not practical to work with lines over 120 characters (80
for the majority of CRT terminals), some time is necessary use lines of
continuation to split a logic line of instruction to shorter physic lines.
The compiler manages a physic line and all the succeeding lines as a
logic line.
.
An instruction line HBL can be broken in more consecutive parts.
The second part and next are called continuation lines and they start
by
“e commercial” (&).
On to improve the reading, blank and tab can precede the symbol &.
For example:
Instead:
LBL02, GOTO(YSC01,YSC02,
&YSC03,YSC04
&),K ; Depending on K
LBL02, GOTO(YSC01,YSC02,YSC03,YSC04),K
All the characters that are following the symbol &, except the
comments
at end line, are considered part of the instruction.
Space e Tab
KSeparators;
Apex single
The alpha constant are delimited by single apex, open and
closed. The constant alpha value is the whole sequence of
characters between the two limiters.
Semicolon
When semicolon (;) is used external to a constant alpha it
does indicate the end of instruction contained in that line and
the beginning of comment.
All the information from (;) to the physical end of line are
showed in the program list but they are ignored by the HBL
compiler.
Dollar Symbol
The first character of all the identifiers must be alphabetic, with the
exception of names for intrinsic functions that have to initiate by ($)
symbol or (%) symbol.
Examples of identifiers are: NFIRST, NLAST, TRX.
KIdentifiersi;
2.6.1. Key Words
Inside of Data Division, the numbers indicate the extent of data field.
.
Is possible declare field of decimal data that contain more than 18
digits
and they have initial values bigger than 18 digits.
However if in the calculation is used a field with a value exciding
the 18 digits significant, will be given the error of “Number too big
[#15]”,
K Data Types;
that means the number is too long.
Data decimal field are not checked when the records are obtained
from data files; they are checked any time they will be used for
calculations or
as sources of instructions to assign from decimal to alpha or vice
versa.
If characters not numerical are present in a instruction for assign
from decimal to decimal, is generated an error of: “Wrong digit on
variable [#20]”
Because decimal data fields are including entire values, the
programmer
has to be sure that the data are correctly formatted and regulated
during arithmetical calculation.
In example c, the limiter appears at the end of the constant, then occur
specify one more limiter to close the definition of constant.
Sometime is more convenient to split alpha constant in smaller
physical parts.
KCostant;
2.8.2. Constant Decimal
KVariabili;
An indexed variable is referring to an element individual inside of a
list of elements. The name of variable is followed by value of index
contained between round brackets.
The index can be an expression decimal bigger than 0 and defines
the element of list to which we want get in.
For example index to 1 represents the first element of the list.
Any variable can be indexed but his memory area must be inside of
the area data accessible to program.
If area data isn’t accessible or if the value of index is smaller of 1,
there will be error:” wrong index [#7]”.
To better understand how the indexed variables are functioning and the
difference with dimensioned array, see the following example:
Considering the following instruction of Data Division:
RECORD DEMO
ALPHA, 3D4 ,3 ,9876 ,4321
BETA, A6 ,'ABCDEF'
GAMMA, D3 ,545
DELTA, 4A2 ,'LM' ,'NP' ,'RS' ,'TV'
ALPHA(1) 0 0 0 3
(2) 9 8 7 6
(3) 4 3 2 1
BETA A B C D E F
GAMMA 5 4 5
DELTA(1) L M
(2) N P
(3) R S
(4) T V
DEMO 000398764321ABCDEF545LMNPRSTV
ALPHA 0003
ALPHA(1) 0003
ALPHA(3) 4321
ALPHA(4) ABCD
ALPHA(5) EF54
BETA(2) 545LMN
GAMMA(ALPHA(1)) PRS
DELTA(4) TV
DELTA(-3) Indexing wrong
ALPHA (4) e ALPHA (5) are both valid references because they are
not extended out of total data space allocated by instructions of data
division;
DELTA (-3) is not acceptable because is not expected a reverse
indexing.
Note that BETA and GAMMA can be indexed even they are simple
variable. BETA (2) is referred to the second group of 6 characters after
beginning of area data of BETA (6 is the extent of single data BETA).
2.9.2. Interval Absolute
RECORD ABS
DFLD, D8 ,10203405
AFLD, A13 ,'ABCDEFGHIJKLM'
DFLD(2,4) 020
ABS(8,13) 5ABDCDE
AFLD(3,6) CDEF
AFLD(DFLD(2,3),DFLD(7,8)) BCDE
AFLD(DFLD(2,3)+2,5) DE
AFLD(13,14) MA
DFLD(6,3) Indexing wrong
2.9.3. Variables indexed Differed
This form permits to refer a field defining his ordinal position inside
to a RECORD, respect to a field “PIVOT”.
We can combine this index by one of the two methods seen
previously.
RECORD ABS
DFLD0, D1 ,9
DFLD, D8 ,10203405
AFLD, A13 ,'ABCDEFGHIJKLM'
DFLD1, D5 ,60708
KDATA DIVISION;
Under this instruction we can combine the fields that allocate memory,
with fields that define only the address of other field and are defined in
other RECORD.
3.1.1. Record
KRECORD;COMMON;GLOBAL SECTION;OVERLAY;VIRTUAL;
This way is used overall in the I/O operations to exchange records in
a data file.
Note that, when we refer to a record in an instruction of Procedure
Division, it’s treated as a variable alpha.
3.1.1.1. Local Record
The main program linked with subroutines may have or not have
necessity of data in common.
Despite of it the main program must contain the instruction
COMMON
to define the co division of data areas, because the memory is
allocated during the compilation of instruction COMMON of main and
because COMMON in a subroutine is referring only to the memory
areas declared in main.
Because the calling module is not interested to the content and to the
disposition of global areas, the changing of these areas does not
requires
to modify any main that uses them.
3.1.1.4. Record Overlay
This cause the field definition following the indicator of filling to refer
to memory area defined in overlay record more recent.
RECORD REC1
A, A5
B, A18
RECORD REC2,X
C, A2
D, A3
RECORD REC3,X
E, A23
COMMON CMN1
CA, A4
CB, A5
COMMON,X
CC, A2
In these views, for example, we can insert values coming from another
trace record, blank selectively fields define a trace of print and edit.
To the virtual records, more than the restrictions indicated for record in
overlay, are added the following restrictions:
RECORD
BETA, D5,12345
DELTA, A8,'paperinò
UA30, A30
VRECORD VREC
ALFA, A10,'ABCDEFGHIJ'
IND, D5 @BETA
GAMMA, D8,87654321
INDA, A6 @DELTA
Riference Content
VREC ABCDEFGHIJ1234587654321paperi
IND 12345
INDA paperi
ALFA(2:) 12345
3.1.2. Fields
The fields are the components of record, and any record contains one
or more field.
The field can be located w/out name (FILLER), and in this case
occupe only the record space or can be variables with name taht
allocate the value of data used for program execution.
The fillers can be used when a record has many fields but a module
of program uses only a little sub assembly of field of that record;
in this case can be called only the fields used.
The fields adjacent, that are not used, are generally grouped in single
field of fillers that are shortening the definition of record, but they have
the effect to not document completely the structure of whole record in
list of program.
3.1.3. Array
The structure record often require particular field that occur many
time, and any occurrence represent an element separated of data.
When a field is defined with more than one occurrence, it’s named
array.
The memory area allocated to array is the product of number of
elements
defined and magnitude of a single element.
RECORD
ARRAY1, 4A6 ,'ABCDEF' ,'GHIJKL'
&,'MNOPQR' ,'STUVWX'
ARRAY2, 3D3 ,123 ,4 ,789
The space of memory will be allocated as follow, from left to right and
from above to below:
ARRAY1(1) A B C D E F
(2) G H I J K L
(3) M N O P Q R
(4) S T U V W X
ARRAY2(1) 1 2 3
(2) 0 0 4
(3) 7 8 9
ARRAY1(1) ABCDEF
ARRAY1(3) MNOPQR
ARRAY2 123
ARRAY2(7,7) 7
ARRAY1(ARRAY2(6,6),12) DEFGHIJKL
3.1.4. Memory of Work
Any definition of field specifies the behavior of a single field, and all the
field definitions are giving the disposition in memory of record.
.
he format to define a simple field is the following:
where:
name is optional name used to refer to space of field memory.
dim is a constant decimal optional, named field dimension, and indicates how
many times the field is repeated (default 1).
The presence of this specification of dimension indicates a simple array’
type is “A” for alpha, “D” for decimal and “I” for binary.
If the dimension was not specified, the length should be a constant decimal
positive.
In case of variables “I”, do not specify the length because is fixed to 4 byte
(32 bit).
pos (optional), indicates a field that is pointing to another field, specifying
Kfields;
eventually an offset.
In this case the field will not reserve memory for the current record, but will
define in alternate a field previously declared.
Similarly for Overlay fields, is not possible specify an initial value for this
kind of fields.
value initial
is the assemble of initial values that are assigned to succeeding
occurrences of field.
This specification is optional and is described with further details
here below.
The initialization of binary fields must be executed as decimal
operation.
RECORD
, A3 ,'XYZ'
INVAL, A20 ,'initial Value’
FLD1, 2D7 ,123 ,987
DATA, D6 ,10394
MESE, D2 @DATA ; punta a '01'
GIORNO, D2 @DATA+2 ; punta a '03'
ANNO, D2 @DATA+4 ; punta a '94'
INDEX, I
DATA= DATE
MESE= MONTH
GIORNO=DAY
ANNO=YEAR
punta a = point to
0 !+ 3
K
3.3. Specification of Initial Values
KValori Iniziali;
Considering the following instructions of Data Division:
RECORD
F1, A30
F2, A15
RECORD ,X
FO1, A5
FO2, A3
The fields F1 and F2 can have initial values, because are part of
declaration of a record not overlay.
Then these fields prepare the space in memory to be allocated.
The fields FO1 and FO2 cannot have initial values, because are in the
declaration of an overlay record;
They can only specify an alternative mode to see the previous memory
space allocated.
The memory areas GLOBAL are not directly associated with any
module.
For that reason, generally, the definition of records GLOBAL doesn’t
permit initial values.
KRECORD;
The following example defines an area local of 35 characters and a
global area named GBL of 11 characters.
Local area consists of one local record named REC1 (21 characters)
and
of a record w/out name (14 characters).
RECORD REC1
ALFA, A13 ,'Valore inizialé
BETA, A2
GAMMA, D6 ,975126
RECORD ,X
R1FLD1, A3
R1FLD2, A7
RECORD R1,X
R2FLD1, A5
R2FLD2, A1
RECORD
XX1, A7
XX2, D7 ,11765
RECORD OVR,X
XX1OVR, A3
XX1END, A4
KCOMMON;
In the example here below are created two areas record called CMN1
(10characters) and DEMO (51 characters).
DEMO is the area of a local record with two overlays called TYPE1
and TYPE3 and a overlay common called TYPE2.
COMMON CMN1
CMN1A, A5 ,'abcdé
CMN1B, D5 ,12345
COMMON OVR1 ,X
COVR1, 5A1
COMMON ,X
, A5
OVR2, 2D2
RECORD ,X (!! ERROR)
, A5
DIGITS, A5
RECORD DEMO
TYPE, D1 ;area I/O
, A50
RECORD TYPE1 ,X (!! ERROR)
, A1 ; first tipe of disposition
FLDA1, A5
FLDA2, A6
FLDA3, 3D7
COMMON TYPE2 ,X
, A1 ; second type of disposition
FLDB1, A7
FLDB2, A9
RECORD TYPE3 ,X (!! ERROR)
, A1 ; third type of disposition
FLDC1, A1
FLDC2, 5D2
KGLOBAL;
The following is a simple section of GLOBAL:
VRECORD [nome]
definition of field 1
.
.
.
definition of field n
KVRECORD;
PIVA, A11 PIVA ?
DARE, D11 GIVE
AVERE, D11 HAVE
SALDO, D11 BALANCE
;
VRECORD RSTAM
, A1,'!'
PROGR, A5 ; Progressive of print
, A1,'!'
, A30 @NOME
, A1,'!'
, A20 @CITTA
, A1,'!'
, A20 @INDIR
, A1,'!'
Note that the names of field VREC are omitted because are not essential to
the purpose.
0 !+ 3
K
3.8. Instruction SUBROUTINE
SUBROUTINE subname
definition of argument 1
.
.
.
definition of argument n
In the above definition, “subname” is the name by which the subroutine should be
called
(to using instruction XCALL).
The compiler will recognise only the first 5 characters of name and will ignore the
remain.
Is not necessary to define the arguments if subroutine and program have no needing
to exchange information between themselves.
How ever, if the arguments are defined, any definition must include the name that
subroutine uses to refer to argument and the type of argument (alpha:[A},decimal:[D]).
The instruction XCALL in calling program can’t contain a number of arguments
bigger than those declared in instruction SUBROUTINE, otherwise we’ll get error:
“Number argument XCALL wrong [#6].
It’s possible that the instruction XCALL in the calling program has less arguments
of those declared: in this last case the subroutine can’t utilize in input nor in output
the arguments that are not passed.
The calling program may have as arguments both variables and expressions.
KSUBROUTINE;
During the execution, for any variable is created a pointer, that will be used to
access variable when the subroutine refers to that argument.
When the subroutine try to modify the value, a control assures that the argument has
not constant nor expression; if this happens, will be given error of “Writing on literal
[#8]”.
Over arguments is not executed a control of type. So that, a subroutine may define an
argument of type alpha, and the call specifies instead a variable decimal for the same
argument in instruction XCALL.
The instruction SUBROUTINE defines the types added by arguments, but does not
control their length; it is the specified argument to determinate the length.
The length can change at any call to subroutine, if the call uses different variables as
argument. If subroutine tries to go out the memory area of arguments, is signaled a
“Indexing error [#7]”.This can happen only by indexed access or interval to argument.
Note that this access can refer to information not requested if the length of argument
is not the same of the one expected by the subroutine.
The example here below contains a subroutine that wait for argument long at least 10
characters; Is showed what happens when the call specify an argument shorter than
the one expected by subroutine.
Considering the following subroutine:
SUBROUTINE ROTAT
;
; Rotate to left the first 10 characters of WHAT
;
WHAT, A
RECORD
FIRST, A1
PROC
FIRST = WHAT(1,1)
WHAT(1,9) = WHAT(2,10)
WHAT(10,10) = FIRST
RETURN
END
If the calling program has only the following instructions of Data
Division:
RECORD
FLD1, A10 ,'abcdefghij'
FLD2, A9 ,'123456789'
RECORD
FLD3, A2 ,'xz'
XCALL ROTAT(FLD1)
XCALL ROTAT(FLD2)
XCALL ROTAT(FLD3)
KPROCEDURE DIVISION;
0 !+ 3
K
4.1. Expressions
An expression is a combination of elements of data (called operand)
and arithmetical operation that produces an unique value.
The expressions HBL are both arithmetical and conditional, and
depending on interpretation of expression value.
If the value is interpreted as decimal number, the expression is
arithmetical;
If the value is interpreted as TRUE or FALSE, the expression is
conditional.
The simplest form of expression contains a single constant or
arithmetical
variable w/out operators.
The programmer can make expressions complex by using operators to
combine various kind of operands
The operators “unary” act only on a single operand and must stay
in left side of the expression;
Binary operand act on two operands and are inserted between the
operands.
Two operators cannot stay adjacent.
Simple examples of expressions valid are:
X - Y * 73/T
ALFA - (BETA.GT.GAMMA)
SINGLE
(VARO1.NE.'Abort').AND. (VARO1.NE.'Destruct')
KEspressions;
4.1.1. Operands Available
The operand gives data base for the expression value. In one
expression can be used the following kind of operand:
.
The programmer can make expressions complex how much he wants by
using the four kinds of operands.
Generally the brackets are not requested to evaluate correctly an
expression;
However, they are necessary if the evaluation order is going to be
distorting; they can also be used to document the evaluation order that
we want for a complex expression, or to make easier determinate the
sequence of evaluation of an expression in the next reading of program.
Some operations impose restrictions about the type of data of their
operandi;
GT.Requires that both the operands must be of the same type;
So that is not allowed to relate an operand alpha to an operand
decimal.
Where there is restriction, it must be respected.
To be noted, anyway, that the compiler will not give error, when done
relation between operandi of different type, because, is possible evaluate
the string null and this one will be understood as TRUE or FALSE.
In example:
ALFA.GT.5
Is interpreted as:
(ALFA.NE.<blank>).GT.5
That is correct syntax (see 4.1.3).
4.1.2. Operators Availabe
When two or more operators with the same priority are adjacent, they are evaluated
from left to right.
So that, A*B/C is evaluated multiplying “A” by “B” and dividing the result by “C”.
Some time the normal priorities associated to operators are modified. In example, if
the programmer wants do the following equation:
A+B
-------
C-D
The expression is written as A+B/C-D, the priorities of operators said that the division
should be executed at first. The value resulting is calculated as the function is written:
B
A + --- - D
C
The only way to give a correct order of evaluation is to using the parenthesis, writing
the equation as (A+B)/(C-D).
A balanced assemble of brackets elevate the expression that is enclosing a higher
level of priority.
For example, if the priorities are numerical values assigned from 1 to 19, an
assembly
balanced of brackets creates a new priorities assy from 11 to 19,
(Anyone of these is higher than any normal priority).
Any assemble of parenthesis repeated elevate the priorities (with an increase of 9 in
our example).
A + B * (C - (D + E)/(F * (G - H)) + I)
The factor “G-H” is evaluated for first because it is closed by the most internal
brackets.
Assuming that the variables have the following values:
A = 10 B = 30 C=5 D=2
Expression Result
A+B / C*D 22
A + B / (C * D) 13
(A + B) / (C * D) 4
The variables and constant alpha are permitted as operand only when are used with
the operators relational (that is EQ., .NE., .GT., .LE., .IN.).
The operators of relation request that both the operands are of the same type.
The operands decimals are compared like in the standard arithmetic; the operand
alpha
are compared by use the order of characters of assemble of code ASCII (NULL is
the character with the lowest order).
Consider the following expressions:
Expression Result
If the alpha operands differ in length inside an expression, only the characters of the
shortest operand are compared, and the additional characters of the longest operand
are ignored.
The operator “LIKE” can be used only in variables alpha and it permits to compare
with a masck, that is a string containing characters “jolly”as the regulation of “shell”
of UNIX:
Of both strings, is analyzed only the significant part excluding the final blank.
Examples:
Expressions Result
Because HBL uses the context of an expression to rule how his result
should be interpreted, the variables decimals or alphanumerical can be
also used like expression conditionals.
I.E. the instruction IF can easily test the status null/not null of the
variable, and use the result of this test.
For convention, the variables alphanumerical are considered NULL,
when they contain only blank (code ASCII=32).
Assuming that: the subroutine CHECK is responsible for control of
data fields, and is ensuring that their values are inside of a pre-
established interval.
Assuming also that CHECK has a variable settled to zero as first
argument, if the interval is not accessed, or is settle to 1 on the
contrary,
the following instruction will call the subroutine, and in base to the
error flag, will address the execution in a side of module that is
controlling the errors:
XCALL CHECK (FLAG, VAR1, VAR2, VAR3)
IF (FLAG) GOTO OOPS
The operator division in HBL divides in base of the type of data that
are manipulated.
Because of HBL does not allow the type decimal with fix dot,
when we divide two data decimal, the value of variable will be
truncated during every operation.
For example, 17 divided by 2 give as result 8; the fraction part (0.5) is
truncated.
0 !+ 3
K
4.2. Functions Intrinsic
4.2.1. $ERLIN
Returns the line’s number of the instruction that cause the error
trappable most recent.
The number of line of any instruction appears on program list made
by command “hbd-1”.
4.2.1. $ERNUM
Returns the code number of the most recent error that can be trapped.
If the program provides the trappable errors management (i.e. with
ONERROR), the value that is back by $ERNUM can help the program
to
differentiate various trappable errors, in the way that each error can be
treated appositively.
4.2.3. $LEN
Backs the area length of the memory referred to the argument
specified.
$LEN is used to develop subroutines to treat arguments with variable
length, because often is necessary to know the length of an argument in
subroutine to control the elaboration of his content.
For example, $LEN can help in a subroutine doing the grammatical
KFunctions Intrinsic;$ERLIN;$ERNUM;$LEN;$RDLEN;
analysis to an argument alpha, to decode a command line.
RECORD
AA, A10 ,'abcdefghij'
BB, D6 ,102507
CC, D1 ,4
Function Length
$LEN(AA) 10
$LEN(AA(5,7)) 3
$LEN(AA(5,6)) 2
$LEN(AA(BB(2,3),CC) 3
4.2.4. $RDLEN
Give back the length of the last record read, by using an instruction of
READ, READS, GET or GETS.
Example #1:
LOOP,
DISPLAY(15, 'Insert next command: ')
READS(15, INPUT)
IF ($RDLEN) GOTO VRDL
WRITES(15, 'Input null ignored’ )
GOTO LOOP
VRDL, BUF(1,5) = $RDLEN , "ZZZZX'
DISPLAY(15, "The length is : ", BUF(1,5), 13, 10)
WRITES(15, INPUT)
Example #2:
SUBROUTINE ROTAT
;
; Rotates to left all characters of WHAT.
; Is used the function $LEN because there’s no way
; to know the length of WHAT before.
;
WHAT, A
RECORD
FIRST, A1
PROC
FIRST = WHAT(1,1)
WHAT(1, $LEN(WHAT)-1) =
WHAT(2,$LEN(WHAT))
WHAT($LEN(WHAT),$LEN(WHAT)) = FIRST
RETURN
END
0 !+ 3
K
4.3. Instruction of Assignment
destination=source
ALFA = ALFA * 3
KInstruction of Assignement ;
4.3.1. Assignment from Alpha to Alpha
Quando la destinazione é una variabile alfa e la sorgente é una
variabile o una costante alfa,
When the destination is a variable alpha and the source is a variable
or a constant alpha, the instruction of assignment copies the information
from an area of memory to another area.
I f the source is shorter than destination, the information of source is
loaded in destination by a justification from left and by characters blank
(That is the source is loaded starting from left and exceeding space
is filled by characters blank).
If the source is longer than destination, only the characters that stay
more in left side of source are copied in destination.
Assuming the following instruction of Data Division:
RECORD XYZ
ABC, A6 ,'ABCDE'
DEF, A2 ,'XY'
RESULT, A4
RECORD
RESULT, D6
AFLD1, A7 ,'-1-2-3'
AFLD2, A10 ,'1234567890'
RECORD
RESULT, A6
DFLD1, D3 ,-23
DFLD2, D6 ,-123456
[LEFT <:dvar>]
and:
[RIGHT <:dvar>]
ALFA = 12345
ALFA = 12345 [RIGHT]
ALFA = 12345 [RIGHT:VAR]
The first two instructions are not determinate the value to VAR, but
the third assigns to VAR the value 5, because the loaded value is
“12345”
ALFA = 12345 ,'ZZ.ZZZ,ZZ-'
ALFA = 12345 ,'ZZ.ZZZ,ZZ-' [RIGHT]
ALFA = 12345 ,'ZZ.ZZZ,ZZ-' [RIGHT:VAR]
Example:
KDescription of instructions;
0 !+ 4
K
4.4.1. ACCEPT
The instruction ACCEPTS receives a character from the channel
specified and loads in the specified variable the read character or the
decimal value.
Sintassi:
Where:
Channel is an arithmetical expression specified by channel HBL from
which we obtain the character.
KACCEPT;
an end-of-file, will be loaded his equivalent decimal [26 for control/Z
(systems MS-DOS), 4 for control/D (systems UNIX)].
Label is an optional label to which the control is transferred if the
variable is alpha and if is received a character of end-of-file.
The label has no meaning in ACCEPT with variable decimal.
Example:
ACCEPT(12, AFLD)
Receives the next character from channel 12.If the character is a signal
of end-of-file, the program terminate by a message error “End file
[#1]”.
Is modified only the character more at left of AFLD; The other 4
remain unaltered.
Also this instruction receives the next character from channel 12.
If the character is a signal of end-of-file, the control is transferred to
the instruction labeled DONE.
Receives the next character from channel 5.The label END is ignored
because DFLD2 is a variable decimal; If the character is a signal of
end-of-file, no special treatment will happen. Note that to DFLD2 is
assigned the value that correspond to character ASCII received.
ACCEPT(3, DFLD1)
Special Notes:
Because of Accept is an operation of input having only one character,
there will be no special treatment to terminate record (as mainly
happens in other operation, like READS).
The programmer has to put those characters by himself. ACCEPT is
often used to receive a character from a terminal device.
To conciliate the operating systems in which HBL runs, when the
operator
push the button RETURN, are generated the carriage return and the line
feed. The program should provide the control for both of them.
0 !+ 4
K
4.4.2. CALL
Syntax:
Form unconditional:
CALL label
Where:
Label is the label specified to which the execution control is transferred.
KCALL;
with the instruction following the CALL.
Examples:
SELECT = 2
CALL(ZAPPER, ZINGER, ZANY), SELECT
. <------- point “A” of return
.
.
.
ZINGER, AGEDATE = DATE(TYPE)
.
.
.
CALL INNER
. <------- point “B” of return
.
.
.
Syntax:
where:
var_1
.
.
var-n are variables alpha or decimals. An instruction CLEAR can
include
different kind of variables.
Examples:
Assuming that Data Division has the following instructions:
AVAR, A1
DECVAR, 3D1
Then,
CLEAR AVAR
is working as:
KCLEAR;
end:
CLEAR DECVAR
works as:
DECVAR(1) = 0
Note that in the last example only the first element of array is
initialized.
0 !+ 4
K
4.4.4. CLOSE
CLOSE channel
Where:
Channel is an expression arithmetical, his value specify the channel of
files
that will be closed.
Discussion:
Se il canale é aperto in modo output (O o U), tutti i dati contenuti nel
buffer di I/O saranno scritti prima che il buffer sia ceduto:
If the channel is open in mode output (O or U), every data contained
in buffer of I/O will be written before that the buffer will be given:
This ensure that all the information written by program are physically
transferred to the device.
The instruction CLOSE suppresses the deleting of output files.
Note that, when a program is ended, all files open will be closed.
If the channel is open in mode update (U or U:I), all the locked record
associated to the channel will be unlocked.
Examples:
KCLOSE;
OPEN(1, 0, 'TEST') ;creates the file TEST
DECR variable
Where:
Variable is a variable decimal the value of which must be decremented
of one. The value of variable can be positive or negative.
Example:
The instruction:
DECR DVAR(2,5)
DVAR(2,5) = DVAR(2,5) - 1
KDECR;
0 !+ 4
K
4.4.6. DELETE
The instruction DELETE cancels the record most recent saved by a
file ISAM.
Syntax:
DELETE(channel, key)
Where:
Key is the value of key that identifies the record that will be deleted.
If the parameter key is not equal to the record key, currently read, there
will be error of “key not same”(#53) and the record will
be cancelled.
Discussion:
The instruction of DELETE must be preceded by an operation of
READ or READS so that a selected record can be specified to
cancellation.
To the value of a single key can be referred more records different in
a file that allow the keys duplication;
Then, there’s no way to specify a member individual of an assemble of
duplicates; for this reason the program must use the instructions of
READ or READS, on to determinate which particular record he has to
cancel.
After that record was determinate, it can be cancelled by instruction
DELETE.
KDELETE;
EXAMPLE:
RECORD REC
DATA1, A30
KEY, A16
DATA2, A25
RECORD
IO, A20
PROC
OPEN(15, I, 'TT:')
DISPLAY(15, IO)
OPEN(1, SU, IO)
LOOP,
DISPLAY(15, 'key: ')
READS(15, IO, DONE)
READ(1, REC, IO)
DISPLAY(15, 'Data: ', REC, 13, 10
& , 'should I cancel this record? ')
READS(15,IO)
IF (IO.EQ.'S') DELETE(1, KEY)
GOTO LOOP
DONE,
CLOSE 1
STOP
END
0 !+ 4
K
4.4.7. DISPLAY
The instruction DISPLAY sends an output of characters to a device of
valid output or to a file, through the name of channel.
Because the output isn’t a record, the system of runtime doesn’t put a
terminator of record. If anyway this terminator is necessary, the
program must indicate it in instruction DISPLAY.
Syntax:
Where:
Channel is a decimal expression whose value specifies the channel of
device of output or of file. The channel must be open in
mode OUTPUT.
List is a list of variables alpha or decimal whose values represent the
characters that will be sent, optionally inter-placed with functions screen
(will be showed next session).
All the elements of list are separated by a comma. The elements of list
are processed in the order in which they are specified.
Discussion:
I f the instruction DISPLAY contains elements of list type alpha, the
sequence of characters of those variables is transmitted directly.
For elements decimal of list, is transmitted the character ASCII
correspondent to decimal value. If the value is bigger than 256, the
character transmitted is the character associated to the rest of division
value for 256.
For example, if value is 321, will be transmitted the character ASCII
“A”
KDISPLAY;$SCR_POS;$P;$SCR_CLS;$C;$SCR_ATT;$A
(The decimal 65).
Instruction DISPLAY is used generally to control terminal screens.
The special functions (i.e. cancel screen CRT and addressing of cursor)
depend of the terminal that should be controlled;
for this reason they are made by transmitting sequences of functions
with multiple characters.
These sequences start by a guide character, that is telling to terminal
that the information following is a special function requested and not
the text to visualize.
Different kinds of terminals, to indicate similar functions, use different
initial characters, as also different sequences of characters.
However, many use the character ASCII ESC as initial character.
To determinate what are the correspondent sequences, we should refer
to spec. of programming given by the maker.
Examples:
The attributes of first group (with tag) are available on a biggest number
of terminals, because provide to reserve a pos. of video (named tag) to
indicate
start and end of an attribute (see Ampex 210 and others).
Black 10+BLACK
Red 10+RED RED
Green 10+GREEN GREEN
Brown 10+BROWN BROWN
Blue 10+BLUE BLUE
Viola 10+VIOLA VIOLA
Ciano 10+CIANO CIANO
White 10+WHITE WHITE
Syntax:
where:
Channel is an expression decimal whose value specifies the channel of
file
needed. The channel should be already opened in mode INPUT (YES)
or UPDATE (ON)
.
key-id indicates in which record will be read an instruction of
sequential reading (READS).In practice, it’s the value of
key field of record designed. If the key value is longer of
key field, will be used only the first part of key value. If
the key value has length less than key field, is named
“partial key”, and the system takes position on first record
whose key start by the specified value. If there are not
fields whose value starts by key values, will be positioned
in the first record with the highest key value and show
error “key not same[#53]”.
KFIND;
keyref is an expression decimal that specifies an explicit key of
reference.
The value zero specifies the primary key, value 1
specifies the first key alternative, etch.
If is not specified a reference key, for default is
considered primary key (KRF=0)
FORMS(channel, control)
Where:
channel is an expression arithmetical whose value specifies the channel
of device to which send the codes of control.
The channel should be already open in mode
OUTPUT.
Discussion:
KFORMS;
Examples:
Where:
channel is an arithmetical expression that specifies the channel of source of binary
data.
the channel should be already open in mode INPUT or UPDATE.
area-data is the variable alpha that will receive the input characters. The length of
area-data determinates the number of characters that will be obtained
by GET.
If the file contains few characters from a record position called at the end, it will give
error”End file(#1)”.
Discussion:
The instruction GET is one of the 4 instructions of I/O binary that support HBL.
The other 3 are GETS,PUT and PUTS.
These instructions don’t interpret the character during I/O.Any characters is assumed
to have value of 8 bit. During the process of I/O, the terminators record are not
automatically connected or disconnected.
The program maintains the control of file output content and can control any
characters of input files. If an instruction GET is referred to a channel opened to a
KGET;
sequential device (i.e. terminal or writing line), is given error of “Mode OPEN
wrong”(#21).
Examples:
Assuming the following instruction of Data Division:
RECORD
AREA1, A38
AREA2, A1967
AREA3, A5
Reads the 123rd record (that is the 123rd group of bytes), from 38 byte each one
from channel 1.
If in channel 1 are remaining less than 123 records (each 38 byte), the program will
end by error “(End file”(#1).
Reads a record of 1967 byte whose number is given by RECNO,and the record is
read by channel named CH.If the record goes over the file end, is given an error.
0 !+ 4
K
4.4.11. GETS
Syntax:
The instruction GET does an input binary with sequential access.
No special meaning is attributed to characters.
The record terminators are treated as ordinary data.
Where:
channel is an arithmetical expression that specifies the channel of
source of input data. The channel should be already open
in mode INPUT.
area-data is the variable alpha that will receive the input characters.
The legth of area-data determinates how the characters will be received.
For example, an area data of 623 characters will read next 623
characters.
If the file contains few characters, is given error “End file(#1).
Discussion:
KGETS;
control any characters of input files.
When the channel is connected to terminal, the instruction GETS is
similar to READS, with this exception: when a character not terminator
overcome the area data receiving, the instruction READS produces the
character ASCII BELL to signal operator and ignore the character. The
instruction GETS instead, overcoming the length area data, backs
immediately and will not visualize any of the characters put in.
Examples:
Assuming the following instructions of Data Division:
RECORD
AREA1, A38
AREA2, A1967
AREA3, A5
GETS(1, AREA1)
Reads the next 38 characters from channel 1.If on the channel are remaining less than
38 record, the program stops by error “End file (#1).
Reads the next 1967 characters of called channel CH. If remain less than 1967
characters, the control is transferred to an instruction labeled by YUK.
0 !+ 4
K
4.4.12. GOTO
The instruction GOTO transfers the control of execution to a specified label. The
form unconditioned specifies only one label; the form calculated, instead, specifies a
list of labels and selects the expression whose value indicate the wished label.
Syntax:
Form unconditioned:
GOTO label
Form calculated:
GOTO(lista_label), selettore
Where:
label is a label of some part of program. The control of execution is transferred
immediately to the called label.
list_label is a list of labels, each of them are separated by a comma. The first label
corresponds to 1, the second to 2, and so by the way.
selector is an expression decimal whose value selects the elements of list_label. If the
value is minor than 1 or bigger of the number of elements in the list,
no one element is selected and the instruction continues with the instruction that
follows GOTO.
If the selected value is included between one and the number of elements of list,
the corresponding element is selected, and the control is transferred immediately to the
label called.
KGOTO;GO;TO;
Examples:
Considering the following program:
RECORD
INPUT, A5
DECML, D5
PROC
OPEN(15, 0, 'TT:')
LOOP, DISPLAY(15, 'Number of label: ')
READS(15, INPUT)
DECML = INPUT
GOTO (Y01, Y02, Y03), DECML
WRITES(15, '... no branches selected )
GOTO LOOP
If the value of DECML is 1, the control of program jumps to instruction labeled with
YO1;if is 2 or 3, the control is transferred respectively to labels YO2 and YO3. Any
other value cause the signal: “…no branches selected”.
0 !+ 4
K
4.4.13. IF
Syntax:
IF ( condition ) instruction
Where:
KIF;
0 !+ 4
K
4.4.14. INCR
Syntax:
INCR variable
Where:
Discussion:
Examples:
INCR DVAR
INCR DVAR1(D3)
KINCR;
0 !+ 4
K
4.4.15. LOCASE
The instruction LOCASE converts the capital characters in small characters. More to
convert the alphabet letters, the instruction converts also the special characters listed
below in section “Discussion”.
Syntax:
LOCASE variable
Where:
variable is a variable alpha containing the characters that must be converted.
The whole sequence of characters is analyzed and any character is converted in small,
if is alphabetical, or in one of the following special characters:
Discussion:
Capitals Small
@ (064) ` (096)
[ (091) { (123)
] (093) } (125)
\ (092) | (124)
^ (094) ~ (126)
Example:
RECORD
FLD1, A14
PROC
FLD1 = 'JUST A [DEMO].'
KLOCASE;
LOCASE FLD1(4,11)
LOCASE FLD1
STOP
JUSt a {demO].
just a {demo} .
0 !+ 4
K
4.4.16. OFFERROR
Syntax:
OFFERROR
Examples:
KOFFERROR;
0 !+ 4
K
4.4.17. ONERROR
The instruction ONERROR reveals if there are one or more trappable errors and treats
the errors of runtime. The form allowed establishes a single point of control managed
specifying a single label to which transfer the control when found an error trappable
of runtime.
Syntax:
ONERROR label
Where:
Discussion:
When a program HBL inits an execution, all the runtime errors are considered fatal.
Than, if appear a runtime error, the program ends his execution and signals an error
message.
However, a sub-assemble of all the possible errors of runtime is considered
trappable.
(See in APPENDIX B the error list).
This sub-assemble contains all the conditions of error that program can solve w/out
stop the execution.
A program can recognize and treat any sub-assy of errors trappable defined by an
instruction of ONERROR.
When we do instruction of ONERROR, we cancel all the trappable errors of previous
execution of ONERROR;
Are defined only those created by the current execution of ONERROR.Those
trappable erors will remain till will be one of the following situations:
1. We execute an instruction of ONERROR;
2. We execute an instruction of ONERROR , causing the cancellation of
current management and creating a new management;
3. The program terminates the execution;
4.We execute an instruction of XCALL,that suspends the current
KONERROR;
operation of errors till that XCALL is ended. When the control
backs, the trappable errors are recovered.
When a trappable error of runtime happens, the runtime watches if the program has
defined his own management of error.
If not, the program will terminate whit an opportune message of error.
If the program has defined an error management, the operation that causes the error,
will not be completed and the control will be given immediately to the label
associated to error management.
After an error signal, the program can understand what’s the error by the intrinsic
function $ERNUM or asking for an XCALL to subroutine external ERROR.
The subroutine ERROR will back also the row number in which the error happened
(also the intrinsic function $ERLIN gives this information).
Examples:
Considering the following program:
RECORD
ALFA, A10
DECML, D5
ERRMSG, A40
PROC
OPEN(15, I, 'TT:')
LOOP,
DISPLAY(15, 'Insert number (1-7 ): ')
ONERROR EXIT ; for EOF, FINE
READS(15, ALFA) ;
ONERROR HBAD ; trap digit wrong
DECML = ALFA ;
OFFERROR ;
WRITES(15, '... Is valid.')
GOTO LOOP
HBAD,
OFFERROR
IF($ERNUM.NE.20)GOTO XHUH
WRITES(15, '... Not valid.')
GOTO LOOP
XHUH,
ERRMSG = $ERNUM,'Error n XX'
WRITES(15, ERRMSG)
GOTO LOOP
EXIT,
OFFERROR ;
IF($ERNUM.NE.1)GOTO XHUH ; Is not EOF
STOP
END
Note that in HBAD and XHUH, the instruction OFFERROR assures that the trappable
errors are deleted. If happens an error, the program ends.
0 !+ 4
K
4.4.18. OPEN
The instruction OPEN is the primary engine for the interface HBL and ambient, and
it’s the instruction of language HBL that more depends from system.The following
section describes the functions of this instruction.
Syntax:
4.4.18.1. channel
The channel is an expression decimal that identifies which channel HBL will be
open.
If the opening process succeeds, all the future requests of I/O will be referred to that
channel.
If during the opening process, there will be an error of “other channel in use”, the
channel specified is not assigned and stay available for use.
Are allowed the channels from 1 to 99, however, the max n. of channels that can
stay open depend of the particular operative system.
4.4.18.2. io_mode
io_mode is the mode of I/O by which the file will be open. The following modes
are possible:
I: (INPUT) permits the reading only from an existing file and accesses also blocked
records.
O: (OUTPUT) permits the generation of a writing file. If the file already exists, it
will be replaced only after the successful execution of instruction
CLOSE.
U : (UPDATE) permits the reading and writing of an existing file.The reading is
locking, that is if a program did executed the reading in mode U of the
same record, we have not the possibility to read it; in case of blocked
record, are possible two behaviours in function of assumed value of
DFLAG (see XCALL DFLAG):
KOPEN;
-The instruction doesn’t back till the record in the case is unlocked.
The record is automatically unlocked, by execution of one of following
instructions:
- WRITE of record
- READ of another record
- CLOSE channel
- UNLOCK channel
- STOP
U:R : (UPDATE, RELATIVE) permits the read-write, as in mode U,with the
possibility to append additional records to the file in queue.
SI : (SEQUENTIAL INPUT) this mode is permitted only in file ISAM and is
equivalent to mode I for file of direct access.
S : (Socket TCP/IP) this mode is permitted only on “Socket” and not on Files. The
address of sockets must be done in standard form URL:
"name_service://name_host[:number_gate]".The use of Socket is reserved to
procedures or subroutines of system dedicates to management of services
internet/intranet.
The instruction HBL OPEN was descripted in general form.Are admitted only
determinate instruction of I/O in function of mode of open as the following table (the
TT can be open indifferently in mode I or O):
┌────────────┬───┬───┬───┬───┬───┬───┬───┬───┐
│INSTRUCTION │ I │ O │ U │U:R│ SI│ SU│TT:│ S │
├────────────┼───┼───┼───┼───┼───┼───┼───┤───│
│ ACCEPT │ X │ │ │ │ │ │ X │ │
│ READ │ X │ │ X │ X │ X │ X │ │ │
│ READS │ X │ │ │ X │ X │ X │ X │ X │
│ GET │ X │ │ X │ X │ │ │ │ │
│ GETS │ X │ │ │ X │ │ │ X │ X │
│ DISPLAY │ │ X │ │ │ │ │ X │ │
│ WRITE │ │ X │ X │ X │ │ X │ │ │
│ WRITES │ │ X │ │ X │ │ │ X │ X │
│ PUT │ │ X │ X │ X │ │ │ │ │
│ PUTS │ │ X │ │ X │ │ │ │ X │
│ STORE │ │ │ │ │ │ X │ │ │
│ DELETE │ │ │ │ │ │ X │ │ │
└────────────┴───┴───┴───┴───┴───┴───┴───┴───┘
4.4.18.3. Specification of file
The file specification can be both a constant and a record name, or a field name.
It defines the file to which we’ll access during the operation of OPEN.
The form of specification of is consistent with the operating system and has
extention of default DDF.
Any other defaults are the same of usual strings of file analyzed grammatically in
the ambient. The spaces and tabs in specification will be ignored. Is possible utilize
the following notation on file name:
DIR:NOME.EXT
Where:
DIR is the name of symbolic variable defined in ambient of Operating
System.
NAME is the effective name of file, as what already discussed.
1. The factor of block of file can be shown by decimal expression as fourth and last
argument of instruction OPEN.
If we use a decimal variable instead of a constant, the variable can’t have the
same name of one of options valid for OPEN. If the names of variables are the
same, will be executed the option instead of the action of block.
OPEN(2, I, FILNAM, 8)
2. When is created the allocation initial of block for the file, his magnitude can be
closed in squared brackets and situated in the file specification after file name and
before of any qualification.
If was specified the initial allocation in an ambient MS-DOS or UNIX, we have to
choose the system option #15.
OPEN(12, O, 'TEST.DAT[150]')
--------------------------------------------------------------------------------- END
0 !+ 4
K
4.4.19. PUT
The instruction PUT executes a binary output with casual access. The content of
choosen area data is sent to the specified channel. There is not record terminator.
Syntax:
Where:
area_data is a variable alpha whose content has to be sent. The length of variable
determinates the number of characters to transmit.
In other words, the variable A623 indicates a data area to send 623 characters. If the
channel is open in mode UPDATE, a trial to exceed the physic end file will cause the
error”number record wrong [#28]”.
Discussion:
The instruction PUT is one of four instructions HBL for I/O binary; The other 3 are:
GET,GETS,PUTS. These instructions don’t interpret the characters during I/O. In fact,
any character is considered a binary value of 8 bit. In I/O process, the terminators
record
are not inserted or disinherited automatically. The program maintains the control of
content output file and can control any character in input file.
Examples:
Assuming for valid the following instructions of Data Division:
KPUL;
RECORD
AREA1, A38
AREA2, A1967
AREA3, A5
Sends the 157th group of 5 byte to channel 12.The record inits at 781st byte from
init file.
Syntax:
PUTS(channel, area_data)
Where:
channel is an expression arithmetical whose value specifies the channel of destination
file.
The channel must be open already in mode OUTPUT.
area_data is a variable alpha whose content has to be sent. The length of variable
determinates the number of characters to transmit.
In other words, the variable A623 indicates a data area to send 623 characters, and it
will make possible write 623 characters. If the output exceeds the physical max
capacity of disk, will be given error “disk space not enough [#24]”.
Discussion:
The instruction PUTS is one of four instructions HBL for I/O binary; The other 3
are: GET,GETS,PUT. These instructions don’t interpret the characters during I/O. In
fact,
any character is considered a binary value of 8 bit. In I/O process, the terminators
record
are not inserted or disinherited automatically.
KPUTS;
Examples:
Assuming for valid the following instructions of Data Division:
RECORD
AREA1, A38
AREA2, A1967
AREA3, A5
PUTS(12, AREA3)
Sends the 5 byte contained in AREA3 to channel 12. Because the PUTS permits an
access sequential, the output starts at next character of channel; that is, the character
follows last information exchanged with the file.
PUTS(3, AREA2)
Syntax:
Where:
channel is a decimal expression whose value specifies the channel of file to read. The
channel is to be already open in mode I,U,U:R,SI or SU.
record_id indicates which record will be read. For a file not ISAM the record_id is
the position ordinal of record in file; the first one has number 1, the
second has 2 and so by the way.
For a file ISAM, record_id is the key field value of record to
designate the input.
If the key value is longer than key field of record, will be used only
the first part of key value to find again the record. If the key value is
shorter than key field, it is called key partial, and system searches the
first record whose key starts with specified value. If there are not key
fields initiating by the specified key value, will back the first record
with key value higher and it will give error of “key not same” (#53).
KREAD;
Discussion:
The instruction READ searches a specified record from a file,the instruction REDAS,
instead, searches next sequential record.
For file ISAM, the specified value of key indicates which record is to be searched
(see the below examples).
Per file non ISAM, l' ordinale specificato indica quale record deve essere cercato. Il
For file not ISAM, the ordinal specified indicates which record is to be searched .The
runtime assumes that the records contained in file have all the same length of area
data searched.
Basing on this length and on the ordinal number of record to be searched, the
runtime determinates the position in file of the first character of record.
After found the init of record, is executed a normal transferring of type READS. See
the instruction READS in section 4.4.22, for details about transferring.
If the READ is used with a open channel in mode UPDATE, is on a normal control
of block of records.
So that, if READ is referring to a blocked record from some other channel, will give
an error of “Record blocked”(#40). If the program does not manage the errors, it’s
considered fatal and the program ends.
The records blocked don’t exist in mono-use and in mono-work.
Examples:
In addition of the above method above mentioned, there’s also an implicit method to
specify the reference key. If there aren’t specifications KFR, and if key field is a
variable, and the variable is inside of definition of record, that key record will be the
key ref.
For example, assuming the disposition of a file ISAM:
RECORD CUSTO
CUNUM, D5
CUNAM, A25
CUSTA, A2
, A40
Where CUNUM IS the primary key, CUNAM is the first alternative key and CUSTA
is the second alternative key.
The two following ensemble of code will be equivalent:
CUSTA = 'NY'
READ(3, CUSTO, CUSTA)
Each assemble of code will find the first record whose the second alternative key is
‘NY’.
Note that if is not present any alternative key of reference,(that is not specified any
“KRF=”),and do not exist the condition for specify reference to an implicit key, then
the READ will access to the primary key of file.
0 !+ 4
K
4.4.22. READS e READB
The instruction of READS executes an input with sequential access on the records
from selected call area data. The instruction can be used both for file ISAM and not,
to search for next sequencial record.
Syntax:
Where:
channel is an expression arithmetical that indicates the file channel to read.
label is an optional label in which is tranfered the control, if happens an error of “End
file”.
Discussion:
The instruction READS looks for next file record.For file not ISAM, with the term
“next” we refer to the record that follows phisically the read record or the most recent
written record by file. If READS is the first action of I/O of channel, the input starts
by the first character of file.
.
For file ISAM, the “next” is intended the record that is following logically the read
record most recently from file by a READ or a READS. The READS searches a
record ISAM with duplicated keys after that a READ did allocate and found the first
record of the assembly.
For file not ISAM, are transferred the characters to area_data till:
If we encountered an end-of-file or reach the max extension file, will give error
“End file [#1]”.
KREADS;READB
If the area_data is full before to encounter a record terminator, will signal “line too
long[#23]”and the input characters are ignored till we have another condition of
termination.
I f encountered a terminator of record before area_data is full; the space remaining
will be filled by blank.
To determinate the length of read record, including all characters that can be inserted
in the area_data, we can use the function intrinsic $RDLEN or the external subroutine
RSTAT.
A record terminator is a line feed or a formed or a vertical tab for all the file and
terminals.
For terminals also the character escape is considered a terminator standard. More
over, we can define till 10 characters terminators in external subroutine ACCHAR.
The record terminators end the operation of I/O and they, never, can’t be transferred
to area_data.
Note that, although they are not record terminators, the carriage return, the character
null and delete are ignored and they are not transferred in area data during the input.
For a file ISAM, being defined in phase of creation the length of each record, if the
record is bigger than area data, will be transferred only the portion more at left of the
record and will be not signal error.
If the record is smaller than area data, the record is allocated with a justification to
left by blank.
Se si usa la READS con un canale aperto in modo SU, i record vengono bloccati.
Così , se la READS si riferisce ad un record bloccato da qualche altro canale, si ha l'
errore "record bloccato [#40]";
If we use READS with a channel open in mode SU, the records are blocked. So
that, if READS is referred to a blocked record by some other channel, we get error of
“blocked rcord [#40]”,if the program doesn’t manage the errors, this one is considered
fatal end the program ends.
We can control the management of blocks using the XCALLDFLAG.
The instruction READB acts similarly to READS, but is permitted only on files
ISAM and allows to access to the record before the last read.
In this case, the condition of “end file” will happens if we try to read before the first
file record. The instruction can be used to read last file record ISAM, after is
happened the condition of “end file” by a FIND or by a READS.
Examples:
READS(12, RECRD)
It finds the next record of channel 12. If there’s no record in file or we encounter an
end-of-file, is generated the error “end file [#1]” and program stops.
More over if the length of read record is longer than the length of RECORD, is given
error of line too long [#23] and the program stops.
It’s searching for next records. However, if there aren’t records present in file, the
control is transferred to the instruction labeled DONE.
If in channel 3 is open a file ISAM in mode SU, the READS can be subjected to a
control of blocked records. In the previous case, the control is transferred to
instruction labeled with RETRY, when there are no more elements in file.
ONERROR HLAST
FIND(3, ISMREC, '~~~~~')
LOOP, READS(3, ISMREC)
GOTO LOOP
HLAST, OFFERROR
IF($ERNUM.EQ.53)GOTO LOOP ; Key not SAME
IF($ERNUM.NE.1)GOTO ERMES ; Other errors STOP
READB(3, ISMREC, EMPTY) ; Read backward
In this examples, we are positioned to last record of file ISAM, indicating, as key
with value high, presumable not existent;
if the key does exist , anyway, we run sequentially the file till encounter an error.
In the block of error control, we check if the error corresponds to “end file [#1]” and
Successively, we execute a reading backward to download last file record.
To be noted that, if the file ISAM is empty, the control will pas to instruction
labeled with EMPTY.
0 !+ 4
K
4.4.23. RECV
The instruction RECV receives a message sent by an instruction SEND previously
executed in the same or in other program. The instruction RECV can communicate
between programs
or between different terminals, or between programs concatenate executed after the
program that is sending the message.
Syntax:
RECV(message, label, [, id, length])
Where:
message is a variable alpha in which will be memorize the received message, with a
justification to left by blank. If the message received is longer than the area receiving,
only the portion of message more to left is received, the remain is ignored.
label is a label in which transfer the control if no message is available. The subroutine
external DFLAG can set the mode “wait for messag”.
Discussion:
When a message is sent by an instruction SEND, it is assigned to ID specified.
This message can be received only when the same ID is specified in instruction
RECV. If some message are put in suspend by the same ID, they are received by an
order first-in,first-out (FIFO).
If variable length has an initial value minor than 0, the instr. RECV acts in mode
not destructive; any message received is not deleted from queue of messages, so that
it can be received again.
KRECV;
If the value length is bigger or equal to zero, the message is deleted and cannot be
received again.
Examples:
RECV(MSG, NONE)
Requires receiving a message with ID “[MINE]”. If this is not present, the control
passes to NONE.
If it’s present, is received and his length is assigned to variable LNG. If the value of
LNG is initially negative, the message will not be removed from queue and other
instruction RECV with the same ID will receive the message.
Syntax:
RETURN
Discussion:
The system is capable to remember the calls succeeding to subroutines, because they
can be nestled.
The execution of instruction RETURN, permits to back to the most recent call. In the
following example is represented a section of code of program and any line is
numbered. A trace of number of lines follows in the order in which they are executed.
Example:
1 CALL SUB1
2 CALL SUB2
3 STOP
4 SUB1, CALL SUB3
5 RETURN
6 SUB2, RETURN
7 SUB3, CALL SUB2
8 RETURN
1 code of main
4 SUB1
7 SUB3
6 SUB2
8 SUB3
5 SUB1
KRETURN;
2 code of main
6 SUB2
3 code of main
0 !+ 4
K
4.4.25. SEND
The instruction SEND sends a message to program. The system saves the message
till it will be received by an instruction RECV in this or in another program.
Syntax:
SEND(message, id)
Where:
message is a variable alpha containing the message to be sent. The length max of
message depends on operative system in use.
id is a variable or a constant alpha which value contains the characters (from 1 to 6)
of name that identifies the message. Only an instruction RECV with
the same ID can receive the message. If the value of variable alpha is
longer of 6 characters, will be used the first 6 characters at left only.
Discussion:
There are two special interpretation of message ID:[SELF] and [INIT].
[SELF] makes the message ID be the name of sender program, this characteristic is
used when a program sends a message intending to receive it later.
The ID [SELF] also avoids the necessity to update the ID and assure that the sending
and receiving will function in the mode wanted. The ID [INIT] makes no messages
will be sent.
In fact, [INIT] deletes all messages pending from terminal associated to program.
Examples:
Sends the indicated message and uses the content of MSGID as ID of message.
KSEND;
0 !+ 4
K
4.4.26. SLEEP
The instruction SLEEP suspends the execution of program for the number of
second’s indicated. After this time, the execution restarts from the instruction that
follow the SLEEP.
Syntax:
SLEEP interval
Where:
KSLEEP;
0 !+ 4
K
4.4.27. STOP
The instruction STOP terminates the program execution and passes the control to
another program or to monitor.
Syntax:
STOP [program]
Where:
program is an optional variable alpha that specifies the name of program to which
transfer the control; if omitted, the control backs to monitor.
The file indicated by program must be a file of executable code, not
necessarily a program HBL.
Discussion:
All the channels of I/O that were closed before instruction STOP are closed (in
mode equivalent to action CLOSE), with the exception of the channels open in mode
OUTPUT, whose file associated will be cancelled.
If the file of specified program can’t be found, there will be an error: “file not
found” (#18).
KSTOP;
0 !+ 4
K
4.4.28. STORE
The instruction STORE is used exclusively for file ISAM. It will make a record
added to file.
Syntax:
Where:
channel is an expression arithmetical that indicates the channel of destination file. The
channel must be already open in mode SU.
area_data is a alpha variable whose content represents the record that will be
memorized in file ISAM.
key is a variable alpha that specifies the primary key which the record will be
associated.
The value of key determinates the logic position in the file record ISAM and must be
equal to key field of record.
The field key of record is contained in area_data with position and length defined in
the creation of file ISAM. If the length of key value is different from
the length of defined key, we have error “key not same”(#53).
Discussion:
If the defined file does not permit the duplication of keys, and the record that we
want memorize has key identical to one of a record already present in file, will get
error of “duplication keys not permitted”(#54).
KSTORE;
If the length area_data is longer than defined length for record of file ISAM, will be
transferred to file only the portion more at left of record. If the length of area_data is
shorter, the record is sent to file and the remaining space is filled by blank.
examples:
This instruction memorizes the information contained in ISMREC and indicates that
“..DOT..” is the value of record key.
If the key field has a magnitude different from key value or is not equal to content of
key value, we’ll get error:” key not same” (#53).If in file ISAM there’s not space will
get error:
“Out of space for ISAM”(#112).
0 !+ 4
K
4.4.29. UNLOCK
The instruction UNLOCK frees all the blocked records associated to the called
channel.
Syntax:
UNLOCK channel
Where:
Discussion:
After executed the instruction UNLOCK, are accessible those data that previosly
were inaccessible for the block of record.
Note that UNLOCK is implicit as last action executed by instructions CLOSE,
DELETE, WRITE and as first action executed by instruction READ.
The instruction READS executes implicitly an UNLOCK only when advance to next
block of data file.
So that, further operations of REASD, can recuperate many records w/out have to
block them. This is done to minimize the inter action with the operating system, that
should be instead requested.
In an ambient mono-user, there’s not blocking of records and this instruction is
ignored.
KUNLOCK;
0 !+ 4
K
4.4.30. UPCASE
The instruction UPCASE converts the small characters to capital. More than
convert the alphabet letters, UPCASE alteres the special characters listed in
section Discussion.
Syntax:
UPCASE variable
Where:
variable is a variable alpha containing the characters that will be converted’
The whole sequence of characters is analyzed and any character
is converted to capital, if is alphabetical, or in one of the here
below listed characters:
Discussion:
Small Capital
` (096) @ (064)
{ (123) [ (091)
} 9125) ] (093)
| (124) \ (092)
~ (126) ^ (094)
examples:
RECORD
FLD1, A14
KUPCASE;
PROC
FLD1 = 'just a {demo} .'
UPCASE FLD1(4,11)
UPCASE FLD1
STOP
END
Ad FLD1 is assigned initially the value:
just a {demo} .
jusT A [DEMo} .
JUST A [DEMO].
0 !+ 4
K
4.4.31. WRITE
The instruction WRITE executes a casual access output on the records
of specified channel. The instruction WRITE is used to rewrite the
records already present in file,both file ISAM and not ISAM.
Syntax:
Where:
channel is an expression arithmetical whose value specifies the channel
of destination file.
The channel must be already open in mode OUTPUT,UPDATE or SU.
record_id indicates which particular record must be sent. For a file not
ISAM, the record_id is a decimal variable, whose value is
the ordinal number of desired record; the first record is
number 1, the second is number 2,and so, by the way.
For the ISAM file, the record_id is a variable alpha
containing the value of primary key, that determinates the
logic position of record in file ISAM.
If the length of key value is not same to the length of key
field, we get error:” key not same”(#53).
The key field is contained in area_data; his position and
length are defined when the file ISAM is created. If the
content of key field is not equal to the value of specifies
key, we get error "key not same" (#53).
Discussion:
KWRITE;
For a file ISAM is written a record got from last instruction READ or
READS. Note that
is not possible do other I/O operations between READ/READS and
WRITE.
If some other operation of I/O are done, is generated the error "key
not same" (#53).
If a key is not specified as to be modified when we create the ISAM
file,( is not possible to do different in the actual implementations),and
we try to modify this key during the WRITE, we get error: "Key not
same" (#53).
For file not ISAM, is written the record with the specified ordinal
nmber. The length of area data and the ordinal number of record
determinate the offset in file, where to start write. A number of record
minor than 1 or bigger of the number of records that can be stored
physically in file gives error: “Number record wrong” (#28).
After that is written the content of are_data in a file not ISAM,is put a
record terminator standard(generally a carriage return and a line feed).
These record terminators split the records adjacent in the file. When the
record will be read later, by instructions READ or READS,the
terminator record will complete the input, but will not be transferred to
receiving area data.
When the instruction is used in file open in mode UPDATE or SU, in
ambient many users, the written record is unlocked.
Examples:
This instruction tries to write the 42nd record in a file not ISAM. If
this record was not blocked before by channel 12, the WRITE tries to
lock it before to modify it. If the record is locked by other channel, we
get error. After that record is written, is unlocked.
WRITE(4, ISMREC, KEYVAL)
This instruction tries to rewrite a record on a file ISAM that was read
previously and whose value of key is same to value of KEYVAL. If
the value of key is not the same, we have an error. If the record is
rewrite, after is unlocked.
0 !+ 4
K
4.4.32. WRITES
Syntax:
WRITES(channel, area_data)
Where:
Discussion:
Examples:
WRITES(2, RECA)
KWRITES;
This instruction writes a content of RECA on channel 2. If the disk is
full, we get error#22 and the program is terminated.
0 !+ 4
K
4.4.33. XCALL
Syntax:
Where:
subname is the name of external subroutine to which transfer the
control;
are significant only the first 5 characters of name,
the remain characters are ignored.
KXCALL;
can’t modify; if it tries, is generated error “writing on
literal [#8].
Discussion:
RECORD
ARG1, A5
ARG2, D7
ARG3, A12
PROC
OPEN(15, I, 'TT:')
.
.
.
XCALL DISP(ARG2, ARG3)
.
.
.
STOP
END
Subroutine External:
SUBROUTINE DISP
VAR1, D
VAR2, A
RECORD
FIELD, A15
PROC
FIELD = VAR1, 'ZZZ.ZZZ.ZZZ,XX-'
DISPLAY(15, VAR2, 'results in ', FIELD, 13, 10)
RETURN
END
0 !+ 2
K
5. CAPITOLO V: INSTRUCTIONS OF DIRECTION TO
COMPILER
The instructions described in this chapter are not executable and are
only to direct the action of compiler HBL. Only the instruction PROC
is required in program HBL.The other is facultative.
The instruction PROC marks the end of Data Division and beginning
of Procedure Division.
It specifies also, optionally, the value of default of factor of blocks for
an open file by program.
Syntax:
PROC [(factor)]
where:
To each file not ISAM open, is assigned an area buffer of I/O that
consists of blocks of 512 byte each.
KPROC;
0 !+ 3
5.2. END
K
The instruction END marks the logic end of the whole program.
Syntax:
END
Discussion:
KEND;
0 !+ 2
K
6. CHAPTER VI: NOTE OF PROGRAMMING
KNOTE OF PROGRAMMING;
Each program should contain a STANDARD HEAD in the way to be
self documental.
The use of graphic in comments is regulated by following normative:
;-----------------------------------------------------------
; Determination of tax unit
; category and area
;-----------------------------------------------------------
ICAIU, ............ ; Comment
............ ; Comment
XCAIU, ............ ; Comment
............ ; Comment
;-----------------------------------------------------------
;
=====================================================
=====
; Management scroll in region video composed by NRIG
; ( > 1) starting from RIMIN. Uses the vector
; VRIGH(NRIG),already put.
; ENTRY POINT:
; 1 = scroll up 2 = scroll down
;
=====================================================
====
SCROL1, RITOD=RIMIN ; Row to delete
RITOI=RIMIN+NRIG-1 ; Row to insert
GOTO SCROL0 ; Do scroll
SCROL2, RITOD=RIMIN+NRIG-1 ; Row to delete
N.B. Eventual blocks sequential with many inputs, are same to structure
“CASE”.
6.1.2 Programs of printing type HEAD-BODY-TAIL
;----------------------------------------------------------
; Prints tabulate with head from ROWS row, body formatted
; by elements each of RIGBO rows (fixed), foot from RIGFO
; row and page from RIGBO rows net.
; (example : 66-RIGFO-margin-RIGBO)
;---------------------------------------------------------
...initialization, open,.....
initialization masck;
RIGST= ; Row Counter
READ first element ;
LSTAMP, IF(finished elements)GOTO XSTAMP ;
IF(RIGST)GOTO VSTAMP ; should be
:IF(ROWPRINT)GOTO VPRINT
. positioning and print head
RIGST=ROWS ; Declares printed rows
..eventual positioning on body
VSTAMP, ..Prints body ;
RIGST=RIGST+RIGBO ; Counter printed rows
IF(RIGST.GE.RIGLP)CALL SSTAFO
; Control paging
READ next element ;
GOTO LSTAMP ;
SSTAFO, ..eventual positioning in footer
..print footer ;
FORMS(15,0) ; Page jump
RIGST= ; Counter reset
RETURN ;
XSTAMP, IF(RIGST)CALL SSTAFO ; Print end
.. end file/printer ;
;-----------------------------------------------------------
In the case that each element of body has not fix length, occur preset
an opportune routine of pre-calculation of encumbrance (RIGBO):
...............................
RIGST= ; Rows counter
READ first element ;
CALL SSTAHE ; Head print
LSTAMP, .. Algorthm calculation RIGBO ;
RIGST=RIGST+RIGBO ; Pre-calculation RIGST
IF(RIGST.LT.RIGLP)GOTO VSTAMP ; Goto print body
CALL SSTAFO ; Print footer
CALL SSTAHE ; Print head
RIGST=RIGST+RIGBO ; Re-calculation position
VSTAMP, ..Print body ;
READ next element ;
IF(finiti elementi)GOTO XSTAMP;
GOTO LSTAMP ; ------------------------
SSTAHE, ..positioning and print
RIGST=RIGHE ; Declares rows printed
..eventual positioning on body
RETURN ; ------------------------
SSTAFO, ..eventual positioning on footer
..print footer ;
FORMS(15,0) ; Jump page
RIGST= ; Reset counter
RETURN ;
XSTAMP, IF(RIGST)CALL SSTAFO ; Print closing
.. closing file/printer
;----------------------------------------------------------
0 !+ 2
K
7. CHAPTER VII: COMPILATION AND DEBUG OF PROGRAMS
This chapter describes the compiler use, linker use and how to create
a library of external subroutines. In 7.4 will be explained the use of
debug symbolic.
The plate-form foreseen for develop is SCO UNIX, but is possible
execute the produced programs in one of plate form supported by RUN-
TIME.
To choose UNIX is due essentially because this operative system is
versatile for the software developers.
-
-The code completed really occupies 1066 bytes of memory.
The command accepts, as first argument, the name of main, then the
names of eventual subroutines external recalled and finally the list of
library from which get the subroutines reference d, but not previously
listed.
hbr name_program
0 !+ 3
K
7.3. Construction of library of Subroutines
-l <name_file_trace>
The program is executed normally, but any instruction
executed is traced on indicated file, and permit, at end
execution, to analyze the route done by program.
-m <name_file_list>
This option doesn’t send the program to execution, but
reconstruct on file indicated the listing of program as to
proceeds from executable program.This command is
necessary, when we do the debug of a program, to have
available the opportune reference to insert the break-point in
the wanted points.
-t <name_file_log>
By this option, the program is executed normally, but all
characters keyed by keyboard are written on Indicated file.
This option is useful for debugging routines of management
of keyboard, to check eventual combination critical of
characters sequence.
If will not specified any option, the program is loaded, and before
to start execution, is visualized a window of commands.
The list of possible command is shown keying “H”, and they are:
N.B.:
The visualization of windows of debug is possible only if the
ambient WINDOW was initialized, or if we have available a terminal
with emulator BWINDOW.
In all other cases, the debug operates in modality of line, maintaining
the operative ness by the relative commands.
0 !+ 2
APPENDIX A: SET OF CHARACTERS ASCII
K
LEGEND:
LEGENDA:
- No ISAM present
We are using a RUN-TIME that not allows the management of
ISAM files.