Installation Advisory for jBASE 3.3 on Linux

These commands will extract the jBASE executables, and perform some initial set-up. The set-up basically consists of the following steps:

1. A symbolic link "/usr/jbc" is created to point to jBASE directory.
2. Check that the korn shell (ksh) is loaded in /bin.
3. the IJU program is copied to /usr/bin (see the section on Automatic User Configuration).
4. the file permissions are set on some jBASE programs.
5. jBASE work files are created.
6. The Linux start up script is modified to run the jBASE daemons.
7. If you have a version of /lib/libncurses.so it is saved as /lib/libncurses.old and a patched version of this library is installed in its place so you can use the TERM command.
8. The jBASE software is now installed on your system.

Tape Devices

In order to access the devices from jBASE it is necessary to modify a few files. These files can be found in the sub-directory dev of the jBASE admin account. Notes on the Layout of these files are given in the file DEVICE_NOTES in this directory.

You may want to create a default device "0" to be referenced by the T-ATT command. For example, to make the Streaming Cartridge Tape (SCT0) the default device, type the following commands as user jbase:

cd $HOME/dev
cp SCT0 0

Thus, when you execute either of the following commands:

T-ATT 0
T-ATT

The tape will be attached according to the file in /usr/jbc/dev/0. Further details can be found in the man page for the T-ATT command. User accounts that have been set up with the iju command (see next section), should have their MANPATH set up automatically to access the jBASE man pages.

Alternatively type the following:

MANPATH=/usr/jbc/man; export MANPATH
man T-ATT

It may also be necessary to modify the permissions of the Linux device files. To do this, log in as root and type the following:

ln -s /dev/fd0 /dev/rfd0
chmod a+rw /dev/*fd0 // for the 3.5" floppy diskette
chmod a+rw /dev/*st0 // for a 0.25" tape cartridge

Automatic User Configuration

Any UNIX user can begin to use jBASE with only the minimum number of changes to their environment.

The best way to configure a user is to amend the login script, usually .profile. There is a program called IJU supplied with jBASE that will create or modify a .profile script. This program is usually copied to /usr/bin so that it is normally in the users default PATH. So, from your users login shell prompt, perform the following:

% IJU

This will create or append an existing .profile script with all the required environment variables. The IJU program will describe each question in full, allowing you to configure a user as you require. If you edit the new or modified .profile later, comments in the script will show you for what purpose each environment variable is used. Users upgrading to a new release should re-execute the IJU script.

Manual User Configuration

The user simply needs to set the following environment variables as a minimum if they do not wish to use the IJU script:

PATH should be changed to include directories /usr/jbc/bin and $HOME/bin.

LD_LIBRARY_PATH should be set to /usr/jbc/lib

MANPATH should be set to include /usr/jbc/man

These variables need to be exported. For example, if running the bash shell, you would enter:

% export PATH=$PATH:/usr/jbc/bin:$HOME/bin
% export LD_LIBRARY_PATH=/usr/jbc/lib
% export MANPATH=$MANPATH:/usr/jbc/bin

The environment variable JBCCONNECT needs setting at some point to enable data to be passed between jBASE applications. This is normally set up in the start-up script (usually .profile) as follows :

export JBCCONNECT=`jbcconnect`

There are other environment variables you can change for things such as Spooler directories and so on. The best way to learn about these is to examine the output of the IJU script or look at the man pages for jbc.

Imported Applications

Users importing applications, i.e. accounts restored from account saves, should execute the following command in the imported directory. This will overlay the imported MD/VOC with the jBASE MD entries.

UpdateMD

This command should also be executed for users upgrading to a new release.

Systems Housekeeping

There is little to do in terms of system housekeeping for jBASE, apart from what you would do for a normal UNIX user.

1. Cleaning-up tmp directory. One of the directories on jBASE is the tmp directory, or /usr/jbc/tmp. You may care to clean this up once in a while. You can simply perform a 'rm -f *' on the directory if you wish, but you should do this when no other users are running jBASE applications and bear in mind you will lose any save-list's saved by your application.
2. Backup and restores. Obviously your data files should be backed up regularly according to your normal backup schedules, usually daily. There are two mechanism for performing backups.
   1. The first mechanism is to use existing UNIX commands, such as 'tar' or 'cpio' . These work very well, but should not be run when a jBASE application is updating files. This is because 'tar' and 'cpio' do a binary dump of each file, and do not take in to account any locks present on the file which may be in the middle of an update.
   2. The second mechanism is to use the jBASE supplied programs jbackup and jrestore. The jbackup routine will back up normal UNIX data files and jBASE data files, respecting locks taken by jBASE applications. They can be run simultaneously with active jBASE applications, although bear in mind that if you need to restore the data that was saved on an active system, the consistency of your data cannot be guaranteed, but your files will not be corrupt. The help screen for jbackup and jrestore can be displayed with the -h option (-h is an illegal option that causes the help screen to be displayed):

jrestore -h

jbackup -h

Performance Tuning

A jBASE application will work at 100% efficiency for most of the time without any special tuning. The only thing that can severely affect a jBASE application is very badly sized files or lack of system resources (such as memory). The latter can be checked for using various options to the sar UNIX utility. The former, the badly sized files, can be addressed in one of two ways:

1. Use the jstat program to check your file sizes. For example:

% jstat CUSTOMERS

will show you the statistical information for the CUSTOMERS file.

2. Use the jrf file resize program when no active jBASE applications are modifying the files. You can specify a file name with jrf, or just execute jrf by itself, and it will re-size all the files in the current directory.

If you have a lack of memory then you can only add more or free resources from memory hogging processes.

Spooler Installation

The Spooler needs to be initialized before any of the Spooler commands can be executed. This is done by performing the following as root user :

login: root
Password:
# PATH=$PATH:/usr/jbc/bin
# export PATH
# LD_LIBRARY_PATH=/usr/jbc/lib
# export LD_LIBRARY_PATH
# :SP-NEWTAB

You will be prompted to allow you to change four defaults, specifying group names to use, directory to put the Spooler in and so on. For most installations the defaults will be the best configuration, and you should simply enter C at the prompt.

The procedure will create the Spooler tables and data in any directory you want, the default being /usr/jspooler. Note that if you choose a directory other than /usr/jspooler, then you need to change the JBCSPOOLERDIR variable in your .profile to reflect the new directory.

The procedure will create a default form queue STANDARD, whose device name is /dev/lp. It will also initialize the queue to be active, so you can start printing straight away.

If you already have a device on /dev/lp, then immediately after Spooler installation use option 4 from the SP-STATUS menu to configure the Spooler device name to another device.

If you already use the UNIX supplied Spooler, then the two can live in harmony by sending all the jBASE Spooler output to the Unix Spooler. This is done by using option 4 from the SP-STATUS menu , and you should change the device type to PROG and the device name to lp. By doing this, any data in a jBASE application that is sent to the STANDARD queue, is re-printed via the UNIX Spooler program lp.

Use program SP-STATUS to create, display and modify printer form queues, and use program SP-JOBS to manipulate print jobs.

A printer queue is normally enabled via the SP-RESUME command like this

% SP-RESUME STANDARD

or by using option 7 from the SP-JOBS menu. You should create a script in the /etc/init.d directory to enable all your form queues at system boot time using multiple invocations of SP-RESUME.

Alternately, use the :REST-SPOOLER command to resume all defined printer queues. Remember, these commands need to have the environment variables LD_LIBRARY_PATH and PATH set up and exported as shown in previous examples, before they will work properly.

Defaults for the printer, such as banners, width and so on, can be found in the configuration file /usr/jbc/config/jspform_deflt and /usr/jbc/config/jspxl_deflt. They contain many notes on the usage of these files. You can either edit these default configurations, or change the form queue to use different configurations.

Option 3 from SP-STATUS changes the form queue definition from /usr/jbc/config/jspform_deflt to /usr/jbc/config/jspform_xxx where xxx is the new form name associated with the printer form queue.

Option 8 from SP-STATUS allows you to change any character translations from the default of /usr/jbc/config/jspxl_deflt to /usr/jbc/config/jspxl_xxx where xxx is the translation name associated with the printer form queue.

Note you can also change the defaults for printer width and depth using the TERM command.

Documentation

The documentation for jBASE comes in three formats.

The first is in the form of on-line documentation available through the man command. The use of the IJU command described later on will set up the environment variable MANPATH so that the on-line documentation is accessible through the man command.

The second format is on a separate set of ZIP files downloadable from the jBASE Software web site.

If you do not have Word for Windows or a word processor that will convert from Word format, you can get the free Microsoft Viewer for windows from Microsoft's Web site.

The on-line documentation is a subset of this documentation and is usually all you will need.

The third format is web based and can be accessed at http://www.jBASE.com/knowledgebase. The knowledge base can be fully indexed and can be searched for the required key word.

Getting started

The following is an example of creating and running a small application under jBASE. There are migration tools described in the documentation to enable you to import existing applications. However, as a new jBASE user, it would be advisable to try to learn to walk before you can run.

It is assumed you have already performed the following, all of which is detailed earlier in this installation advisory.

1. Create an administration account for jBASE.
2. Load the jBASE software from the downloaded tgz file.
3. Created a new user , for example purposes we will call this new user 'jbcdev' .
4. Create a new .profile for the jbcdev user, by logging on to the jbcdev account and using the IJU command. Then log off again.
5. Enabled the jBASE daemons.
6. Created Spooler tables and files.

You can now log back on to your development account, which we have called jbcdev for example purposes. If you have chosen to run the jsh as your login shell (or execute it from your .profile), then the following prompt appears :

jsh jbcdev ~ -->

* Note that Pick users should probably start with the jsh as it allows a TCL look and feel to be created. Later you may wish to use a standard Unix shell.

Assuming your TERM statement is correct, you can use F1, F2, F3 and F4 to change the shell emulation from jsh (where characters such as * are not expanded), to other UNIX shell emulation's. If your terminal settings are not correct, then change them using the two commands (the examples assume a vt220 screen):

TERM vt220

TERM=vt220

The first changes the TERM settings for jBASE applications, the second for UNIX applications. Please ensure that your terminfo definition is correct for the terminal you are trying to use. Wyse-50 is a particular bad definition usually and apart from the function keys, it is confused about the difference between kbs=\b and cub1=\b

You can change the prompt for your jsh to be whatever you like. For example:

jsh jbcdev ~ --> set jps1 $%N:

:

A sample Application

For each of the following steps, we will give the development manner for compatibility mode, and the alternate UNIX mode. These steps can be interchanged depending upon the level of UNIX experience and personal preferences of the user.

The compatible mode will assume you are using the jsh and the prompt is 'jsh jbcdev ~-->' , and for the UNIX mode we assume you are using the bash shell, whose prompt is 'jbcdev ~ >'.

In both cases, the ~ sign denotes the current working directory, and the prompt may change depending upon what directory you are in.

Step 1. Create a source file.

jsh jbcdev ~ --> CREATE-FILE BP 1,1 23,1

OR

jbcdev ~ > mkdir BP

Step 2. Edit a source program.

jsh jbcdev ~ --> ED BP PROG1
New record
PROG1
TOP
.I
000+ OPEN "CUSTOMERS" TO FDESC ELSE STOP 201,"CUSTOMERS"
000+ PRINT "Enter customer ID " :
000+ INPUT CustomerId
000+ READ Record FROM FDESC,CustomerId THEN
000+ PRINT "This customer exists"
000+ END ELSE
000+ PRINT "!! No such customer !!"
000+ END
000+ STOP
000+
.FI

Record 'PROG1' written to file 'BP'

OR

jbcdev ~ > cd BP
jbcdev ~/BP > vi prog1.b
I
OPEN "CUSTOMERS" TO FDESC ELSE STOP 201,"CUSTOMERS"
PRINT "Enter customer ID " :
INPUT CustomerId
READ Record FROM FDESC,CustomerId THEN
PRINT "This customer exists"
END ELSE
PRINT "!! No such customer !!"
END
STOP
<ESCAPE> :wq

OR

Use the 'jed' editor in either mode . For example , use jed BP PROG1 or cd BP ; jed prog1.b

Step 3. Create executable programs.

jsh jbcdev ~ --> BASIC BP PROG1
jsh jbcdev ~ --> CATALOG BP PROG1

OR

jbcdev ~/BP > jbc PROG1.b -o PROG1

Step 4. Create the data file called CUSTOMERS.

jsh jbcdev ~ --> CREATE-FILE CUSTOMERS 1 19

OR

jbcdev ~/BP > cd
jbcdev ~ > CREATE-FILE CUSTOMERS 1 19

Step 5. Create some dummy data in file CUSTOMERS.

jsh jbcdev ~ --> ED CUSTOMERS 100 200 300

New record
100
TOP
.FI
Record '100' written to file 'CUSTOMERS'
New record
200
TOP
.FI
Record '200' written to file 'CUSTOMERS'
New record
300
TOP
.FI
Record '300' written to file 'CUSTOMERS'

OR

(Note that file CUSTOMERS is a jBASE hashed file, and the normal UNIX editors such as 'vi' or 'emacs' cannot access records inside formatted files.)

jbcdev ~ > jed CUSTOMERS 100 200 300

For each item , enter <ESCAPE> FI <RETURN>

Step 6. Run the program.

jsh jbcdev ~ --> PROG1

OR

jbcdev ~ > BP/PROG1

If you have come this far without problems you should be ready to start porting your programs:

T-ATT <device>

CATALOG BP