jBASE Tools

The most noticeable difference between jSHELL and other command line shells (such as the UNIX Korn shell (ksh)) is that command line arguments such as * and ? are not expanded by the shell but passed directly to the command that has been invoked. In same manner, quoted strings (such as “quoted string”) are passed directly to the command with quotes intact. This enables query language statements such as:

SSELECT file = “[SPROUT]” BY *A1 –

Issued directly from jSHELL. If the same command was issued from the ksh Prompt, then it would have to be issued as:

SSELECT file = \”[SPROUT]\” BY \*A1 –

This avoids the quotes being removed and the * being expanded by the Korn shell.

Beyond this convenient feature, jSHELL also offers many significant advantages over traditional shells and is easier to use. Some of the main features of the jsh are:

• Easily customised command line prompt
• If required commands can be passed to other shells
• Easy command recall
• Easily identified special prompt when a select list is active
• Long program names are automatically translated to their new names on SVR3.2 systems
• Run jCL programs directly from jBASE hashed files
• Supports command type-ahead

Command syntax for jsh is:

jsh - -c command -s shell -p Prompt

Before getting started, you should log in to your UNIX system and set your position at the shell prompt. If your user account has not been configured to run jSHELL by default, then execute it and complete the following:

exec jsh –

The default jSHELL prompt should now appear.

jsh user cwd -->

User is your login name and cwd is your current working directory. For this exercise, assume that your login name was jBASE and that your current working directory is the home directory for jBASE. In this case, your prompt will look like this:

jsh jBASE ~ -->

The tilde character (~) is a shorthand method of referring to your home directory. The shell expands this character to the full path name of your login home directory before executing commands. If you had changed to a sub-directory called source, then your prompt will look like this:

jsh jBASE ~ --> cd source
jsh jBASE ~/source -->

You can change the primary or secondary default prompts by using the following commands:

jsh jBASE ~ -->set jps1 newPrompt
jsh jBASE ~ -->set jps2 newPrompt

newPrompt is a string defining the new prompts. The string can contain terminal control characters such as a bell character by specifying special character sequences in the newPrompt string. The character sequences allowed are:

The shell operates in two distinct modes each having a separate function.

• Command mode is used to issue all commands to jsh itself
• Operating mode is used to issue all commands to the system

There is only one command available in the current implementation of jsh (the / command). This character introduces a search string to jsh. The search string is compared against every command in your command history and if a match is found, then the command is recalled as the current command. Pressing the Esc key on your keyboard normally enters command mode.

If you include the $%m sequence when you configure the prompt, then the prompt will change to indicate whether you are in the shell command mode. For example, if the prompt is in its default state, then the following sequence will locate the last cd command in your command history.

jsh ~ --><Esc>
jsh ~ (Cmnd) -->/cd
jsh ~ -->cd source

Note the appearance of the (Cmnd) string as part of the prompt on the middle line.

Two other keystrokes within jsh allow you to recall up to 50 previous commands. They are:

• <Ctrl P> – Go to previous command
• <Ctrl N> – Go to next command

Using these two keystrokes allow you to retrace your commands by stepping backwards or forwards one command at a time. If you need to change any part of a command line, it is very easy as the jsh supports command line editing by using a subset of the jED editor keys.

In particular, you can use the right and left arrow keys to move the cursor to any position in the current command string. The jsh is configured for editing in insert mode by default. This means that any characters you type will be inserted just before the current cursor position. Use the Backspace key to delete the previous character and the Delete key to delete the character directly under the cursor.

The jsh can be placed into overwrite editing mode by pressing <Ctrl O>. In this mode, all typed characters will replace the character under the cursor.

The following table shows all the editing commands:

JSH Emulation Modes

If you are already familiar with operating UNIX under other shells, then jsh will allow you to work in the environment with which you are most comfortable. You can switch between the various emulation modes in jsh by using the function keys:

Key	Function
F1	jSHELL (jsh)
F2	Native Platform Shell (CMD.exe, ksh, csh, etc)
F3	Mixed shell (msh)

Some terminals may not support these function keys. If your terminal does not support the F1, F2 and F3 function keys, then the emulation mode can be modified by the jsh internal command jshelltype. The command syntax is:

jshelltype shell

jshell can be one of the following:

• jsh – Pre-processes Meta characters like the asterisk (*), as expected by legacy systems.
• sh – Native system shell on UNIX depends on NT/Win95 CMD.exe.
• msh – Mixed shell. Pre-processes Meta characters as a combination of jsh and sh.
• msh – Mapped Sequences

Options specified on the command line will have the leading bracket escaped. For example:

CT File1 Record1 (X becomes CT File1 Record1 \(X

Any asterisk used as part of a record specification is escaped. For example:

CT File1 * becomes CT File1 \*

Quotes used in a selection criteria specification are escaped

LIST File1 WITH A1 = “XYZ]” becomes LIST File1 WITH \*A1 = \”XYZ]\”

Other Meta characters are untouched so that pipes, etc. can be invoked.

The errmsg tool displays the platform related error message text when used with an error message number.

errmsg 13

The had utility displays any file in a hexadecimal format. Specification of a hexadecimal offset denotes the start of the display.

had –offset

This phase involves running your application in a certain manner and allowing jBASE to record the statistics about the lines of code that were executed during the running of the application. jBASE can record the information using the following mechanisms:

• Use the -JC option to the program. For example:

  % MYAPPLICATION -JC COMMANDARG ETC ETC

  In the above example, when the MYAPPLICATION application terminates a file called jprof, the activity will be written to the current working directory, which contains all the profiling information for this application.

• Set the JBCPROFILE environment variable to 3. For example:

  % JBCPROFILE=3
   % export JBCPROFILE
   % MYAPPLICATION COMMANDARG ETC ETC
  

  In this second invocation jBASE will create a file in the format jprof_mmmmm_nnn. One file for each program that is executed, where mmmm is the process ID and nnn is the perform or execute level. In this way, you can generate multiple copies of profiling information which will automatically include all executed procs and programs. Each file will be stored in the current working directory as of when the application was loaded.

  Remember to unset the JBCPROFILE environment variable when you are finished, otherwise you will find a very large number of the profiling files accumulating your directory. It might be useful to run your application through a jkeyauto script. In this manner, you can accurately repeat a test case through your application and repeatedly use the jcover tools to ensure as much as possible percentage of your application is executed.

At the end of the recording phase, you will have one or more profiling files. These profiling files can then be used in the second stage of jcover profiling. Remember that as UNIX files they can be easily moved and renamed. For example, you can run a number of test cases using the -JC option and each time rename the generated jprof file, such as jprof_a, jprof_b and so on.

In the next phase, you can supply multiple file name for renaming.

Once you have recorded one or more profiling files as shown in the previous section, you are ready to collate all the information. The following is the function of the jcover program. The jcover program can be run as below:

jcover {-fFilename {-fFileName ...}} {-oOutputFile} {-ddelim} {-e} {-h|?} {-u} {-x} {jprof {jprof ...}}

Where,

• -ddelim – Change the delimiter in output records from '*'.
• -e – Write out verbose details of all lines of the executed code.
• -fName    – Name of file to extract source from.
• -h | -? – Help screen output.
• -oOutputFile – Output file name.
• -u – Write out details of unused source code in the supplied input files.
• -x – Write out verbose details of all lines of not executed code.
• prof – Profile name.

By default, the function takes the input UNIX file jprof, extract some statistical information about it, and write it back to a newly-created file called jcover_nnn, where nnn is the port number. It also creates suitable dictionary items.

The default information stored is a summary of the percentages of all source items executed. You can use the -e, -u and -x options to create additional statistical information.

The -oOutputFile option allows you to specify an alternative output file to jcover_nnn. If this option is not used, then it defaults to jcover_nnn and create the file if necessary. Whatever file name you choose, both the DICT and the DATA section is cleared and suitable DICT items are written for later usage.

Once this phase is complete, you will have an output file ready for use with the final phase.

This third phase requires the use of the file created in the second phase. For convenience, call it as jcover_23, but it can be any filename used as the output of the jcover program.

There are basically three ways of using the information created in jcover_23.

• Using jQL with the default DICT macros

  To show a summary of percentages of coverages, use:

  LIST jcover_23 STATS

  To show a summary of general information, such as times, dates, files used and so on, use:

  LIST jcover_23 GENINFO

  If the -e option was used, you can display a list of all the lines of source code executed with:

  LIST jcover_23 EXEC

  If the -x option was used, you can display a list of all the lines of source code not executed with:

  LIST jcover_23 NOTEXEC

  If the -u option was used, you can display a list of all source items that didn’t have any code executed during the application execution.

  LIST jcover_23 NOTUSED

• Using jQL with your own command line

  This involves using a jQL statement with something other than the supplied macros. For example:

  LIST jcover_23 WITH S.ITEMID EQ “MAR]” S.ITEMID

• Using a jBASE BASIC program

  Refer to the layout of the output file and the dictionaries to write your own jBC program to further report on the information available.

At present, jcover is available on UNIX platforms only. When you are running profiling for jcover your application will run at 2-20 times slower, so this type of profiling is not suitable for performance measurement. If you use this against batch jobs, then there will be much decrease in the performance. You will additionally use around 0.5 to 5 MB extra memory per application while running this jcover profiling.

The profiling can only detect whole lines of code executed, or not executed. In the following line of code:

READ record FROM filevar, itemid ELSE record = "xxx" ; GOSUB subname

The jcover profiling only records the fact that the READ statement was executed. It cannot be used to determine if the code following the ELSE was executed or not. If you want to test, then the application will need to be changed so that the ELSE code is on a separate line.

The records written to the jcover output file have different formats depending upon what they are showing. The formats are identified by a prefix on the record key. Note that in the following examples a * character is used to delimit certain fields. This is the default delimiter character. Remember if the -d option was used to jcover, then this delimiter will be different.

E*itemid*filename*lineno

Where,

• itemid – The 4 fields show the record type (E), the item id, the source file name and the line number that were executed.
• <1> – The actual line of source code taken from the source itemid in file filename.

These items show, which lines of code have been executed. They are generated if the -e option is used on jcover. There will be one item for each different line of code executed during the application execution.

F*itemid*filename

Where,

itemid – The 3 fields show the record type (F), the item id and the source file name that were executed.

Used internally to keep track of what items in what files have been accessed as part of the jcover execution.

G*descr

Where,

• itemid – The 2 fields show the record type (G) and then a unique identifier, not really of any use.
• <1> – Textual description of the general information.
• <2> – The actual general information.
• <3> – The order in which the fields are to be displayed using LIST filename GENINFO.

These are general information items.

S*itemid

Where,

• itemid – The 2 fields show the record type (S) and the item ID that were executed.
• <1> – Item ID of the source executed.
• <2> – File name containing the executed source.
• <3> – Number of lines of source. This attribute will be the sum of attributes <4> and <5>.
• <4> – Total number of comment lines in the source code.
• <5> – Number of lines of code in the source that are executable. Blank lines and comment lines are not included in this count.
• <6> – Number of lines of code executed by the application.
• <7> – Number of lines of code executed by the application as a percentage of the total number of executable lines.
• <8> – Number of lines of code not executed by the application.
• <9> – Number of lines of code not executed by the application as a percentage of the total number of executable lines.
• <10>-<20> – Reserved for future use.
• <21> – Details of line 1 of the source code; a character C shows line 1 is a comment line. A numeric value shows line 1 is executable code and has been executed this many times. A blank shows line 1 is executable code, but was not executed during the application execution.
• <22> – Same as <21> but for line 2 of the source code.
• <23> – Same as <21> but for line 3 of the source code.
• Etc. for all lines in the source code.

These items show what item has been executed and are used to build up a list of statistical analysis of the executed item.

U*itemid*filename

For every filename specified with the -ffilename parameter of jcover, there will be one of these items for every item in every file that was not used during the application execution. These items are only generated if the -u option is used on jcover. Item id's that show a non-source item will not be included and these are items that are appended with .o , .a , .so , .sl , .obj , .d or .d or items that begin with ! , $ or *.

itemid – The 3 fields show the record type (U) , the item id and the source file name that were not executed.

X*itemid*filename*lineno

Where,

• itemid – The 4 fields show the record type (X) , the item ID, the source file name and the line number that were not executed, but the source have one or more lines of code executed.
• <1> – The actual line of source code taken from the source itemid in file filename.

These items show which lines of code have not been executed. They are generated if the -x option is used on jcover. There will be one item for each different line of code not executed during the application execution. Only the source files that have one or more line of code executed will be included here. Any source items not executed at all will not have a X* item but will be included in the U* items (assuming the -u option was used)

Run the following command to list the batch.b file in sub-directory source to the printer, indent it by four spaces per level and start non-labeled code at 8 spaces from the left margin:

jfb -L4,2 -V source/batch.b

Profiling can either be enabled using the -JP option, which only profiles the root process, or through the JBCPROFILE environment variable, which profiles the root process as well as all executed processes.

MAINPROG –JP

This command generates a profiling file called jprof_n in the current directory, where n is the port number. Only MAINPROG and any called subroutines are profiled, any executed programs will not be profiled. However, if the CPU time spent executing the actual EXECUTE statement is significant, then that line will be included in the profiling statistics. Profiling terminates when the application stops or chains to another program.

JBCPROFILE=1
 MAINPROG

This command generates a different profiling file for each process executed in the form jprof_pid_n, where pid is the process ID and n is an incrementing number starting at 0.

The profiling file generated contains information about user CPU time. The time spent in system calls, file I/O, and lines, which do not accumulate more than a clock tick are not included in the profiling statistics.

Use the jprof command as shown below to provide profile analysis of the jprof files generated by a program executed with the -JP option.

jprof -kfilename {jprof{_nnn}}
 jprof -a {jprof{_nnn}}
 jprof -o {-v} {jprof{_nnn}}
 jprof -s {jprof{_nnn}}
 jprof {-n{-u}} {-i} {-fFilename}} {jprof{_nnn}}

Where,

• -a – Display all ancillary information.
• -fName – Name of file to extract source from.
• -i – Sort by increasing ticks, rather than decreasing tick.
• -kKeyFile – Name of file to store keyboard input, used by jkeyauto.
• -n – Subtotaled and sorted by source name.
• -o – Display shared object usage.
• -s – Display list of subroutines called.
• -u – Sorted by CPU utilization.
• -v – Verbose mode.

Imagine the source test1.b below has been edited into file BP, where BP is a directory. Note the INCLUDE of another source file test2.b.

OPEN "fb1" TO DSCB ELSE STOP 201,"fb1"
 PRINT "Phase 1 -- start"
 S1 = SYSTEM(9)
 FOR Id = 1 TO 100
    Rec = "
    FOR I = 1 TO 100
       Line = "
       FOR J = 1 TO 20
          Line := CHAR(SEQ("A")+RND(26))
       NEXT J
       Rec = Line
    NEXT I
    WRITE Rec ON DSCB,Id
    NEXT Id
 PRINT "Phase 1 -- end, CPU = ":SYSTEM(9)-S1
 INCLUDE test2.b
 PRINT C1:" records in file fb1"
 PRINT "End"

The program can be created normally with the following command:

BASIC BP test1.b
 CATALOG BP test1.b

By default, when the program is run, no profiling takes place.

Run the program with the -JP switch to create a file jprof.

test1 -JP

You can now examine the profile file with the jprof command, using the -f option to generate optional source code listings from the file BP.

jprof -f BP jprof

Profile of program test1 from jprof Page 1.

Source     Line Ticks       %     Source
 test2.b    8     166         32.93 READ Rec FROM DSCB,Key EL
 test1.b    9     160         31.74 Line := CHAR(SEQ("A")+RND(
 test1.b    11    128         25.39 Rec = Line
 test2.b    7     28          5.55  WHILE READNEXT Key DO
 test1.b    10    9           1.78  NEXT J
 test2.b    9     5           0.99  C1++
 test1.b    13    3           0.59  WRITE Rec ON DSCB,Id
 test2.b    5     2           0.39  SELECT DSCB
 test1.b    7     2           0.39  Line = "
 test2.b    10    1           0.19  REPEAT

The -i option sorts the output with incrementing ticks counts. The -n option additionally sort it by file name. Therefore, the test1.b entries will be displayed separately to the test2.b entries.

jstart jsh -s jsh -

This starts the jSHELL in a new window, with a different port number and works for both Win9x as well as NT.

To run jtic you need a description file to describe the capabilities. This file is very similar to that required by the UNIX tic command.

• Comment lines start with # as the first character of each line. Blank lines are also counted as comment lines.
• Terminal names specifies jtic the names of the terminal definition. It is a list of names delimited by | character. The final field is treated as a comment. Following the terminal names will be the binary definitions, integer values and string values for those terminals. When another set of terminal names are defined, the current definitions are written to file and the current definitions nulled. For example,

  vt100|vt100am|prism-ans|Simple vt100 support

• Binary definition are just the name of the definition.
• Integer value specifies the name of the definition followed by # then the value. For example, cols#132.
• String value specifies the name of the definition followed by = and followed by the string value. jtic supports all the functionality of tic, such as defining characters 1 to 26 using ^A through ^Z, special characters such as \E for escape, \s for space, \t for tab. It also supports the if/else/endif structure and logical/arithmetic operations supported by tic.

  For example, if_prtr_letter=\E[02l, use=name. This resets the definition to that of a previously defined name in the definition; you can use this to create a terminfo definition for one or more names, and then base subsequent definitions on that.

  The comments and terminal names must all start at column 1. The binaries, integers, strings and use=name must all have a leading tab character. There can be more than one binary, integer or a comma should delimit string on a line, and each definition. When invoked with the -x option, a terminfo binary file with the suffix _jbase is generated for the extended capabilities.

The table below shows the extended terminfo definitions.

You can generate a terminfo extension file using the jtic -x command. Ensure that the prt_video emulation flag is configured to true, for the required emulation.

Example

Generate jBASE extension tic file.

ED . Mytic
TOP
.
001 # My jBASE extension file for vt220
002 vt220|VT220
003 if_crt_132=My132String,
004 if_crt_80=My80String,
.FI

Generate jBASE terminfo extension file.

jtic -x Mytic

This generates a jBASE extension entry for vt220 in the terminfo database. For example, /usr/lib/terminfo/v/vt220_ext_jbase.

Test terminfo produces correct result.

ED . TESTMYTIC.b
 TOP
 .
 001 CRT "Output my 80 column terminfo command ":@(-28)
 002 CRT "Output my 132 column terminfo command ":@(-27)
 .FI
export TERM=vt220
 export JBCEMULATE=ROS
 jbc -Jo TESTMYTIC.b
 TESTMYTIC > MyFile

mw42 -f -a -t -n 30 1440 > mw42.out

Produce a full listing for the application account with timestamps on every line without asking for input. Sample every 30 seconds for 1440 samples and pipe the output to mw42.out.

jsh -->AUTOLOGOUT 10

Automatic logout is set for 10 minutes.

jsh -->AUTOLOGOUT 15 OFF (C

Automatic logout is set for 15 minutes.

Use the UNIX command typescript for this functionality if COMO is NOT part of your legacy application. For example,

1. script - Start recording
2. [command execution]
3. Ctrl-D - Stop recording.

   You can find the recorded information in the typescript file.

The default behaviour is to allow the input of control characters. The jBASIC IN statement ignores the setting. For example,

CONTROL-CHARS

Control characters OFF (allowed).

CP CUSTOMERS SMITH

CT CUSTOMERS SMITH

# DB-PAUSE
DatajBASE paused at Mon Nov 25 15:59:53 2002
For READ and WRITE operations
Updates are denied also to root users
Transactions will be blocked immediately.

# DB-RESUME
Database is active, resumed at Mon Nov 25 16:00:33 2002
When run, it resumes all operations to the database.

# DB-STATUS -V
DatajBASE paused at Mon Nov 25 16:13:36 2002
For READ and WRITE operations
Updates are denied also to root users
Existing transactions can continue until complete
Port 4 is waiting for DB-RESUME
Port 23 is waiting for DB-RESUME
Port 31 is inside a transaction
1 ports inside a transaction, 2 ports waiting for DB-RESUME

One common usage of these commands will be to split mirrors on a mirrored disk system. One of the mirrors can then continue a jBASE operation following a DB-RESUME and the other mirror, which is now quiescent, used for a fast backup using operating system specific backup tools.

If a database update is currently in operation, the command will not stop existing updates. Normally these only last a matter of milliseconds, but could be longer depending on the application. For example, the file might have a datajBASE trigger associated with it, and as that is under the control of the application, any sort of delay might occur depending on the trigger.

It does not force any data from the kernel file cache onto disk. Hence, if you paused a database and immediately started a mirror split you would get inconsistent data and possibly corrupt files, as some of the changes to files would only be in a kernel file cache rather than disk. You should wait 1-2 minutes for your sync to flush updates to disk, but this is only guidance as each installation is different.

In both of the above scenarios, you must satisfy yourself that consistent flushing of the data to disk before attempting any operation that depends upon it.

The DB-PAUSE command is extremely effective. So much of jBASE, both internal and application wise, writes to files that once it executes the DB-PAUSE command, virtually no jBASE programs will run (the DB-PAUSE, DB-RESUME and DB-STATUS commands being the notable exceptions). Please treat with extreme caution. You might like to initially use the -a option to DB-PAUSE such that root (administrator) users can continue running jBASE.

Be wary of having jBASE commands in the login script for root user, as this is always bad practice, but even more so with DB-PAUSE. Be careful, not to pause a database and log back on to root to resume. The login script pauses because it is paused while running a jBASE program. It is best practice that you never put jBASE programs in the login script of root user.

By default, the DB-PAUSE command only affects individual updates, not transactions. Therefore, while the effect of DB-PAUSE is to make the files logically correct ready for backups or splitting mirrors, the database records will not be consistent. If your applications use transaction boundaries, you should use the -t option to DB-PAUSE, that is the transaction will complete and make your database logically correct. Using DB-STATUS -t, you can check how many (if any) users are still inside a transaction and hence able to do further data jBASE I/O and so delay and maintenance until all the users have completed their transaction.

The jBASE ECHO-OFF command resets the jBASE echo enabled flag. This suppresses input character echo, when using a jBASE program.

The command syntax is:

ECHO-OFF

The jBASE ECHO-ON command sets the jBASE echo enabled flag. This enables input character echo, when using a jBASE program.

The command syntax is:

ECHO-ON

LISTDICTS PAYROLL

The jBASE LISTF command displays in page format all MD entries with attribute one set to either D or Q.

The command syntax is:

LISTF

This shows what files a user has open. By default, it shows a summary. For example,

jsh --> list-files
Polling 3 ports ...
Opened files at 19:52:16  16 JUN 2003       
Page    1
Port     Application Open Files     Actual O/S Open Files 
0         258                             247
1         8                                8
2         4                                4   

Many of the new commands get their information by polling active ports. This can take 5-10 seconds.

With jBASE, 4.1, if you open the same file multiple times to different variables, then jBASE will have only a single operating system file. This is for efficiency and thread consideration. The difference between the numbers of files the application thinks it has open and the number of files jBASE actually has open with the operating system is displayed in the second and third columns. This will be more significant in multi-thread applications that might open the same file, once for each thread. In this case, there will only be a single actual file opened and the threads will share the same file handle, although this is done hidden from the application.

The (V) option will show a row for each file opened by the application.

The LISTU utility displays information on processes executing jBASE programs.

The command syntax is:

LISTU (Options)

Where, options can be P, which redirect output to printer and N, which specifies no page.

The output of the LISTU command is customized by calling the JBCUserCustomiseDisplay subroutine.

The following table shows the utilities that displays and controls locks taken by jBASE applications:

MSG !31 Happy Birthday Jim

Sends a message to the tty device associated with port number 31.

MSG Jim Can I borrow your pipe and slippers?

Sends message to the tty device for all users named Jim.

Phantom process started on Process ID pid#.

The operating system assigns the process ID number, pid#.

A phantom process cannot use any tty devices. Input to a phantom process processes can be achieved using the database statements. For example, the following paragraph runs the BASIC program MYPHANTOM and supplies input to it using two data statements:

BACKGROUND
0001: PA
0002: RUN BP MYPHANTOM
0003: DATA A

SLEEP 13:15

The process will sleep until 1:15 p.m.

SLEEP 300

The process will sleep for 300 seconds or 5 minutes.