Jaap's Psion II Page

                                CHAPTER 14

                                  ______
                                  EDITOR



There are two distinct editors in the operating system.  In OS itself,  the
LANGUAGE  EDITOR  is used for editing OPL programs, and the LINE-EDITOR, is
used in all other editing situations; the editors can however each be  used
in a wide range of circumstances.  Both can be called by the programmer, so
I will now give a basic outline  of  some  of  the  differences.   Detailed
descriptions are given in sections 14.1 and 14.2 on system services.


The line-editor is used for editing a maximum  of  255  characters  in  the
editor buffer, RTT_BF.  Any text on the display prior to calling the editor
will be treated as a prompt, with  the  text  that  is  editable  displayed
directly  after  it.   If  required,  a string can be set up for editing by
copying it into the editor buffer before calling the editor.


The language editor can be used for editing any text files.  The amount  of
text  that  can be edited is limited only by memory availability.  Free RAM
is allocated to the editor as required.  An existing file can be loaded for
editing in this memory.  A file can be saved with a block file type between
$81 and $8F inclusive, as specified by the programmer (see  chapter  12  on
file handling).  When exiting the editor, the user has the choice of

     1.  translating an OPL program,

     2.  saving the file,

     3.  quitting, in which case everything typed in the editing session is
         lost.

Since any type of text file can be edited (not only  OPL  procedures),  the
programmer can choose to prevent the option to translate the edited file.



      ___________________________
14.1  LINE-EDITOR SYSTEM SERVICES

        _______
14.1.1  ED$EPOS

VECTOR NUMBER:          029
INPUT PARAMETERS:       A register - Bit 0 clear for single-line editing.
                                     Bit 0 set for multi-line editing.
                                     Bit 7 clear for exit on MODE key.
                                     Bit 7 set for no exit on MODE key.
                        B register - Maximum input length.
                        UTW_S0     - Position within line to start editing.
OUTPUT VALUES:          B register - Terminating key.

DESCRIPTION

    This is the standard input line-editor.  The OPL EDIT command uses this
    service.

    A maximum of B characters may  be  edited.   There  are  two  modes  of
    operation, multi-line and single-line editing.  With multi-line editing
    the down arrow key starts a new line of text,  while  with  single-line
    editing the up and down arrow keys send the cursor to the beginning and
    end of the editable text respectively.  A new line  is  represented  in
    the  editor  buffer  by  a  TAB  character  (ASCII  value 9).  Bit 0 of
    register A is cleared for single-line and set for  multi-line  editing.
    The  MODE  key causes the editor to exit only if bit 7 of register A is
    clear.

    The characters displayed prior to calling the editor are treated  as  a
    prompt.   Any  characters  in  the editor buffer RTT_BF are used as the
    default  string  for  editing.   Since  a  TAB  in  the  editor  buffer
    represents  a  new  line,  including  any  in  the  default  string  in
    single-line mode produces unpredictable results.  The default string is
    displayed   directly   after  the  prompt.   The  cursor  is  initially
    positioned UTW_S0 characters beyond the end of the prompt in the  first
    line  (UTW_S0  is  0  for  the first editable character).  If UTW_S0 is
    greater than the length of the editable line, the cursor  goes  to  the
    end  of  the  line.  After editing, the input is returned in the editor
    buffer.  The terminating character is returned in the B register.

    The editor is exited when the EXE key is pressed, or when the  ON/CLEAR
    key  is pressed with an empty editor buffer.  When the editor buffer is
    not empty, the ON/CLEAR key clears it and does not cause an  exit.  As
    explained  above,  the programmer can also choose whether to allow exit
    from the editor when the user presses the MODE key.

EXAMPLE:

    Displays the prompt "Code: " and inputs the code number in single-line
    mode, preventing an exit on pressing MODE. The default code number is
    "0235". The cursor is positioned at the end of the default string (as
    one extra character is expected to be input by the user).

; Display the prompt
        OS      UT$DISP         ; Display the prompt
        .BYTE   #D_FF           ; Clear screen (control character 12)
        .ASCIZ  "Code: "
; Set up editor buffer RTT_BF of length RTB_BL with default string
        LDD     #$3032          ; A='0' and B='2'
        STD     RTT_BF
        LDD     #$3335          ; A='3' and B='5'
        STD     RTT_BF+2
        LDA     B,#4            ; Length of default
        STA     B,RTB_BL
;
        INC     B               ; Maximum input of 5 characters
        CLR     A
        STD     UTW_S0:         ; Cursor at end of line initially
        LDA     A,#80           ; Single-line edit, with no exit on MODE
        OS      ED$EPOS

ERRORS:                None.

BUGS
    In single-line mode, TABs in the default string will still  be  treated
    as new-line markers but will not be handled predictably.



        _______
14.1.2  ED$EDIT

VECTOR NUMBER:          028
INPUT PARAMETERS:       A register - Bit 0 clear for single-line editing.
                                     Bit 0 set for multi-line editing.
                                     Bit 7 clear for exit on MODE key.
                                     Bit 7 set for no exit on MODE key.
                        B register - Maximum input length.
OUTPUT VALUES:          B register - Terminating key.

DESCRIPTION

    Calls the line-editor service routine ED$EPOS  with  0  in  UTW_S0  for
    positioning the cursor initially on the first editable character.

    See ED$EPOS for a full description.

EXAMPLE:

    Input a name.

; Display the prompt
        OS      UT$DISP         ; Display the prompt
        .BYTE   #DFF            ; Clear screen (control character 12)
        .ASCIZ  "Name: "
        CLR     RTB_BL          ; No default string
        LDA     B,#8            ; Maximum input of 8 characters to input
        CLR     A               ; Single-line edit, with exit on MODE
        OS      ED$EDIT         ; Get the name
        CMP     B,#K_MODE       ; Terminated with MODE key?
        BEQ     1$
        RTS
1$:                             ; Here if MODE pressed to stop editing

ERRORS:                 None.



        _______
14.1.3  ED$VIEW

VECTOR NUMBER:          030
INPUT PARAMETERS:       X register - 0 to continue viewing where it left
                                     off last time called; non-zero for
                                     1st view or to start again.
                        UTW_S0     - Initial delay before scrolling (in
                                     1/20 second units).
OUTPUT VALUES:          None.

DESCRIPTION

    Allows the user to view the string  that  is  in  the  run-time  buffer
    RTT_BF with length RTB_BL.  Called by the OPL VIEW function.

    New lines are specified by TABs, and the up and down arrow keys control
    the  line being scrolled.  Two spaces are displayed between the end and
    beginning of any scrolling text.  The left and  right  arrow  keys  are
    used  to  stop, start and change direction of scrolling.  Any other key
    pressed is returned in the B register.

    When called with a new string in RTT_BF (or when the display  has  been
    used since the last call), the X register must be non-zero to view from
    the beginning of the  text.   After  exiting  from  this  routine,  the
    programmer  can  cause  the display to continue at the same place as it
    last stopped, by calling it again with the X register set to 0.

    UTW_S0 specifies the delay (in 1/20 second units) before a line  starts
    scrolling.

    The cursor is switched off during this routine  but  the  cursor  state
    prior  to  the  call  is  maintained.   Corrupts  location DPB_CPOS the
    current cursor position.

EXAMPLE:

    View the 3 lines in VIEW_BUFFER until the EXE key is pressed.

VIEW_BUFFER:
        .ASCII  "(Some interesting data)"
        .BYTE   9                               ; TAB for new-line
        .ASCII  "(End of data)"
        .BYTE   9
        .ASCII  "Press EXECUTE to continue"
END_BUFFER:

DO_VIEW:
        LDD     #END_BUFFER-VIEW_BUFFER
        STD     UTW_S0:                 ; Length of buffer to be copied
        STA     B,RTBBL         ; Set up run time buffer's length
        LDX     #VIEW_BUFFER            ; Source buffer
        LDD     #RTT_BF                 ; Destination buffer
        PSHX                            ; Save non-zero X
        OS      UT$CPYB                 ; Copy VIEW_BUFFER to RTT_BF
        PULX                            ; Restore non-zero X for 1st view
LOOP:
        LDD     #40
        STD     UTW_S0:                 ; Wait 2 seconds before scrolling
        OS      ED$VIEW
        LDX     #0                      ; X=0 for subsequent views
        CMP     B,#13                   ; EXE key pressed?
        BNE     LOOP                    ; No, so loop
        RTS

ERRORS:                 None.

BUGS
    Calling initially with the X register equal to 0 produces unpredictable
    results.



      ________ ______ ______ ________
14.2  LANGUAGE EDITOR SYSTEM SERVICES

      _______
14.3  LG$RLED

VECTOR NUMBER:          078
INPUT PARAMETERS:       None.
OUTPUT VALUES:          None.

DESCRIPTION

    Handles RUN, LIST, EDIT and DELETE commands in the  top  level  PROGRAM
    menu.   LIST,  EDIT  and DELETE can operate on any text file, while RUN
    operates on OPL procedures only.  The name of the file to  be  operated
    on must be in the find buffer RTT_FF with length RTB_FL.  The file must
    exist or an error message will be displayed - new files can be  created
    and edited using the service LG$NEWP.

    The system variable TLB_MODE must be set by the programmer  to  control
    which of the top level commands is performed.  The appropriate settings
    are 1) EDIT         3
    2) LIST             4
    3) RUN              7
    4) DELETE   8

    The standard input language editor can be used  for  editing  any  text
    files  (with  size  limited  only by memory availability).  The file is
    loaded into RAM specially allocated to the language editor.  An  edited
    file can be saved with a block file type between $82 and $8F inclusive,
    as specified by the programmer in the  system  variable  LGB_LANT  (see
    chapter  12  on  file handling).  The types from $81 to $84 are already
    used for specialised file types.
             $82                block file  - saved DIARY
             $83                block file  - OPL procedure
             $84                block file  - saved RS232 setup

    Users wishing to use any of the remaining block file types $85  to  $8F
    should  first  contact  Psion, to avoid incompatibility with any future
    products.

    The system variable LGB_LANT must be set to  the  required  block  file
    type for all the operations handled by LG$RLED.

    When exiting the editor, the user has the choice of

    1.  translating an OPL program,

    2.  saving the file,

    3.  quitting, in which case everything typed in the editing session  is
        lost.

    Since any type of text file can be edited (not  only  OPL  files),  the
    programmer  can  choose  to  prevent the option to translate the edited
    file, by setting the system variable LGB_MENU to  any  non-zero  value.
    Attempting  to  translate  a  non-OPL file will simply produce an error
    message.

    The language editor differs from the line-editor (ED$EPOS) in  the  use
    of cursor and control keys.

    1.  The ON/CLEAR key deletes only  the  current  line  (not  the  whole
        record).

    2.  The down arrow key moves the cursor one line down  the  file.   (It
        does not create a new line).

    3.  The EXE key creates a new line.  (It does not exit the editor).

    4.  A line can be split in two using the EXE key.


EXAMPLE:

    Allows the editing of the non-OPL (type $8F) text file named "P".

        LDD     #256+^A/P/      ; A=1, B='P'
        STD     RTB_FL          ; FIND buffer contains 'P'
        LDD     #$8F01          ; Block file type and also no translate
        STD     LGB_LANT        ; Set LGB_LANT and LGB_MENU which are in
                                ;   consecutive bytes in memory
        LDA     A,#3
        STA     B,TLB_MODE:     ; Edit mode for LG$RLED
        OS      LG$RLED

ERRORS:                 None.



      _______
14.4  LG$NEWP

VECTOR NUMBER:          077
INPUT PARAMETERS:       None.
OUTPUT VALUES:          None.

DESCRIPTION

    Calls the language editor to create a new file.

    This is identical to LG$RLED when  it  is  operating  in  editing  mode
    except that the file to be edited is created.

    See LG$RLED.

EXAMPLE:

    Creates the OPL file "Q" and lets the user edit and translate it.

        LDD     #256+A/Q/       ; A=1, B='Q'
        STD     RTB_FL          ; FIND buffer contains 'Q'
        LDD     #$8300          ; OPL block file type and allow translation
        STD     LGB_LANT        ; Set LGB_LANT and LGB_MENU which are in
                                ;   consecutive bytes in memory
        OS      LG$NEWP

ERRORS:                 None.



      _______
14.5  TL$XXMD

VECTOR NUMBER:          104
INPUT PARAMETERS:       A register - Bit 0 clear for single-line editing.
                                     Bit 0 set for multi-line editing.
                        B register - Maximum input length.
                        X register - Addr of prompt excluding " D:"
                                        (leading count byte string)
OUTPUT VALUES:          Carry flag - Set if ON/CLEAR pressed.

DESCRIPTION

    Typically used to edit a filename, with the  MODE  key  being  used  to
    select a PACK as in "FIND A:".

    TL$XXMD clears the screen, prints a leading  count  byte  string  at  X
    followed  by  a  space,  a  device  letter 'A' to 'C' and a colon.  The
    system service ED$EDIT is then called to edit a line of text, typically
    a  file  name.   ED$EDIT  will edit text in the form of a leading count
    byte string at RTB_BL.  The A and B registers are saved at the start of
    TL$XXMD  and  passed  to ED$EDIT.  The A register will usually be zero,
    indicating single line editing and that ED$EDIT should  exit  when  the
    MODE key is pressed.  B is the maximum input length.

    The device letter is determined  by  TLB_CPAK.   If  the  MODE  key  is
    pressed,  the  device  letter  displays  the  next  available pack, and
    TLB_CPAK is set appropriately.  TL$XXMD  returns  when  either  EXE  or
    ON/CLEAR  is  pressed.   If  EXE  was pressed to exit from TL$XXMD, the
    carry is returned clear.  If ON/CLEAR is pressed, the carry is set, but
    the  B  register  is undefined.  On exit the device selected is held in
    TLB_CPAK.

    See section 14.1.2 ED$EDIT.

    NOTE :  TL$XXMD will not work if bit 7 of A is set since  this  ED$EDIT
    will not exit when MODE is pressed.

    ERRORS

        carry is set if ON/CLEAR pressed, but B is undefined

    EXAMPLE

    ;   TO INPUT A FILE NAME, STORE IT AS A LEADING COUNT BYTE STRING AT
    ;   FILE_NAME IN THE FORM "D:NNNNNNNN"

                CLR     RTB_BL          ; NO PREVIOUS NAME IN EDITOR WORK AREA
    1$: LDX     #PROMPT
        LDD     #8              ; A=0, B=MAX INPUT LENGTH
        OS      TL$XXMD
        BCS     ON_CLEAR_PRESSED

        LDD     #^A/A:/         ; MAKE INTO THE FORM "A:NNNN"
        ADD     A,TLB_CPAK:     ; A = TLB_CPAK+'A'
        STD     FILE_NAME+1
        LDA     B,RTB_BL        ; GET LENGTH OF EDITED TEXT
        BEQ     1$              ; IF ZERO LENGTH, TRY AGAIN

    ;   COPY TO DESTINATION

        CLR     A
        STD     UTW_S0:         ; NUMBER OF BYTES TO COPY
        ADD     B,#2            ; TWO MORE INCLUDING "A:"
        STA     B,FILE_NAME     ; STORE NEW LENGTH BYTE
        LDX     #RTT_BF         ; COPY FROM EDITOR WORK AREA
        LDD     #FILE_NAME+3
        OS      UT$CPYB