CONTENTS

Name
Description
Screen Options
A – Attributes
B – Background
C – Conditions
D – Display Only
E – Expand/Zoom
F – Programmed Function Key
G – Group Fields
H – Help
I – Information Box
J – Join Key
M – Pop-Up Menu
O – Options
R – Repeat Fields
S – Set/Initialise Fields
T – Title
U – Updates
V – Validations
W – Warnings
X – Command Execution (Triggers)

NAME

screen – screen definition file.

DESCRIPTION

Screens are programmed by writing a screen definition file. These are static descriptions of how the screen should work. All the basic functionality is built into the ubmulti program so the screen definition file is used to switch on (or off) the various ubmulti functions.

Files whose names end with ‘.scn’ are taken to be a screen definition file which is used by the program ubmulti. These files are text files and can be created and maintained with any text editor.

A screen definition file consists of one picture call the ‘master file’ and with or without several other pictures called ‘secondary files’. Each Picture starts with a line containing the filename for the picture. This line starts ‘: ‘ followed by the filename. The Secondary File pictures consist of two pictures. The first is a heading that appears on the screen underneath the ‘master file’ screen (during data entry) and the second is the screen for each record in the Secondary File. Each picture ends on a line which is only a ‘>’.

In this simple example, a simple debtor name and address file screen definition might be:

: debtor
#DEBTOR FILE
Debtor Name:    [debtor]
Address:        [address 1]
                [address 2]
-
Phone:          [phone]
>

Which when run as

ubmulti debtor

would look like:

EXAMPLE SCREEN – debtor.scn

In the screen picture there are four special characters that alter the way a screen looks. Lines that start with ‘#’ are centred. A line consisting of a single ‘-‘ will be displayed as a horizonatl line. ‘|’ characters are replaced by vertical bars and ‘~’ are replaced by horizontal lines. ubmulti will detect and display line joining symbols such as tees and crosses as appropriate.

In this example of a two part screen the debtor’s list of orders is displayed below the master file record:

: debtor
#DEBTOR FILE
Debtor Name:    [debtor]
Address:        [address 1]
                [address 2]
-
Phone:          [phone]
>

: orders
ORDER NO|DATE    |          VALUE
>
[order no]|[date]|[value]
>

which looks like:

EXAMPLE SCREEN – debtor2.scn

In this example there are two secondary files. After selecting a master file record, the user presses F6 (FILES) and is given a pop-up menu allowing them to choose between the two possible secondary files. Once in one of the secondary files the user can move between them by either returning to the pop-up menu (F10 – EXIT from the secondary file) or by using the TAB and BACKTAB keys to move forward or backwards through the list of secondary files. There is a limit of 100 secondary files although on a 25 line screen there is a practical limit of 20 secondary files as only 20 menu options can be displayed.

: debtor
#DEBTOR FILE
Debtor Name:    [debtor]
Address:        [address 1]
                [address 2]
-
Phone:          [phone]
>

: orders
ORDER NO|DATE    |          VALUE
>
[order no]|[date]|[value]
>

: invoice
INV NO|DATE    |          VALUE|DATE PAID
>
[inv no]|[date]|[value]|[paid]
>

Which looks like this while the user decides which secondary screen to view:

EXAMPLE SCREEN – debtor3.scn

Screens can also be displayed as “secondary file only”. In this mode the screen is a single scrolling region and only the secondary file picture format can be used. As there is no way that ubmulti can tell the difference between the this and the master file base screens, the “-s” flag must be given when using secondary file only screens.

One good use for this type of screen display is to provide a scolling list from which the user can then expand(soom) into more detail when used in conjunction with the EXPAND/ZOOM option.

: orders
#CUSTOMER ORDERS
-
ORDER NO|DATE    |     VALUE|DEBTOR
>
[order no]  |[date]|[value]|[debtor]
>

Which when run with

ubmulti -s orders

looks like:

EXAMPLE SCREEN – orders.scn

SCREEN OPTIONS

The screen is controlled by several screen options. Options are defined by a line starting with a capital letter and are followed either on the same line or subsequent lines with further specifications of the options. If an option uses extra lines, then these are terminated by a line that starts with a ‘>’.

The options that follow a picture apply to that picture only.

The list of options that follows is in alphabetical order. Each option description starts with the basic syntax, followed by a description of what it does and then one or more examples. Where appropriate sample screens are used to illustrate the effect of an option.

ATTRIBUTES

A
{<field>} <attribute list> {<condition>}
...
>

The fields listed will be displayed with the attributes in <attribute> list if the optional <condition> is true, or if there is no condition. <field> may be used several times. In this case the first <condition> that is true is used to select the <attribute> list to use.

If <field> is [_record] then the attributes are applied to all fields that do not have their own attribute.

If <field> is omitted, the attributes are applied to the screen background and foreground colours.

A slight bug in ubmulti means that at least TWO white-space characters must immediately preceed any <condition> that is present.

A
[on hand]       BLINK,WHITE,RED         [on hand] < 0
[on hand]       BOLD,WHITE,BLUE
                BOLD,BLACK,WHITE 
>

<attribute list> is a comma (,) separated list chosen from the following:

Colours starting with B_ are brighter versions of the normal colour. If colours are specified, the first is the foreground colour and the second is the background colour. Support for combinations of mono and colour attributes may vary from one terminal to another. Colour support requires a suitable terminfo entry. B_ is a combination of BOLD and the colours.

BACKGROUND

B
{<top>}
>
{<centre>}
>
{<bottom>}
>

Background Text is divided into 9 regions on the screen. Top, centre and bottom (separated by ‘>’ lines) and left, centre and right on each line (separated by ‘#’ characters).

CONDITIONS

C {<table>}
<condition>
...
>

Only records meeting all the conditions will be available.

If <table> is given the conditions will be applied to <table>.

DISPLAY ONLY

D
<field> {<condition>}
...
>

The fields listed are display only on data edit i.e. change and edit.

If a condition is given then the field will beocme display only if the condition is met. This is dynamic and changes as data on the screen changes.

N.B. only one field per line. The line must start with the field definition.

D
[size]
[quantity]	[size allowed] != "Y"
>

EXPAND/ZOOM

E <field> {<field>...} {<arguments>} <screen>

Expand record using the list of fields or text as a key and calling ubmulti to run screen. Note that additional command line arguments can be given after the expansion field. eg.

E [user] -k user usernames

PROGRAMMED FUNCTION KEY

F{C|E|S|X} <key> {<field>} <label>
{<help>}
>
{<command>}
>

Whenever <key> is pressed <command> is executed.

If <field> is given the output of <command> is captured and placed in <field> otherwise the output goes to the screen. More than one <field> can given. In this case the output is used to fill the fields until the fields are all used or the output runs out.

<command> is the shell script to execute. The data fields can be referred to by enclosing the field name in ‘[‘ and ‘]’. The current value will be substituted in the command script.

<key> is the function key to which command is bound. This is not optional. <key> is in the range 1 to 8. Note that ubmulti does not use key 7 so it is a good one to use if only one key is required.

Note also that function keys with <field> specified will only be displayed during add or edit functions.

<label> is the label to display on the function key labels at the bottom of the screen. Only the first six characters are significant.

If the option C (Command) is given the function key will only be displayed and available in command mode. i.e. while waiting for FIND, EDIT, etc.

If the option E (i.e. FE) is given then the function key will be displayed if the user enters an invalid Foreign Key value. <field> in this case is the foreign key field to use this error function key. The function key is displayed when the “VALUE NOT FOUND” message is displayed.

If the option S (Save) is given the current record will be saved automatically when the key is pressed in ADD or EDIT mode. All the change or add validations will be applied as well as the function key validations.

If the option X (i.e. FX) is given then ubmulti will exit after executing <command>.

Example:

                F2      [user] USER
                USER NAME
                        USER NAME

                Use F1 to put your login name in the user field
                >
                who am i |awk'{print $1)'
                >

GROUP FIELDS

G group
<field>
...
>

Field is part of display group. The cursor moves left to right, top to bottom in each group.

HELP

H
<help>        
>

Help message for screen. See help(4) for format.

INFORMATION BOX

I{<title>}
<picture>
>

This displays additional information on the current record. Typically it is used in a secondary screen to display totals of columns or extra details on the current row.

If <title> is given, it is used as the window title for the information box. This has the same function as ‘T’ below.

An I section can be used with a master file in which case it will be displayed on the bottom of the screen below any secondary file. This is particularly effective when a total is required.

: ordhead
...
>

: ordline
PART QTY   PRICE   EXTENSION
[part no] [qty] [parts price] [extension]
>

I
ON HAND: [parts.qty on hand] TOTAL: [ordhead.total]
>

JOIN KEY

K <key>

Specific join key. Used when there is more than one join possible to a Secondary File.

Environment variables are substituted.

This directive should be placed AFTER the secondary file name.

LINES ON SECONDARY SCREEN

        L <rows>

Use at least rows lines on screen for displaying this secondary file. The secondary file will overlay the main file if necessary. This is in addition to any required for the information window.

POP-UP MENU

M{B}{<row><col>{:<users/groups>{:<menu name>}}}
{<help>}
>
{<heading>}
>
{<option>}
>

Pop up menu. See menu (4) for format details.

OPTIONS

O <options>

Restrict options available on screen.

1..10   Default highlighted function key number
A       No Add
B       No 'SEARCH' key
C       No Change
D       No Delete
E       No 'EXIT' key
I       Initial Secondary Screen After finding  a
        master  file  record, the display will go
        straight to this secondary file.
L       Link Secondary Screens List of  secondary
        files   for  automatic  progression  when
        adding a master file record.
R       Draw  a  ruler  between  records   in   a
        Secondary File
S       Force manual save (with  F1)  of  records
        after editing
T       Display Secondary table tail. That is the
        last   records   rather  than  the  first
        records.
X       Issue a warning before aborting (via F10) during
        ADD and EDIT.

REPEAT FIELDS

R
<field>
...
>

The values in field(s) are repeated from the previous record during add.

SET/INITIALISE FIELDS

S{CDM}
<field>    <expression>
...
>

Set (initialise) Field Value

If field is blank or zero, copy contents of expression into field.

If C is given the sets will be applied to empty fields when the record is edited.

If D is given the sets will be applied to empty fields as for other type S, but the field will be display only on both add and edit.

If M is given the sets will be applied to the fields whether they are empty or not when the record is edited.

N.B. Only one of C, D, M, or no options may be given. Fields may only occur in one S section. There can be one S section for each of nothing, C, D, or M.

TITLE

T <title>

<title> is used as the window title. The top border of the window is shown in inverse video with <title> centered in it.

UPDATES

U{X}{ACD1..8}
<field><=+-*/><expression>
...
>

Update value of field

One of A, C, D, or 1.. 8 must be given and the update will be applied after adding, changing or deleting a record respectively, or after executing the specified function key (1-8).

If X is given then the update will take place before executing the appropriate ‘X’ section or function key. Otherwise the update is done after the ‘X’ section.

N.B. When updates and executes are used together, the order of operation is:

1. Record is saved
2. UX is done and saved
3. X is done and record is read again to ensure it has current values
4. U is done and saved

VALIDATIONS

V{ACDX1..8}
<expression>
<message>
...
>

Record validation

• A only for add record
• C only for change record
• D only for delete record
• X validation before exit from screen or secondary file
• 1..8 only for function key 1..8

All the expressions must be true for the Add, Change, or Delete to be applied or before the user can exit. If one fails the message following is displayed and the operator returned to the data entry screen. If a number is used the validation is applied before executing the relevant function key.

VA
[qty] != 0
YOU MUST ENTER A QUANTITY
[date due] >= [system.date]
DATE DUE MUST BE AFTER TODAY
>

WARNINGS

W{ACDX1..8}
<expression>
<message>
...
>

Record warning

• A only for add record
• C only for change record
• D only for delete record
• X only on exit (as above)
• 1..8 only for function key 1..8

Similar to validations, except that if an expression fails, the operator is given a choice of accepting or rejecting the record with the error.

COMMAND EXECUTION (TRIGGERS)

X{ACDX} {S} {M<message>}
<command>
>

Execute command

• A only for add record
• C only for change record
• D only for delete record
• M Display <message> in centre of screen before executing <command>
• S Execute commands after editing all Secondary Files
• X Execute commands when exiting the screen

White space is allowed between the options and any leading white space before <message> is ignored.

A, C, and D may be combined in the one execute section.

The screen script of commands is executed following the addition, changing or deleting of a record. In the case of XX the commands are executed as the screen program exits. Fields from the current record (and associated records) may be referenced in the commands in the usual way.

XAM     SENDING MAIL
mailx -s "NEW CUSTOMER" root <<!
[customer]
[address 1]
[address 2]
[address 3]
[telephone]
!
>