Till now you have learnt how to write a simple jBase program.

But the data

from your program is not stored anywhere.

In any applications data has to be stored persistently.

In this unit you will learn tha jBase functions to store the data persistently.

1
At the end of the session you will able to

Use jBC statements to

Store data into a file
Manipulate the data
Fetch data from a file

Describe transaction block

Use transaction management related commands in jBC programs

2
The first step to store data persistently is to have a database structure to store
the data. Therefore we have to have a hashed file.

In our example, we are going to use the case as ‘Trainers Data’. So a hashed
file is created with the fields as explained below:

@ID holds the ID of the trainer and uniquely identifies a trainer. Value has to
be numeric. It is a T24 convention to name all ID fields as @ID. Hence the
name @ID
NAME holds the name of the trainer. Can contain maximum of 35 characters
and left justified
CLASSIFICATION holds whether the trainer is a technical or a business
trainer. Can contain maximum of 35 characters and left justified
REGION holds the region where the trainer is from. Can contain maximum of
25 characters and left justified
COURSES holds the list of courses the trainer can handle. Can contain more
than one value. When multiple values are stored, values to be delimited with
VM (Value Marker). Can contain maximum of 35 characters and left justified.

Note: It is not covered here about how to create a data file and to define the
fields, because this is done in the previous session

3
Let us learn the how to implement the following file operations using
jBase functions. And we will use the Trainer database as an example

1. Insert records
2. Display records
3. Update records
4. Delete records

4
1. The first task is in performing file operation is to open the file, here
TRAINER
2. The OPEN statement is used to open a file or device to a descriptor
variable within jBC. Please note that the OPEN statement does not
actually open a file as J4 files are never closed in jBASE. An OPEN
statement stores the path and the name of the file on to a file
descriptor thus making the file descriptor point to the file.
3. 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.
5. If the SETTING clause is specified and the open fails, setvar will be
set to one of the following
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error

5
The WRITE statement allows a program to write a record into a
previously opened file.
array-variable is the identifier containing the record to write.
file-variable is the variable that has been previously opened to a file
using the OPEN statement
Record-id holds the record key
If the SETTING clause is specified and the write fails, setvar will be set
to one of the values:
128 No such file or directory
4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error

When an error is encountered and ON ERROR clause is specified then,

the statements specified within ON ERROR clause will get executed for
any of the above mentioned File Errors except error 128.

Note: The record ID or to be in simple term the value for the @ID field
would not get into the dynamic array. The value of @ID would be
passed as record-id

6
7
The READ statement allows a program to read a record into a previously
opened file.
Variable1 is the dynamic array, that would contain the record that is read
File is the variable that has been previously opened to a file using the OPEN
statement
Record-id holds the record key

If there is no error occurred, then the statements given in the then block will
get executed, if not the statements given in else block will get executed

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

When an error is encountered and ON ERROR clause is specified then, the

statements specified within ON ERROR clause will get executed for any of the
above mentioned File Errors except error 128.

Note: You can use INPUT statement to read the ID from the user and you can
append the data to the dynamic array.

8
9
1. When we have to update a record we need exclusive access to that record.
To obtain exclusive access to a record, we will have to read and lock a
record. The jBASE command READU enables us to achieve this.
2. READU reads data from the file pointed by ‘file variable’. The ID of the
record to be read is specified in ‘record id’. The record read is stored in the
‘array variable’. If READU fails due to an error then the statements in the
ON ERROR clause will get executed. If READU is successful, then the
statements in the THEN clause will get executed. If READU is able to
obtain a lock on the record but the record does not exist, then the
statements under the ELSE clause will be executed (This type of situation
can happen when you try to read and lock a new record that you wish to
create. READU does allow you to obtain a lock on a record that does not
exist). If a record is locked and 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
3. This information might be useful : The SYSTEM(43) function can be used
to determine which port has the lock. We can display the value of
SYSTEM(43) using the ‘CRT SYSTEM(43) statement’
4. When an error is encountered and ON ERROR clause is specified then,
the statements specified within ON ERROR clause will get executed for
any of the above mentioned File Errors except error 128.

10
11
1. User 1 executes a READU statement to read and lock record with ID
1 in the TRAINER file
2. jBASE checks in memory whether the record has previously been
locked by any user. Memory here refers to the memory (RAM) on
the server where jBASE is installed.
3. There is no lock information on the record with ID 1
4. Hence, jBASE locks the record by writing the locking information in
memory
5. Record is then released to the user
6. User 2 tries to read and lock the same record with ID 1
7. jBASE checks in memory whether the record has previously been
locked by any user.
8. There is lock information on the record with ID 1
9. Hence, jBASE rejects the lock request from User 2 for record ID 1

12
The lock taken by the READU statement will be released by any of the
following events:

1. The record is written to by the same program with WRITE or

MATWRITE statements.

2. The record is deleted by the same program with the DELETE

statement.

3. The record lock is released explicitly using the RELEASE statement.

4. The program stops normally or abnormally.

Note: Use the SHOW-ITEM-LOCKS command to view locks currently

held

13
1. The next operation that we are going to learn is ‘deleting the record’ .
To achieve this, we have to check whether a particular record is
available in the file and then to delete the same. The ID of the record
is the input for this statement. And if the delete fails then an error
message has to be displayed to state why the DELETE failed.
2. 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

4096 Network error
24576 Permission denied
32768 Physical I/O error or unknown error

When an error is encountered and ON ERROR clause is specified then,

the statements specified within ON ERROR clause will get executed for
any of the above mentioned File Errors except error 128.

14
15
Take a couple of minutes to read the task displayed. This program can
be written using dynamic arrays. In order to learn commands that
manipulate dimensioned arrays, this program is to be created using
dimensioned arrays.

16
Step 1: Edit the dict file TRAINER]D add the field ‘DESIGNATION’

Step 2: Open the TRAINER file

Step 3: Select all trainer ids whose designation is technical

Step 4: Remove one trainer id from the selected list

Step 5: Read the record

Step 6: Get the value for the field COURSE.DELIVERED

Step 7: Flush data to disk.

As you know how to add a field and open a file, let us now discuss how
to code for steps 4 to 7.

17
After opening the file, we have to get the list of ID’s and then we have to
loop through the list of ID’s to apply the required process

1. To select all the Trainers, we cannot select data using the READ
command as READ only allows us to read one record provided we
know the ID of the record that we wish to READ.
2. We need to use JQL as part of your program.
3. In order to execute a SELECT statement as part of our program we
will have to store the SELECT statement in a variable and then use
the EXECUTE command to execute the select statement
4. EXECUTE will execute the statement in ‘Selectstmt’ and the result
will be stored in return variable. A SELECT statement can only select
IDs of records. It cannot select the whole record. All selected IDs will
be stored in the return variable delimited with FM.

Note:
1. RTNLIST is a keyword to specify that the result of the EXECUTE
statement returns a list and the result has to be stored in the return
variable specified with RTNLIST keyword.

18
1. Now that we have the list of selected IDs in KEY.LIST, you will now have to
REMOVE each ID and process it.
2. Use the REMOVE statement to remove a value from a dynamic array.
3. 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:
End of the array reached 0
Array delimited with FM 2
Array delimited with VM 3
Array delimited with SM 4
4. The first time the REMOVE statement is used with a particular array, it will
extract the first delimited string 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 sub value for example.
Once the end of the array has been reached, the string variable will not be
updated and the SETTING clause will always return 0. We can reset the
"remove pointer" by assigning the variable to itself - for example
KEY.LIST=KEY.LIST
The REMOVE statement should be placed within LOOP REPEAT statement
so that it can remove recursively.

19
1 . Use the MATREAD statement to read a record from a file.
MATREAD works similar to a READ statement. The only difference is
that the MATREAD statement will read the record from the file and
load the record on to a dimensioned array rather than a dynamic
array.
2. The array variable on to which MATREAD will load the record should
be previously declared as a dimensioned array. Note that the
dimensioned array R.TRAINER has been declared using the DIM
statement. Here the dimensioned array is declared to have 10
dynamic arrays. R.TRAINER has been declared to be of size 10 .
Hence it can handle a maximum of 10 fields. Each field contents is a
row of the dimensioned array

We can also use MATREADU and the syntax of the same

MATREADU array FROM {variable1,}expression {SETTING setvar} {ON
ERROR statements}{LOCKED statements} {THEN|ELSE statements}
MATREADU locks the record that is been read and ensures that only
one user can update the record at a time.
When an error is encountered and ON ERROR clause is specified then,
the statements specified within ON ERROR clause will get executed for
any of the above mentioned File Errors except error 128.

20
R.TRAINER is the array variable which holds the whole record read and
COURSES.DELIVERED is the fourth field in the Trainer file. Use the
DCOUNT function to retrieve the number of courses delivered by a
trainer

The DCOUNT() function counts the number of field elements in a string that are
separated by a specified delimiter.
DCOUNT(expression1, expression2)
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.

A = "A:B:C:D"
CRT DCOUNT(A, ":")
will display the value 4

Note how the dimensioned array is accessed. For dynamic arrays you
used angular brackets while here you are using normal parenthesis.
When accessing dimensioned array specify the dimension( or subscript)
within round brackets. Thereafter specify the FM pos, VM pos, SM pos
like it is given for a dynamic array. Each dimension of a dimensioned
array refers to a field of the record. There are no FM in a dimensioned
array. Hence, the FM pos will always be 1.

21
1. After read the do the required changes and then write back to the
file.
2. To write back to the file use the MATWRITE statement to write the
entire contents of a dimensioned array to a specified record on to a
file on the disk.
3. MATWRITE will write the contents of the dimensioned array ‘array’ on
to the file pointed by the file variable ‘file variable’. The ID of the
record to be written is specified using ‘record id’. If the SETTING
clause is specified and the write succeeds, setvar will be set to the
number of attributes read into array. 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

If ON ERROR is specified, the statements following the ON ERROR

clause will be executed for any of the above mentioned File Errors
except error 128.

22
Putting together the concepts discussed earlier, here is the code
snippet used to update the DESIGNATION field.

23
Assume that USD 500 has to be transferred from Account A to Account
B. In this transaction, two important tasks need to be carried out.

One is a debit to A’s account with USD 500

Another is a credit to B’s account with USD 500

It is vital that both the above-mentioned tasks happen or none of them

to happen. If either of transaction alone happens, it would lead to
inconsistency of data.

24
But how do we ensure that either both the tasks are executed or none
are executed?

The answer is simple. If we tell the database that these 2 tasks form ‘a
transaction block’, then, the database will ensure that all statements
with in the transaction block get executed or none of them get executed.

A transaction block usually carries a set of related statements to the

database for execution. Since the statements inside the transaction
block are related, either all the statements have to be executed
successfully or none will be executed.

25
Transaction block in jBase is implemented as shown above

The jBASE TRANSTART command is used to mark the beginning of a

transaction block. Once this command is executed, any database
update will only be made to the buffer.

jBASE will keep executing the statements until it encounters

TRANSEND. Once it encounters a TRANSEND, it writes all buffered
data to the disk thus ensuring that all updates are flushed together. If
any of the statements within the transaction block fail, then all updates
made to the buffer will be rolled back and the TRANSABORT statement
will be called internally by jBASE.

26
27
To generate start date and end date use the OCONV function

Account number is valid if it is available in FBNK.ACCOUNT application

28
1. READ statement reads and locks a record (TRUE/FALSE)

2. When the WRITE statement is executed within a transaction block, write always
happens in the buffer until TRANSEND is encountered (TRUE/FALSE)

3.OPEN command actually opens a file in jBC (TRUE/FALSE)

4. A transaction block is
1. Set of statements within a TRANSTART and TRANSEND
2. Set of statements within a program
3. Set of statements executed from the jsh prompt

5. What is the difference between READ and MATREAD

The READ statement reads a record from a previously opened file into a dynamic array.
The MATREAD statement reads a record into a dimensioned array.

29
You will now be able to
Use jBC statements to
Store data into a file
Manipulate the data
Fetch data from a file
Describe transaction block
Use transaction management related commands in jBC programs

30