Customizing the output of commands


It is possible for a customer to modify the output characteristics of the WHERE, LISTU and SHOW-ITEM-LOCKS** utility programs. This is achieved by creating a subroutine that is called by these programs. The subroutine must be accessible to all users who will call the programs.

**User customization for SHOW-ITEM-LOCKS is not available for jBASE 4.1 onwards.

This subroutine has the fixed name JBCUserCustomiseDisplay. It is passed a single parameter that is both the input and the output parameters. This subroutine is called as a common subroutine for WHERE, LISTU and SHOW-ITEM-LOCKS and is called once at the start of each program to present the heading information, and once again for each line of data that will be output 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 it's own options. For example, ; a new command line option such as (U) could be added on the command line to specify that user location details should be displayed.

The subroutine can be called in two different ways.

1. Header Specification

The following information will be presented to the caller in the single parameter:

attribute 1 One of "WHERE", "LISTU" or "SHOW-ITEM-LOCKS"
attribute 2 Always 1 to show it is presenting the headers.
attribute 3 A multi-value list of the heading text, one value per column.
attribute 4 A multi-value list corresponding to attribute 3 which has numeric definitions to describe the column. These definitions are contained in the supplied JBC.h file. This makes it better and more portable to find, for example, what column the port number is displayed in. You would use this code
INCLUDE JBC.h
LOCATE CUSTOM_TYPE_PORT_NUMBER in parameter<4> SETTING ....

which will find what column number the port number will be presented in.

attribute 5 This is the width of each heading column. This value does not include the delimiter added by the jBASE program.
 

2. Body Specification

The subroutine is called once for each line of body data that the jBASE program will output. When this is done the following information will be presented to the caller in the single parameter

attribute 1 One of "WHERE" , "LISTU" or "SHOW-ITEM-LOCKS". Do not amend this attribute
attribute 2 Always "2" to show it is presenting the data. Do not amend this attribute.
attribute 3 A multi-value list of the data it wishes to display. Each value corresponds to the layout in the heading as presented in the first call shown above. For example, if the account name were to be presented in the 3rd column of the output of WHERE, then the account name will be in the 3rd multi-value of this attribute 3, and the first call which defines the headings will have multi-value 3 in attributes 3,4 and 5 defining the account name. If you want to remove a complete row of data, then in attribute 3 return a null string.

 

NOTES

  • When finding out what column a particular piece of information is held in, remember that if you insert or delete fields that field number might become invalid, so the order of finding the information is important. For example you might use LOCATE (as in the examples) to find out what column the Account name is during the WHERE command , this is usually by default in column 3. If you later decide to delete the Port number , in column 1, then the Account name will now be displayed in column 2 instead of column 3.
  • The WHERE command has the (V) option, which means multiple lines of information are displayed for each jBASE active program. When this happens you probably want to mimic the layout of the WHERE command i.e. the columns such as Port, Device, Account are only displayed 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 are variable in width. They are initially created so 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 so that it fits onto the screen width. The LISTU command has no such fields and it is up to the programmer to ensure all modified fields will fit onto the screen width.

 

 

EXAMPLE 1

Remove the "Device" column from the output of the WHERE command. The output of a WHERE command that is:

   Port     Device   Account      PID      Command
   10       ttyp0    jbase32      8838     jsh
                                  8840     ED BP TASKLIST
  *12       ttyp2    jbase32      11328    WHERE
   14       ttyp1    jbasebld     11327    ADD.CUSTOMER

is changed to:

   Port     Account      PID      Command
   10       jbase32      8838     jsh
                         8840     ED BP TASKLIST
  *12       jbase32      11328    WHERE
   14       jbasebld     11327    ADD.CUSTOMER

This is the required subroutine.

    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 3 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 = 0
        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

EXAMPLE 2

In this example we:

  • Remove the device name column as we did in the first example.
  • Insert a new column of our own which we will call 'Location'. This column will be filled in by data we create ourselves. 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 be changed to have a width of 16. This will allow us extra room to add a (S) to the account name if we find the user is in sales.

So the output of WHERE will change from:

   Port   Device    Account       PID      Command
   10     ttyp0     rogerm        8838     jsh
                                  8840     ED BP newshell
  *12     ttyp2     jbase32       11328    WHERE
   14     ttyp1     dorisk        11327    ADD.CUSTOMER

to

   Port    Account         Location          PID      Command
   10      rogerm (S)      Sales station 12  8838     jsh
                                             8840     ED BP newshell
  *12      jbase32         Developer desk    11328    WHERE
   14      dorisk          Marketing SW      11327    ADD.CUSTOMER

Here is the required code.

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 = 0
                RETURN
            END
            okayflag = 1
*
* 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 definitio
                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

Utilities