EXTCTL:  Extended options

(Optional) A composite (unformatted) variable used for additional return status and control options. It should be mapped as:

MAP1 EXTCTL

MAP2 EXTCOD,B,2  ! exit code

MAP2 EXTERR,B,2  ! exit error status

MAP2 EXTMAP,B,4  ! exit code enable bitmap

MAP2 EXTCOL,B,2  ! cursor column

MAP2 EXTROW,B,2  ! cursor row

MAP2 EXTBYT,B,4  ! # bytes in memo

MAP2 EXTHIT,B,2  ! # rows

MAP2 EXTWID,B,2  ! longest row length

MAP2 EXTPRW,B,2  ! # protected rows

MAP2 EXTSMI,S,1  ! start menu item char

MAP2 EXTEMI,S,1  ! end menu item char

MAP2 EXTMRW,B,2  ! error message row

MAP2 EXTTOP,B,2  ! top window offset

MAP2 EXTLFT,B,2  ! left window offset

MAP2 EXTPCL,B,2  ! # protected columns

MAP2 EXTTIM,B,2  ! max inter-char timeout

MAP2 EXTLIN,B,2  ! MMO'LIN max; see TEXT

MAP2 EXTMGN,B,2  ! MMO'LIN margin; see TEXT

MAP2 EXTOTH,B,2  ! (A-Shell only) other menu exit keys:

! 02 = left arrow (EXITCODE -40)

! 04 = right arrow (EXITCODE -41)

! 08 = up arrow (EXITCODE -42)

! 16 = down arrow (EXITCODE -43)

! 32 = tab key (EXITCODE -44)

MAP2 EXTJNK,X,14Þ ! for expansion

The EXTCTL parameter provides access to a number of extended memo control capabilities, and leaves room for future expansion.

EXTCOD is similar to the EXITCODE parameter in INFLD; it receives a code indicating how the memo was exited. The codes are defined as symbols in the MMOSYM.BSI include file:

MMX'OK

0

Normal Updated exit

MMX'QUI

1

Non-Updated exit (Control-C)

MMX'VTS

2

Non-Updated exit (VSPEC too small)

MMX'TIM

4

Updated exit (time out)

MMX'TAB

7

TAB used to select menu item

MMX'SPC

13

Spacebar used to select menu item

 

-#

Command function exit *

 

* Command function exits are returned as negative numbers F1=-1, etc.

EXTERR contains a value indicating various errors. These are also defined in the MMOSYM.BSI include file:

MME'ERR

2

abnormal exit (see POS)

MME'SAF

1

failure to save or restore area

MME'OK

0

normal exit

 

You may wonder why we had to add two variables to return errors and status instead of just one. The reason is some of the MME' errors can be independent of the MMX' exit status, particularly MME'SAF.

Note that for convenience you can check EXTERR prior to checking the POS parameter for errors; if EXTERR is not equal to MMX'ERR then you don't need to check for POS errors.

When checking for function key exit codes in EXTCOD, keep in mind that since Basic binary variables (less than 5 bytes) are unsigned, negative numbers actually appear as very large positives. If you want to transfer them to signed floating-point variables, use this formula:

FLT = EXTCOD - 65536

If you are using exclusively Alpha BasicPlus, which supports signed integers (data type I), then you won't have this problem if you map the binary parameters as I,2 instead of B,2. (The internal format of these two-byte types is identical, only the interpretation of negatives is different.) Be careful, though, that you do not assume signed behavior if you are using a mixture of Basic and BasicPlus; it may be better to live with the unsigned B format since it behaves the same under both Basics.

EXTMAP is a bitmap used to specify which command key exit codes you want to enable by setting the corresponding bit. Bit 0 = F1, Bit 5 = F6, Bit 31 = F32. If the EXTCTL parameter is omitted or EXTMAP is zero, no command key exits will be allowed. Command key exits work just like the Escape key (memo is updated) except that they return a code in the EXTCOD parameter indicating which function key was used.

EXTROW and EXTCOL will return the position of the cursor on exit, relative to the virtual space of the memo. 0,0 is the upper left corner of the memo. These can also be used with the MMO'CXY opcode to force the cursor to start in a particular position.

EXTBYT returns the physical size of the memo written to the disk, in bytes, not counting the links or the bytes unused in the last physical memo record.

EXTHIT returns the height (max row) and EXTWID returns the width (max col) of the updated memo.

EXTPRW contains the number of rows, starting from the top, to be designated as protected. Protected rows may be displayed, but the cursor is not allowed to move up to those rows. Although the protected area may only consists of a whole number of lines, starting from the top, it may be specified relative to the top (using positive numbers) or bottom (using negative numbers). For example, EXTPRW = 5 would protect the top 5 rows, whereas EXTPRW = -2 would protect all but the bottom row. EXTPRW = -1 protects the entire (existing) memo, which in effect puts the user in append-only mode.

EXTSMI and EXTEMI may be used optionally to specify alternate free form menu item delimiter characters. If not specified, the defaults are "[" and "]".

EXTMRW may be used optionally to specify where unusual messages (e.g. File full, Memo link error, etc.) are displayed. Otherwise they display on line 24 or within the memo box.

EXTTOP and EXTLFT may be used optionally the scrolled position of the editing window within a larger memo. For example, if you set them to 5 and 10, respectively, the memo window would start out with the upper left corner of the window over row 5, column 10 of the memo.

EXTPCL contains the number of columns, starting from column 1, to be designated as protected. Protected columns are displayed, but the cursor is not allowed to into those columns, and some editing operations which would damage those columns (such as delete line and concatenate lines) are disallowed. Under A-Shell, when you are preloading text (such as a date stamp) into a memo, the protection is turned off during the preload, allowing you to put the date stamp in the protected area.

EXTTIM may be used to specify a maximum number of seconds of no keyboard activity (to avoid letting a memo be kept in use indefinitely by someone forgetting to exit.) The timer is reset after each character input. If the timer expires, INMEMO saves and exits, as if the user had exited normally with the Escape key, except that the EXTCOD parameter is returned as MMX'TIM (4) instead of MMX'OK (0).

EXTLIN and EXTMGN are used with an A-Shell-only feature in which you can use the MMO'LIN opcode to output an entire memo to a sequential output (print) file in one step rather than one line at a time. (See the description of the TEXT parameter for more information on invoking that feature.) In this mode, EXTLIN may be used to set a maximum limit on the number of lines output (presumably to avoid going beyond the end of the current page.) The next call (assuming the parameters are not disrupted) will continue from where it left off (presumably after the program did whatever was appropriate to start a new page of output.) Leaving EXTLIN set to 0 removes the maximum limit. EXTMGN may be used in this mode to specify a left margin for the lines output, allowing you to align them in a particular column of the report.

EXTJNK was defined to allow for additional expansion without requiring you to reallocate your parameter space