SCRB |
![]() ![]() ![]() |
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
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, 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
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
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:
The step type may also include the following qualifying codes:
Clear The clear item contains Y if the screen is to be cleared prior to displaying this step.
Display step (multi-valued) 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 multi-valued 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 (multi-valued) 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 multi-valued to perform successive conversions. Output conversions are:
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:
Input val 1 (multi-valued) The first input validation is performed on the input data prior to input conversion. This item may be multi-valued to perform multiple validations. The data is deemed acceptable if any of the validation criteria are satisfied. Validation codes are:
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.
Input conv (multi-valued) This item holds the conversion to be performed on the input data. The conversion may be multi-valued to perform successive conversions. Input conversions are:
Input val 2 (multi-valued) The second input validation is performed on the input data after input conversion. This item may be multi-valued 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 backtab key is allowed and may contain Y, N or blank which is taken as N. If backtab 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 multi-valued 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 multi-value 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.
Within SCRB itself, the F2 key is used to enter multi-valued items such as validation criteria. Input prompts for successive items appear at the bottom of the screen until a null value is entered. |