SCRB

SCRB

Top  Previous  Next

 

The SCRB command runs the screen builder to create or modify a screen definition for use by the QMBasic !SCREEN() subroutine.

 

 

Format

 

SCRB {screen.file} {screen.name}

 

where

 

screen.fileis the name of the file holding the screen definition.

 

screen.nameis the screen definition record name. If neither a screen.file nor a screen.name is given, SCRB will check for an active select list before prompting for a screen name.

 

 

The QMBasic !SCREEN() subroutine uses screen definitions which are created and maintained using SCRB. The name of the account’s default screen definition file is stored in field 2 of an X-type VOC record named $SCRB.FILE and will be used if no file name is given in the SCRB command line. If this record does not exist, SCRB uses the $SCREENS file which is common to all accounts. The $SCREENS file may also contain screen definitions which are part of the QM product. These have a dollar sign in their name and should not be modified or removed.

 

A screen consists of a number of steps, each of which may have a fixed text display, output of data from a data record, and input of data into a data record. Data may be converted or formatted on output and input. Steps that include data input may perform validation within the screen driver subroutine and may also have user defined help and error messages. Programs can undertake all aspects of managing the flow from one step to another themselves, pass this task to the screen driver using a variety of conditional flow control options or use a mixture of the two modes.

 

The screen builder can automatically generate an include record identifying the screen steps by name for use in programs that use the screen. This include record will be placed in a nominated file with the same name as the screen with a .SCR suffix.

 

On entry to SCRB, the user is invited to enter a screen name unless this has been provided on the command line. SCRB will look for this in the form entered and, if not found, in uppercase. If neither exists, a new screen is created.

 

The user can then select from the following options

DDelete the screen definition
FFile the screen definition
HAmend the screen header line
ISet the file to store the generated include record
LList the screen steps
PPaint the screen
LPTRPrint the screen definition
SnShow / edit step n
XExit without filing

 

 

Amending the Screen Header Line

 

Selecting the H option allows entry/modification of the screen header line. It is useful to include the screen name in the header, perhaps at the left margin. All the normal input editing keys are available. Pressing the return key will end the header update.

 

 

Listing Screen Steps

 

The L option displays a list of screen steps. The information displayed is the step number and the fixed text (if any) associated with the step. If the step has no fixed text, the display shows <<step name>>. The escape key can be used to terminate the list before the last page is displayed.

 

 

Painting the Screen

 

The P option paints an image of the screen, showing the fixed text associated with steps except those that are tagged as not to be included in a full screen paint. A prompt is issued allowing selection of a step number to be executed. This allows easy debugging of the screen from within the screen builder. Entering X at the action prompt exits from paint mode.

 

 

Printing the Screen

 

The LPTR option send the screen definition to the printer. Details of each step are printed followed by a representation of the screen as it would be appear after the screen paint action of the !SCREEN() subroutine.

 

 

Show / Edit a Screen Step

 

The Sn option displays the definition of screen step n. A further prompt allows selection of the action to be taken

CnCopy step n over the currently displayed step
Cscrn,nCopy step n of screen scrn over the currently displayed step
DDelete this step
IInsert a new step before this step
MnMove currently displayed step to become step n
NAdvance to the next step
PMove to the previous step
RReturn to the top level screen
SnMove to step n
nEdit step definition starting at item n

 

 

The items that make up a screen step are described below.

 

Name

Steps may optionally be given names. These must be unique within the screen definition and are used in generating an include record of step names for use in QMBasic programs. The include record tokens are formed by adding a prefix of SS. to the step name.

 

Type

The step type determines the way in which the screen driver will handle the step. The type may be any of the following:

 

DA display step. Any data item referenced by the step will be displayed but no input is permitted.

 

IAn input step. The data is displayed as for a display step but input may also be performed.

 

NA control step. Any data item referenced by the step is not displayed but conditional flow control elements based on this data item may still be included.

 

GnA step group to be repeated n times. The display step field described below contains a list of steps to be repeated. The repeat will terminate if the next step determination of any repeated step evaluates to anything other than the default. Step groups cannot be nested.

 

 The step type may also include the following qualifying codes:

 

BSounds the terminal "bell".

 

CClears the text and data of this step after the step is completed. Usually used with the X display mode options described later, this feature is particularly useful for clearing temporary prompt fields from the screen.

 

HCauses the screen header to be displayed as part of this step.

 

RnThis step is to be repeated n times. The repeat will terminate if the next step evaluates to anything other than the default. Repeated steps may not appear inside step groups.

 

XExcludes this step from the initial screen painting process. This should normally be included on the elements of a repeating group (not a repeated step).

 

Clear

The clear item contains Y if the screen is to be cleared prior to displaying this step.

 

Display step (multivalued)

This field lists steps by name or number which are to be displayed prior to displaying this step. For repeating step group definitions it holds the steps to be repeated as described above.

 

A list may be entered in a multivalued screen definition field by pressing F2.

 

Text

Text row

Text col

Text mode

The text item contains a fixed text string which will be displayed on the screen at the position given by the text row and text col values using the text mode display style. The mode may contain any combination of H to display in half intensity, R to set reverse video (interchange foreground and background colours) and X (omit from full screen paint).

 

Field

Value

Subvalue

These items determine the position of the data item to be displayed or input. The field may be specified as a numeric position or as a filename and field name separated by a space. In the latter case, the screen builder will look up the actual field position in the dictionary of the specified file when the screen definition is being entered. Later changes to the dictionary will not cause the screen definition to change. The value and subvalue fields may be left blank where the entire field or value is to be displayed.

 

A value of zero for the field uses an internal temporary variable. This is of particular use in confirmation prompts, for example, where the data input is used to determine flow through the screen steps but is not part of the record being amended.

 

For a repeated step or the elements of a repeating group, the field, value or subvalue may be specified as ‘1+’, for example, which will cause the screen to use successive items starting at the given position.

 

Prompt char

This item may be used to specify a character to appear immediately to the left of the data field. It will be ignored if the data is displayed at the left margin.

 

Fill char

The fill character is used to pad out short data items on the display. It is not entered into the stored data.

 

Data row

Data col

Data mode

These items operate in the same way as their equivalents for the text area.

 

For a repeated step or the elements of a repeating group, the row may be specified as y+i where y is the line on which the first item is to appear and i indicates the number of lines by which the position is to advance for successive elements. The value of i defaults to 1.

 

Output len

The output length item specifies the length of the data item on the display. If the actual data is longer than this, the display is truncated.

 

Output conv (multivalued)

This item holds the conversion to be performed on the data prior to display. The same conversion will be applied to redisplay input values when the step is completed. The conversion may be multivalued to perform successive conversions. Output conversions are:

 

FfmtApply FMT() using fmt as the format specifier.

 

Ifile,recExecute the I-type named rec in the dictionary of file. against the data record.

 

SnameExecute catalogued subroutine name, passing in the field value as argument 2 and replacing it with the valued returned through argument 1.

 

Tfile,fld,codeApply TRANS() using the data item as the record id to access field fld of file. The code determines the action if the record is not found. C returns the record id, X returns a null string.

 

<f,v,s>Extract the given field, value or subvalue.

 

OtherAll other codes are passed to OCONV().

 

Justify

This item contains L for left justification or R for right justification.

 

End mark

This item may be used to specify a character to appear immediately to the right of the data field. It will be ignored if the data field extends to the right margin.

 

Input len

The input length item specifies the permissible length of the data. If this value exceeds the output length, the field is panned to allow entry of long data. Many of the screen definition items are themselves panned in this way by SCRB.

 

Required

This item indicates whether the field may be left blank. It may contain:

 

YThe field may not be left blank.

 

NThe field may be left blank.

 

FFor a repeated step or element of a repeating group, the field must not be blank for the first iteration of the repeat but may be blank for subsequent iterations.

 

<f>condThe field is required if field <n> (or <f,v> or <f,v,s>) meets the supplied condition. The condition code is as described for the next step determinations described below.

 

Input val 1 (multivalued)

The first input validation is performed on the input data prior to input conversion. This item may be multivalued to perform multiple validations. The data is deemed acceptable if any of the validation criteria are satisfied. Validation codes are:

 

mNumeric value m. This is a numeric comparison, leading zeros will be ignored.

 

m-nA numeric value in the range m to n.

 

=xString equality with x. x may be a null string.

 

C'abc',65,68-70Character validation. The data must only contain characters from the set listed. These may be a literal string enclosed in single or double quotes, a character number or a range of character numbers. Multiple character sets can be given with a comma separator as in this example which allows "abcADEF".

 

DA valid date.

 

FfilenameA record named as the input data exists in filename.

 

Ffilename,nSimilar to the simple F validation but, if the record is found, the input data is replaced by the contents of field n of the record.

 

MtemplateThe input data matches the specified template.

 

Rfile,rec,fld,case,subst
Record rec is read from file. Field fld of this record is scanned for a match with the input data. If case is X, this scan is case insensitive. If subst is specified, the input data is replaced with the content of the corresponding value of field subst of the record. Field fld may be broken down into subvalues to specify alternative strings all of which are replaced by the value (not subvalue) in subst.

 

@subrnameCalls the named user supplied validation subroutine. This subroutine takes three arguments; the return status ( 1 if ok, 0 if error), the data record being processed and the input data field to be validated.

 

XxxxInverts the condition xxx. For example, XFINDEX would check that there is no record named as the input data in file INDEX.

 

Input conv (multivalued)

This item holds the conversion to be performed on the input data. The conversion may be multivalued to perform successive conversions. Input conversions are:

 

FfmtApply FMT() using fmt as the format specifier.

 

NnIf the data is numeric, extend it to be right justified in n digits.

 

SnameExecute catalogued subroutine name, passing in the field value as argument 2 and replacing it with the valued returned through argument 1.

 

Tfile,fld,codeApply TRANS() using the data item as the record id to access field fld of file. The code determines the action if the record is not found. C returns the record id, X returns a null string.

 

<f,v,s>Extract the given field, value or subvalue.

 

OtherAll other codes are passed to ICONV().

 

Input val 2 (multivalued)

The second input validation is performed on the input data after input conversion. This item may be multivalued to perform multiple validations. The data is deemed acceptable if any of the validation criteria are satisfied. Validation codes are as for the first input validation.

 

Back step

The back step item determines whether the back-tab key is allowed and may contain Y, N or blank which is taken as N. If back-tab is allowed, the screen driver will perform the action internally if it has a step history. If there is no step history, the screen driver returns to the calling program with a status indicating that the backstep key was used. The back step will correctly back-track through a repeated step or repeating group.

 

Next step

The next step item defines the action to be taken after the step is completed. It may be multivalued with conditional elements. A null action simply increments the step number. All next step action lists effectively end with a null element which would be executed if all previous elements were conditional and not satisfied.

 

An action item comprises three parts; a field reference, a condition and an action. The action is preceded by a colon.

 

The field reference identifies the field within the screen data which is to be used in the following condition. This may be specified as <field>, <field,value> or <field,value,subvalue>. If omitted entirely (as is usual), the data from the current step is used. If a field reference is included, the condition must also be present.

 

The condition compares the selected data with a fixed string or numeric value. The generic form of this is EQ'string', EQnumber or EQ<f,v,s>. The operator may be any of EQ, NE, LT, GT, LE or GE. If the condition is omitted, the action is performed unconditionally.

 

The action may be null to advance to the next step, a step number, a step name or X to exit to the calling program. Within a repeated step or a repeating group any non-null action terminates the repeat.

 

Example: EQ'':X would exit if the field is empty.

 

Help msg

The help message item defines a message to be displayed if the F1 key is pressed. The message may be split over multiple lines by using the F2 multivalue entry feature of SCRB.

 

Error msg

The error message item defines a message to be displayed if input validation fails in a similar manner to the help message.

 

Exit key

The exit key item defines the action to be taken if the escape key is pressed. The format and processing of this item is as for the next step item except that a null value causes an error message indicating that the exit key is not allowed.

 

F2 action

The F2 key is used for extended pick-list based help. If this item is blank, F2 is treated the same as other function keys as described below. There are three formats to this item:

 

filename, selection/sort clauses, field names

This format causes the screen driver to select records from the specified file using the selection and sort clauses (as for the query processor). A pick list is displayed based on the specified field names (which are space separated and may include I-types). The first field in this list is used as the returned value from the selection. The pick list short cut system described below uses the field name by default. An alternative field may be used by prefixing its name with a & character. The short cut will only work correctly if the list is sorted in ascending order by the short cut field.

 

#filename,record.name,sort.field,field.list

This format builds a pick list from given file, record, field. The sort.field and field.list reference fields in the named record by number. Dictionary names cannot be used in this action.

 

The data is sorted based on the value in the sort.field. The sort.field number may be followed by R to perform a right justified sort. The field.list is a space separated list of fields to be displayed. The sort.field must be explicitly referenced if it is to be displayed. The first field in field.list contains the value to be returned by the selection process.

 

@subr

@subr(arglist)

Calls a user written subroutine subr to generate the list of items to display. This subroutine returns the data to be displayed via its first argument, one field per pick list line each containing a value mark delimited set of data values. The second argument should return the pick list column number (from one) of the column to be used by the short cut system described below. Up to four additional arguments may be passed into the subroutine from arglist which contains literal values separated by commas. No string delimiters are required.

 

The pick list is displayed as a rolling window. The cursor up/down, page up/down, home and end keys may be used to explore this window. Keys corresponding to printable characters cause a short cut jump to a page displaying items starting at the first that commences with the entered character. The return key will place the data displayed in the first column of the selected item into the screen field. The escape key will exit from the pick list processing without entering data into the screen field.

 

Func keys

The screen driver may accept or reject function keys. Entering Y in this item causes the screen driver to return function keys to the calling program. Entering N or leaving it blank causes an error message if function keys are used.

 

Key val

This field may contain the name of a validation subroutine that will be called after each input keystroke in the field. The subroutine name is followed by a comma and the error message to be displayed if validation fails.

 

The subroutine takes three arguments; the returned status (1 if ok, 0 if error), the data record being processed and the input data for the field (not just the last keystroke).

 

 

Special keys

 

The screen driver uses the following keys for special purposes. The control key bindings shown after some entries are provided for compatibility with other parts of QM.

 

F1Help
F2Pick list help
F3Delete the contents of the current field
F4Restore the contents of the current field after incorrect entry
ReturnExecute the next step action
TabTreated identically to the return key
Ctrl-PExecute the back step action
ExitExecute the exit key action (Ctrl-X)
HomeMode to start of field (Ctrl-A)
EndMove to end of field (Ctrl-E)
Cursor leftMove left one character (Ctrl-B)
Cursor rightMove right one character (Ctrl-F)
DeleteDelete character under the cursor (Ctrl-D)
Ctrl-KDelete all to right of the cursor
BackspaceDelete character before cursor
InsertToggle overlay mode
Page upScroll up in pick list display (Esc-V)
Page downScroll down in pick list display (Ctrl-V)

 

Within SCRB itself, the F2 key is used to enter multivalued items such as validation criteria. Input prompts for successive items appear at the bottom of the screen until a null value is entered.