Customising jBASE Commands Output

It is possible to modify the output characteristics of the WHERE, LISTU and SHOW-ITEM-LOCKS utility programs by creating a subroutine, which is accessible when the program is called. The name of this fixed subroutine is JBCUserCustomiseDisplay. This section describes how you can define and call this subroutine.

The subroutine is passed to a single parameter, which is both the input and the output parameters and is called as a common subroutine for WHERE, LISTU and SHOW-ITEM-LOCKS. It is called once at the start of each program to present the heading information, and once again for each line of output data to the screen (or printer). The subroutine can choose to modify the headers and output data as required, and can do so differently for each command, or add its own options. For example, a new command line option such as (U) can be added on the command line to specify that it should display the user location details.

There are two ways to call a subroutine:

Header Specification

It presents the following information to the caller in the single parameter:

INCLUDE JBC.h

LOCATE CUSTOM_TYPE_PORT_NUMBER in parameter<4> SETTING ....

Body Specification

It calls the subroutine once for each line of body data based on the jBASE program’s output. When completed it presents the following information to the caller in the single parameter:

Notes

When locating in which column it holds a particular piece of information, the order of finding the information is important. If you insert or delete fields, it could invalidate that field number. For example, you might use LOCATE (as in the examples) to locate the column in which the Account name appears during the WHERE command, usually by default is column 3. If you later decide to delete the Port number, in column 1, then it displays the Account name in column 2 instead of column 3.

The WHERE command, has the (V) option, which means it displays multiple lines of information for each jBASE active program. When this happens you probably want to mimic the layout of the WHERE command, that is it only displays the columns such as Port, Device, Accounts on the first row of data for each jBASE process.

The Command column on the WHERE command and the FILENAME and RECORD KEY columns for the SHOW-ITEM-LOCKS commands vary in width and are initially created so that the command fits the entire width of the available screen. If you modify the columns to display, the jBASE commands WHERE and SHOW-ITEM-LOCKS will re-calculate their variable length fields to fits onto the screen width. The LISTU command has no such fields; therefore, you must ensure all modified fields fit onto the screen width.

Examples

In the example below, you should remove the Device column from the output of the WHERE command. The output of a WHERE command is:

The output is changed to:

Required subroutine is:

SUBROUTINE JBCUserCustomiseDisplay(rec)
 Customize so that for the WHERE command only, we will not display the DEVICE column.
 In order to keep the functionality quicker, we will use named commons
 * so we aren’t permanently opening and closing files.
 INCLUDE JBC.h
 COMMON /JBCUserCustomiseDisplay/ device.column
 IF rec<1> EQ “WHERE” THEN ; Limit ourselves to the WHERE command
     IF rec<2> EQ “1” THEN
 
 This is the call that defines the heading statements.
 * Look to see where the device name is stored.
*
       LOCATE CUSTOM_TYPE_DEVICE_NAME IN rec<4> SETTING device.column THEN
 *
 * Delete the three values that define, for the device name, the heading
* text, the heading identifier and the heading width.
 *
        DEL rec<3,device.column>
        DEL rec<4,device.column>
        DEL rec<5,device.column>
    END ELSE
        device.column = zero
    END
 END ELSE
*
* this is a line of data. Remove the data for the device name
* as we did for the heading statement.
*
            IF device.column THEN
        DEL rec<3,device.column>
        END
    END
 END
 RETURN

In the example below, you should remove the device name column as you did in the first example.

Insert a new column of your own which we will call Location; data you create will fill this column. In this example, it is simply a cross-reference between the port number and a record keyed on the port number.

The account name field will change to a width of 16. This will allow extra room to add a (S) to the account name if we find the user is in sales.

Therefore, the output of WHERE will change from:

To:

Required subroutine is:

SUBROUTINE JBCUserCustomiseDisplay (rec)
 
Customize ourselves purely for the WHERE command.
*    The output for WHERE is normally like this:
* Port    Device    Account    PID    Command
* We will modify the output in the following manners
*    (a) Delete the Device column
*    (b) Insert a new “Location” field, preferably after the
* Account field
*    (c) Update the Account column to be 16 characters and
* append (S) for sales
* This means the heading now looks like:
* Port     Account          Location         PID      Command
 
 
In order to keep the functionality quicker, we will use named commons
* so we aren’t permanently opening and closing files.
*
INCLUDE JBC.h
COMMON /JBCUserCustomiseDisplay/ FILEVAR, delvalue
COMMON /JBCUserCustomiseDisplay/ insvalue, accvalue
COMMON /JBCUserCustomiseDisplay/ okayflag, portnumber
*
* This function is called by many commands other than
* the WHERE command,
 
command = rec<1>    ; Extract the name of the command
type = rec<2>    ;* Extract the type of call.
BEGIN CASE
CASE command EQ “LISTU”        ;* Ignore the LISTU command (for clarity)
CASE command EQ “SHOW-ITEM-LOCKS” ;* Ditto
CASE command EQ “WHERE”
* It is only the WHERE command we are interested in.
* The other CASE statements added for clarity of code only
 
See if this is a heading statement or line of details
*
IF type EQ “1” THEN
*
* This is the heading definition. The rest of the ‘rec’ is made up as follows
* attribute 3: Multi-value list of heading text
* attribute 4: Multi-value list of heading definitions
* attribute 5: Multi-value list of widths of each column
 
Open the LOCATION file for our use.
*
    OPEN “LOCATION” TO FILEVAR ELSE
 
        okayflag = zero
        RETURN
    END
    okayflag = one
*
* Find out where we can extract the port number from.
*
LOCATE CUSTOM_TYPE_PORT_NUMBER IN rec<4> SETTING portnumber ELSE
    okayflag = 0
    rec = recsave
    RETURN
END
*
* (a) Find the Device Name to delete
 
recsave = rec
LOCATE CUSTOM_TYPE_DEVICE_NAME IN rec<4> SETTING delvalue THEN
    DEL rec<3,delvalue>    ; Delete the heading text
        DEL rec<4,delvalue>    ;* Delete the definition
        DEL rec<5,delvalue>    ;* Delete the width
        END ELSE
        delvalue = 0  ;* Cannot find the heading
        END
 
(b) We will add the ‘Location’ value AFTER the account name
 
LOCATE CUSTOM_TYPE_ACCOUNT_NAME IN rec<4> SETTING insvalue THEN
            insvalue++    ; This is the value we insert BEFORE
        END ELSE
            insvalue = 2  ;* Default to becoming the second column
        END
        INS “Location” BEFORE rec<3,insvalue> ;* Insert the text
        INS “99” BEFORE rec<4,insvalue>       ;* Insert a dummy value for the 
                                     heading definition
        INS “20” BEFORE rec<5,insvalue>       ;* Insert the width to use
 
(c) Find the column of the Account definition
*
        LOCATE CUSTOM_TYPE_ACCOUNT_NAME IN rec<4> SETTING accvalue ELSE
            accvalue = 0
        END*
        END ELSE
 
This is a line of data in attribute 3 Each column is
* multi-valued We will amend this line of data according
* to the data we extracted earlier.
 
Make sure the OPEN went okay
*
        IF NOT(okayflag) THEN
        RETURN
END
*
* Extract the port number before we do anything else.
*
port = rec<3,portnumber>
*
* (a) Delete the Device Name
*
IF delvalue THEN
DEL rec<3,delvalue>
    END
*
* (b) Insert the LOCATION information.
*
IF port NE “” THEN
READ location FROM FILEVAR, port ELSE
location = “UNKNOWN”
END
        END ELSE
            location = “”
            END
            IF insvalue THEN
            INS location<1> BEFORE rec<3,insvalue>
            END
*
* (c) Amend the account name to have (S) appended if a sales account
 
            accname = rec<3,accvalue>   ; The account name or “”
            IF NOT(LEN(accname)) THEN
            location = “”
            END
            IF location<2> = “SALES” AND LEN(accname) THEN
            rec<3,accvalue> = accname :” (S)”
            END
        END
    END CASE
RETURN