SUB.EDIT

SUB.EDIT is used to edit records. Single or multiple lines of text may be edited within a specified area of the screen.

SUB.EDIT(file, key, title, null, inval, protect, exit.key, except.key, col, row, displen, color, flags, change, lines, exit, inpat, outpat, just, delim, mask, linelen, state)

The edit environment is highly configurable and may be saved and restored. SUB.EDIT differs from the system subroutine SCRIBE only in the first four arguments (SCRIBE does not use them), reflecting its record editing function.

Use file to pass the name of the source file

Use key to pass the key of the record to be edited. Multiple records may be edited, the keys delimited by @VM.

Use title to pass the text to be displayed as the title of the edit window

This parameter is reserved for system use and should be null.

Use inval to pass the data to be displayed and edited. SUB.EDIT also returns the edited data here. In multiline mode (lines is greater than 1), the lines of text returned in inval will be delimited by the character specified in delim.

If true, this flag prohibits the editing of inval data. A system message will be generated if editing is attempted. Protect defaults to false.

Use exit.key to pass the key or key sequence which will exit SUB.EDIT whenever editing is enabled. Multiple values for exit.key must be separated by | or @FM. In addition, exiting will occur under the following conditions:

• [ <F128M>ì<F255D> ] is pressed at the top of an edit window, or [ <F128M>Å<F255D> ] at the bottom.
• [Enter] is pressed and lines is 0 (single line edit)

Use except.key to pass the key or key sequence that will exit SUB.EDIT whenever editing is disabled. Multiple except.keys must be separated by | or @FM. In addition, exiting will occur if [<F128M> ì<F255D> ] is pressed at the top of an edit window, or [<F128M> Å<F255D> ] at the bottom.

Use col to pass the starting display column of the edit environment.

Use row to pass the top display row of the edit environment.

Use displen to pass the display length in columns of the edit environment. Displen must be specified. If the length of the text entered exceeds displen, the text is horizontally scrolled.

Use color to pass an array of Advanced Revelation escape sequences indicating the video attributes for the edit window. The attributes default to the settings in @ENVIRON.SET (see Appendix 1, "System Variables" and Appendix 3, "Video Attributes"). The following color fields may be set:

Use flags to pass a dynamic array of SUB.EDIT environment parameters. The following are the definitions for the flags fields (these are also defined in the SCRIBE.FLAGS.CONSTANTS record of the INCLUDE file):

EQU ST.CHAR$     TO  1
EQU NOPAINT$     TO  2
EQU UPPER.CASE$  TO  3
EQU EDIT.NAME$   TO  4
EQU FORCE.EDIT$  TO  5
EQU REPAINT$     TO  6
EQU NOSUBVALUES$ TO  7
EQU SAVE.STATE$  TO  8
EQU NOZOOM$      TO  9
EQU NO.ORIG.VAL$ TO 10
EQU EDITOR.FLAG$ TO 11
EQU KEEP.STATUS$ TO 12

The requirements for the field values are described below:

A flag used by SUB.EDIT to indicate whether edit changes occurred to inval data. False is returned if no changes were made, otherwise true.

Use lines to specify single or multiple line entry modes. The following listed values are operable (defaults to 1):

SUB.EDIT returns in key the ASCII code for the exit key used.

The value(s) of inpat determines input pattern data validation and conversion. Syntactically as well as operationally, this is exactly the same as an In Pattern operation in the Paint window (see "Data Validation" in the "Adding Advanced Features to Windows with Paint" chapter of Developing an Application in the main system documentation.). Multiple inpat statements are processed as logical OR values, and must be delimited by @VM or |. Inpat is applied to each line if lines specifies multiline or single line scroll mode.

Use outpat to specify output pattern conversion (applied line by line). Syntactically as well as operationally, this is exactly the same as an Out Pattern operation in the Paint window (see reference above under inpat).

Use just to specify display line justification. The possible values are:

The character used to delimit multiple lines of data in SUB.EDIT. This may be an accepted Advanced Revelation delimiter (e.g. @FM), an ASCII code, or a literal character. If delim is null, only single line text entry is enabled, irrespective of any other specifications (this will cause the display of inval data to be suppressed if lines specifies multiline mode).

Defines an input mask. This indicates to the user the length of data expected to be input. The mask is displayed at the current edit line. If mask is a single character, it is repeated for the length of the line.

Defines the length of the edit line (defaults to 64K). If * (asterisk) is specified, the value of displen is used. A carriage return is generated at the end of the line, unless just is T or TN.

A dynamic array of edit session parameters. These parameters are saved in state, allowing recall of a specified edit environment.

If flags <SAVE.STATE$> is set to true, SUB.EDIT saves the current edit environment (as opposed to a specified edit environment) in state, automatically maintaining (updating) these values during the edit session. Any existing state parameters are overwritten.

Note that the state specifications save but do not redisplay the edit session data. This data may be redisplayed by setting the flags <REPAINT$> field (see above).

If state is null, any previous state settings are cleared. The following fields are defined for state (these are also defined in the SCRIBE.STATE.CONSTANTS record of the INCLUDE file):

EQU SS.ORIG.VAL    TO  1
EQU SS.LAST.VAL    TO  2
EQU SS.TOP         TO  3
EQU SS.MVD         TO  4
EQU SS.START       TO  5
EQU SS.POS         TO  6
EQU SS.EDITOR.ON   TO  7
EQU SS.UNUSED1     TO  8
EQU SS.FIND        TO  9
EQU SS.REPLACE     TO 10
EQU SS.STATE       TO 11
EQU SS.BLOCK.START TO 12
EQU SS.BLOCK.END   TO 13

The requirements for the field values are described below:

The following is a list of the argument list parameters in which SUB.EDIT passes values, a description of the value returned, and any conditions governing the return of this value:

/* The following code opens the SAMPLE_CUSTOMER file, then 
reads record number 5.  SUB.EDIT is invoked on this record, 
the edit display window being limited to the dimensions 
specified in the SUB.EDIT calling arguments. */

DECLARE SUBROUTINE SUB.EDIT, MSG, FSMSG

EQU esc   TO CHAR(27)
EQU true  TO 1
EQU false TO 0

file       = "SAMPLE_CUSTOMERS"
rec_key    = 5
title      = "Customer edit"
null    = ""
inval      = ""
protect    =  false
exit.key   = esc
except.key = ""
col        = 10
row        = 5
displen    = 40              ;* 40 character-wide display
color      = ""
flags      = ""
change     = ""
lines      = 8               ;* edit display window 8 lines 
deep
exit       = ""
inpat      = ""
outpat     = ""
just       = ""
delim      = ""
mask       = ""
linelen    = ""
state      = ""

SUB.EDIT(file, rec_key, title, options, inval, protect, |
exit.key, except.key, col, row, displen, color, flags, |
change, lines, exit, inpat, outpat, just, delim, mask, |
linelen, state)