INTRODUCTION

This manual is the main reference document for the Laser-Scan Cartographic Editor LITES2. It is intended for any person who uses LITES2 and it describes the editor environment and use, and each editor command in detail.

LITES2 is an interactive graphical editing program which has been designed to be particularly suitable for work with cartographic type data, but can also be used on other types of feature-orientated data. It has facilities for reading, drawing, amending, creating, and deleting features.

It is assumed that the user is already familiar with general use of the VAX/VMS operating system (see the DEC VAX/VMS manuals), and with the principles of digital cartography. This manual is supplementary to the "LITES2 User's Guide", which should be read before any use is made of LITES2, and before referring to this document.

This manual describes the full LITES2 command language, including some commands which are included for compatibility with future enhancements. The presence or absence of any facility from this manual does not imply any future commitment by LSL. See the current version of the LITES2 SPS (Software Product Specification) for a description of currently supported facilities.

LITES2 is a reimplementation of the previous LSL cartographic editor LITES1, (variously referred to as LITES, MADES, IGES, or SOLADI). The reimplementation has achieved the following major advances over LITES1.

ENVIRONMENT

COMPUTER

LITES2 runs on Digital Equipment Corporation (DEC) VAX series computers, running under the VMS operating system. Sufficient disc space must be available to hold input, workspace, and output versions of the IFF file containing the map being edited, as well as about 5M bytes for program images and static data files. An appropriate graphics workstation must also be available (see below) if graphic interaction is required.

For further details of the VAX computer series, see the DEC documents 'VAX Technical Summary', and the 'VAX Handbooks' (which describe the Architecture, Hardware, and Software of the machine).

For further details of VAX/VMS, see 'VAX Software handbook', published by DEC. Other manuals of direct relevance to the user of this manual are 'Introduction to VAX/VMS', and 'VAX/VMS Command Language Reference Manual'.

Refer to the LITES2 SPS (Software Product Specification) for currently supported VMS versions and hardware and software prerequisites.

WORKSTATION

LITES2 can be run without graphic interaction on any DEC-compatible alphanumeric terminal eg VT320 VDU.

For graphic interaction it requires an LSL-supported GKS workstation configuration. This can include either one or two graphics screens (referred to as primary and secondary displays). Refer to the LITES2 SPS (Software Product Specification) for currently supported workstation types.

The refresh capability of the graphical display serves to provide a positional marker or cursor on the screen, to highlight features selected on the screen and to provide temporary display within graphical constructions.

FILES USED BY LITES2

INPUT DATA

LITES2 is used to display and edit map data. At initialisation it reads one or more IFF files of map data and other files containing information about the graphic representations of features, layout of menus, tailoring options etc. At the end of a session, new edited versions of the IFF files are produced.

Each IFF file contains a single MAP. Data within a map may be grouped into LAYERS (sometimes known as OVERLAYS). The basic elements of map data are called FEATURES. The editor deals with twelve different categories or graphical types of feature. See the FRTLIB Reference Manual for details of treatment of graphical types. The list is:

         1      line string
         2      clockwise arc 
         3      anticlockwise arc
         4      three point arc
         5      full circle
         6      curve
         7      unoriented symbol
         8      oriented symbol
         9      scaled symbol
        10      text string
        11      symbol string
        12      fill area

LOGICAL NAMES

For LITES2 to run successfully, certain logical names must be set up to point to directories and files used by the program. These will normally be set up automatically, but there may be a need to alter them for special purposes.

Logical name LSL$LITES2LOCK must be set to the full file specification of a file containing the LITES2 licence.

Logical name LSL$LITES2WORK must be set to a directory in which LITES2 is to put workspace and dump files. If a LITES2 session is terminated abnormally (e.g. by computer failure, or CTRL/Y) then the workspace file will be left in this directory, so the directory should be checked periodically, and old versions of files deleted.

Logical name LSL$LITES2CMD must be set to a directory in which LITES2 expects to find command files (default extension .LCM). The edgematching problem file is written to this directory.

Logical name LSL$LITES2JNL must be set to a directory into which LITES2 writes a journal file of commands given during a session (extension _.LJN). It is advisable either to regularly purge this directory, or to set a version limit on it (using the DCL command SET DIRECTORY/VERSION_LIMIT=n), so that journal files do not build up without limit.

Logical name LSL$LITES2SETUP must be set to a directory in which LITES2 preserves table setup parameters for use in future sessions (extension _.SET). It is often convenient to use the same directory as LSL$LITES2JNL for this.

If the logical name LSL$LITES2TERMINAL is set to a string, then this string is used as the terminal name when naming device dependent files. If LSL$LITES2TERMINAL is not assigned then the logical translation of SYS$COMMAND is used as the terminal name.

If the logical name LSL$LITES2ROUTINES is set to the full file specification of a shareable image containing the LITES2 user routines, then the LITES2 command USER will execute the code in this image.
Similarly the logical names LSL$LITES2ROUTINES_n (where n is an integer in the ranges 1 - 5 or 101 - 105) supply the images to be executed with the corresponding ROUTINE command.
See the chapter on user routines for details of how to create your own user routines. If these files are not present, then the corresponding LITES2 commands will not be available.

Logical name LSL$IF must be set to a directory in which LITES2 expects to find IFF files (input and output map data).

Logical name LSL$FRT must be set to a directory in which LITES2 expects to find FRT, SRI, and TRI files (feature representation files).

Logical name LSL$DTI must be set to a directory in which LITES2 expects to find DTI image files.

Logical name LSL$LSI must be set to a directory in which LITES2 expects to find LSI image files.

Logical name LSL$LSR must be set to a directory in which LITES2 expects to find LSR image files.

Logical name LSL$HELP must point to the directory containing the LITES2 help library, LITES2.HLB. This may be used outside LITES2 by typing e.g. $ HELP_/LIBRARY=LSL$HELP_:LITES2.

If the logical name LSL$LITES2INI is set to a file specification, then the contents of this file will be read as a series of LITES2 commands, when the program is first invoked (see section 4.3 below).

By default the maximum number of user macros that may be declared is 600. This value may be altered by defining the logical name LSL$LITES2_MACROMAX to be the appropriate number.

By default the maximum number of menu squares and puck buttons that may be declared is 500. This value may be altered by defining the logical name LSL$LITES2_MENUSQUAREMAX to be the appropriate number.

By default the maximum number of user variables that may be declared is 1000. This value may be altered by defining the logical name LSL$LITES2_VARIABLEMAX to be the appropriate number.

As in other Laser-Scan programs which are able to fill areas, the maximum number of points allowed in a solid filled area may be controlled by defining the logical name LSL$FILL_POINTSMAX to be the required number. The default value is 8192 points, with the minimum allowed being 100. Exceeding the limit for number of points will result in fill areas being drawn incorrectly or being drawn as an outline. When drawing raster images, LITES2 uses the same logical name to control the maximum number of pixels that can be drawn across an image, so the message "Buffer too small to draw DTI/LSR - zoom in or increase LSL$FILL_POINTSMAX" can be avoided in a future run of LITES2 by increasing the value of this logical name. Similarly the maximum number of times which a scan line may cross the boundary of an area may be controlled by defining the logical name LSL$FILL_CUTSMAX to be the required number. The default value is 100 intersections, with the minimum allowed being 10. Exceeding the limit for intersections will result in messages 'FILL_SIDE - Too many intersections found - ignored'. Memory has to be allocated in proportion to these numbers, so unnecessarily large values should be avoided.

If the logical name LSL$IFF_OUTPUT_REVISION is set to the value 1, then the IFF files that LITES2 outputs will contain CB entries and edits made to point attributes will be retained. If, however, LSL$IFF_OUTPUT_REVISION is set to the value 0, or is not set up at all, the IFF files that LITES2 outputs will contain ST (and ZS entries). The commands which add other attributes will still appear to work, but the attributes will not appear in the file.

The logical names LSL$TEXT_ROUTINE and/or LSL$SYMBOL_ROUTINE may be set to point to shared images that can be used to draw texts and symbols differently from the standard FRT routines used by LITES2. More details of this facility is available in the chapter on alternative text and symbol drawing routines.

The logical name LSL$LITES2_GET_SHEET_ROUTINES may be set to point to a shared image which can be used to supply a user defined map indexing system. This image is then called when the system variable $MAP_SHEET is accessed. This substituted routine may be passed either the absolute position of the cursor or its geographical position. Example source files that contain instructions to build this image are supplied in LSL$PUBLIC_ROOT:[LITES2.ROUTINES.EXAMPLES] and are called GET_SHEET_GEOG_EXAMPLE.FOR and GET_SHEET_GRID_EXAMPLE.FOR.

If this logical name is not set up, the variable $MAP_SHEET will use the sheet naming convention specified for the Ordnance Survey of Great Britain.

If the logical name LSL$OS_MH_TABLE points to a file name, this file will be opened and read as a translation table to locate the update flags in OS map headers type 3 and 4 for use with the OPERATION OS_MH_FLAGS command. If this logical name is not set up prior to invoking LITES2, it will not be possible to read IFF files with these type of map headers if an OPERATION OS_MH_FLAGS command has been given, or it will not be possible to give an OPERATION OS_MH_FLAGS command after reading IFF files that have these type of map headers. See the CONVERT package documentation for details of this table and the logical name.

The logical name LSL$LITES2_TERMINATOR_MASK may be used to control which characters will be taken as line terminators when typed at the terminal. It should be defined as a comma-separated list of ASCII codes and ranges of codes (use quotes if the list contains commas, otherwise a search-list will result). For example
_$ DEFINE LSL$LITES2_TERMINATOR_MASK "13,26,128-159"
would cause carriage-return (13), Ctrl-Z (26), and also the upper control characters (128-159) to terminate lines.

If the logical name is not defined, then it is left to the VMS terminal driver to decide which characters are terminators. This is affected by the command
_$ SET TERM/LINE_EDITING

The purpose of this is to allow characters which would by default have terminated the line to be input as characters, for example into text strings or AC entries. Note that even if they are set not to terminate the line, most control characters will not echo as anything sensible at the terminal.

Certain functions in LITES2 are supplied as shared images, which are only mapped when they are first accessed. This keeps the LITES2 image smaller, and thus more efficient, for those users who do not require the extra functionality that these shared images supply. These shared images are pointed to by the following logical names:

FILES CREATED BY LITES2

WORKSPACE FILES

Maps read in by the IFF command are copied to a workspace IFF file LSL$LITES2WORK:filename.WRK. This file is operated on during the editing session, and is normally deleted at the end, unless the DUMP command is used, when it is renamed as LSL$LITES2WORK:filename.DMP and may be used for subsequent input to LITES2. The dump file is a valid IFF file, and may be used as such by other programs, but as a result of editing it may contain dead space, and the layers are likely to be fragmented. For this reason, it is advisable to finally use the EXIT or WRITE command to cause the workspace file to be tidied into a new version of the IFF file.

JOURNAL FILE

During a session, LITES2 writes all commands issued to a file LSL$LITES2JNL:terminal.LJN (where "terminal" is either the SYS$COMMAND device, e.g. TTA0, or the name defined by the logical name LSL$LITES2TERMINAL). Optionally, any macros or command file directives may be journalled, but preceded by the comment delimiter (_!), so that the file may be used as command input to LITES2 to recover a session lost for any reason. (See Recovery.)

TABLE SETUP FILE

LITES2 saves the information concerning the positions of maps, menus, and tracking areas in a file LSL$LITES2SETUP:terminal.SET. This enables the old positions to be re-used in another LITES2 session, without re-digitising. (See Table Setup.)

EDGEMATCHING PROBLEM FILE

The edgematching routine writes a LITES2 command file LSL$LITES2CMD:terminalPROB.LCM, usually overwriting any previous version. If however ENABLE APPEND has been given, the LITES2 commands are added to any existing version of the file.
This file is automatically invoked by the REVIEW command, to guide the operator through any problems encountered while edgematching.

SAVE MACRO FILES

The SAVE MACRO command causes a file LSL$LITES2CMD:macroname.LCM to be written for subsequent input to LITES2.

SECTOR LIST FILE

The SAVE SECTORS command causes a file LITES2.PRT to be written to the current directory. This is intended as a program development aid.

USING LITES2

RUNNING THE PROGRAM

In order to run LITES2, you must be logged in to VMS at a terminal. See your System Manager if you do not have the Username and Password required to do this.

At some sites, the system manager will have included LITES2 as part of a captive command procedure so that the user will not have to give the actual command to start up LITES2. However, if you are presented with the "$" (dollar) prompt, then you can start up the program by typing

LITES2

The program will announce itself as

LITES2 ([version]) V[n] of [hh:mm:ss dd-mmm-yy]",

where [version] is the name of the hardware specific version of LITES2 in user, [n] is the version number, and [hh:mm:ss dd-mmm-yy] is the time and date of linking of this release. This is followed by a message indicating the licensed users of this version.

There will then be a pause while first stage initialisation is carried out, and normally an initialisation command file containing options and menu definitions will be read. You will then be presented with a prompt from LITES2, which is an asterisk by default, but may have been changed in the initialisation command file eg

*

and commands to the program may be given (eg HELP).

COMMAND STATES

There is underlying structure to editing operations, which often need to be performed in a certain sequence or in the correct context. This structure is reflected in the fact that LITES2 is always in one or other of a small number of command states. Within each state, a given range of commands is valid and certain commands or operator actions are used to move between states. The main command states and their transitions are shown diagramatically in the figure below.

On starting up, the editor is in INITIAL state in which options and attribute files can be specified, and which continues until the commands have been given which specify the map file(s) to be edited. The map is then read-in to the workspace file, and optionally drawn. The editor then enters READY state. It is possible to return to INITIAL state by using EXIT, DUMP, or QUIT commands when DISABLE EXIT is in operation.

The majority of commands are available in READY state, which is the principal operating level of the editor. LINE state is entered when a linear feature is identified using the FIND command. TEXT state and SYMBOL state are the equivalents for text features and symbols.

EDIT state and MODIFY state are both entered as the result of editing operations which require an END command to terminate. ON state is entered by commands which require the cursor to be constrained on a linear feature. CONSTRUCT state is entered during construction of linear features.

WINDOW state is entered by a WINDOW command to allow specification of an area of the map to be enlarged onto the graphics screen, or by a REGION WINDOW command for constructing a rectangular region. MACRO state is entered while defining macro commands. AC state is entered to allow editing of ancillary coding (AC/TC/CH entries). SETUP state is entered while digitising map corners on a raster image on the screen. PAINT state is entered while editing a raster image using the IMAGE PAINT command.

The current program state is displayed by the command SHOW STATE. It is also displayed in the status line (ENABLE STATUS), and is used as a prompt if PROMPT STATE is in action. System variable $STATE is set to the current state.

The possible program states are:
INITIAL   - Awaiting specification of input maps (IFF files)
READY     - Ready for an editing command, no operations in progress
LINE      - Line type feature found
CIRCLE    - Circle arc feature found
TEXT      - Text feature found
SYMBOL    - Symbol feature found
EDIT      - Edit operation on line type feature in progress
MODIFY    - Modification of text or symbol feature in progress
ON        - Constrained on line feature during part edit operation
WINDOW    - Defining a window for drawing
CONSTRUCT - Constructing a line type feature, or a BRIDGE
AC        - Editing ancillary codes of a feature or attribute set
DEBUG     - Not used
RECOVER   - Deleted (or 'limbo') feature found
SETUP     - Setting up corners of IFF files on a raster image
PAINT     - Editing a raster image using the IMAGE PAINT command
MACRO     - Defining a macro


                           INIT state
                               |
                          (IFF/READ commands)
                               |
                               V
                           READY state
                               |
        +------------------+---+------------+----------+--------+
        |                  |                |          |        |
        |                  |                |          |        |
(FIND text/symbol)    (FIND line)    (construct line)  |  (WINDOW command)
        |                  |                |          |        |
        V                  V                V          |        V
   TEXT or SYMBOL     LINE state    CONSTRUCT state    |   WINDOW state
      states         /        |                        |
        |           /         |                        |
        |          /          |                        |
        |         /           |                        |
        |        /            |                        |
  (editing command)     (constraining)         (MACRO command)
        |                     |                        |
        |                     |                        |
        V                     V                        V
 EDIT or MODIFY state     ON state                MACRO state

LITES2 INITIALISATION

When started up, LITES2 implicitly obeys the command @LSL$LITES2INI, thus, if logical name LSL$LITES2INI is set up to point to a file (with defaults LSL$LITES2CMD:---.LCM), then this will be executed. This mechanism is normally used to tailor LITES2 for a particular application.

Next, LITES2 obtains the device name from the translation of LSL$LITES2TERMINAL if it exists, or else from SYS$COMMAND. This will normally be the user's login terminal e.g. TTA0. This is used to gain access to several files specific to this terminal. The command @terminal is implicitly obeyed, so that if, for instance, the user is on TTA0, the file LSL$LITES2CMD:TTA0.LCM will be obeyed if it exists. This mechanism is normally used to configure LITES2 for the particular hardware available on each terminal line, or to set up menus and pucks.

Finally LITES2 obeys any commands given on the DCL command line, and is then ready for interactive input. If LITES2 is to be run non-interactively, then the commands for the complete session should be contained in the initialisation files or command line. (These may of course invoke other command files.)

Certain LITES2 commands ("privileged commands") are only valid if encountered in initialisation files, so that a degree of control may be exercised over the use of these by ordinary users.

While reading initialisation files, the "Now in state..." messages are suppressed independently of the setting of ENABLE NOW, so that the defining of menus or pucks or other macros does not cause an excess of messages to be output.

LITES2 RECOVERY

If a LITES2 session is lost for any reason (e.g. computer failure, operator error), then there are two possible ways to recover it. The preferred route is to utilise the journal file, but it may also be possible to use the workspace file if this still exists.

RECOVERY FROM THE JOURNAL FILE

Find out the name of the terminal on which the session was run (e.g. TTA0), possibly using the DCL command SHOW TERMINAL. If LSL$LITES2TERMINAL was used, then the translation of this will be needed instead. Look for the journal file, LSL$LITES2JNL:terminal.LJN. If any sessions have been run at this terminal since, the required journal file may not be the most recent version, so check the file's creation date.

Check that the file is complete. If the file is LOCKED, then use the DCL command UNLOCK on it. If part (or all) of the file appears to be missing, and the number of blocks used is less than the number of blocks allocated (as shown by the DCL command DIRECTORY), then use the DCL command SET FILE/END_OF_FILE, and then edit to remove any garbage at the end. If necessary, edit the file. If for instance the session was lost due to the operator accidentally typing QUIT, then the QUIT command must be removed, otherwise it will be executed again.

It is advisable to RENAME or COPY the journal file to a different filename, to avoid confusion when LITES2 creates another of the same name. It is convenient to rename the file into LSL$LITES2CMD: with extension .LCM, so that the directory and extension need not be specified when it is used e.g.
$RENAME LSL$LITES2JNL:terminal.LJN LSL$LITES2CMD:CRASH.LCM
where CRASH is a name of your choice.

Define logical name LSL$LITES2REC as the journal file, e.g.
$DEFINE LSL$LITES2REC CRASH (if file is LSL$LITES2CMD:CRASH.LCM)
and run LITES2.

The command in the recovery file will be read instead of any initialisation files. It will be necessary to set up maps on the table if this was done in the original session. After reading the recovery file, provided that it does not contain an EXIT, DUMP, or QUIT command, LITES2 will prompt for interactive input, and editing may be continued.

Finally DEASSIGN logical name LSL$LITES2REC, so that LITES2 does not use the recovery file for the next session. Delete the recovery file when it is finished with.

While reading a recovery file, LITES2 always continues on error, whether or not ENABLE CONTINUE has been specified.

RECOVERY FROM THE WORKSPACE FILE

It may be possible to use the workspace file to recover a LITES2 session. The workspace file is a valid IFF file, and may be input to LITES2 as an IFF file in the usual way. It will usually be necessary to mend the workspace file before use using the IMP utility IMEND (which replaces the old MIFF and IFT), as it will not have been closed correctly. It is probable that one block (and possibly more) of the workspace file will not have been written to disk when LITES2 terminates abnormally. If the missing block is at the end of the file, then the result will just be the loss of some data, but if a block in the middle of the file is missing, then it may be impossible to access the data after it.

If using the workspace file for input, then great care should be taken to ensure that data is not lost.

INTERACTIVE DEVICES

Each version of LITES2 supports a number of interactive devices, such as digitising tables and bitpads, in addition to a keyboard. For details of the particular hardware supported by each version, see the appropriate Workstation Guide. Nevertheless some general principles apply:

If a digitising table is used, then it will be possible to set up source documents (maps), menus, and a tracking area on it. The digitising puck will normally have more than one button on it, and in this case each button may be programmed to execute a LITES2 command. The lowest numbered button is usually reserved for tracking the screen cursor around the map, or tracking area, and may not be programmed to do anything else. If any other button is pressed while within a map or tracking area, the cursor will be positioned to the appropriate place before the button's own command is obeyed, so it is not compulsory to track the cursor to the correct place first using the lowest numbered button. Some LITES2 commands cause the screen cursor to move to a computed position, for instance CLOSE and LOOP (which create closed loops), and FIND (which moves onto a nearby feature). If the next command after one of these is given from a puck button, then no cursor movement will occur even if within a map or tracking area. This allows, for instance, an END command to be given without spoiling the computed cursor position, or having to move the puck off the map area. Any button (but sometimes not the lowest numbered button) may be used to access a menu box, but a facility exists (PRIORITY PUCK) to cause certain buttons to perform their puck functions even when pressed over a menu.

The same comments as for tables apply to bitpads (tablets), but there are some differences. Source documents may not be set up on bitpads (they are usually too small and inaccurate). Bitpads are always connected locally to the workstation, and can perform some sort of cursor tracking on the screen without the intervention of the computer - this often leads to LITES2 having two screen cursors - its own position and the bitpad position. In these cases, the lowest numbered button on the bitpad puck causes the LITES2 cursor to move to the position of the bitpad cursor. Because of this local tracking, there is not usually any reason to set up a tracking area on a bitpad. The other buttons may be used to access bitpad menu boxes, or be programmed in their own right.

If a screen menu is provided, then it is usually accessed by moving the bitpad cursor to the required box and pressing the lowest numbered button.

LITES2 TABLE SETUP

If a digitiser is in use, then before reading in maps, or when the SETUP AGAIN command is used, LITES2 will prompt the user to digitise the positions of maps, menus, and tracking areas. At this point, the user may digitise the points as requested, but also has the chance to abort the setup, or to use the setup from a previous LITES2 session if possible.

The setup of a map, menu, or tracking area may be aborted by pressing CTRL/C at the keyboard (Control and C keys pressed simultaneously), or by pressing the highest numbered button on any puck (provided that the puck has been defined using the PUCK command).

The previous setup values may be used by pressing the penultimate button on any puck (again providing that the puck has been defined).

USE OF CTRL/C

LITES2 has its own CTRL/C handler, so that CTRL/C (pressing Control and C simultaneously at the keyboard) may be used for several purposes. Note that which function occurs will depend on what the program is doing at the time. The functions of CTRL/C are as follows: If enabled, then CTRL/Y will return to a DCL prompt as usual. If done by accident, then CONTINUE (or C) will continue with LITES2.

MESSAGES AND ERRORS

LITES2 has 4 types of messages which can be output to the alphanumeric terminal, indicating conditions of varying severity.

Some messages are purely informational and are sometimes unsolicited, and sometimes the result of an operator command requesting the information. These are known as 'INFORM' type messages, and may be suppressed if required using the DISABLE INFORM command.

The sort of operator errors which are expected to occur occasionally, such as failing to find a feature, or an invalid command, result in the production of a 'MOAN' type message, which is preceded by '???', and is usually accompanied by an audible warning.

'NASTY' type messages are preceded by '!!!' and should not normally occur. They usually indicate that an internal consistency check has failed, which may lead to catastrophic failure of the program.

The final type of message is 'LEARN' type, which is preceded by '...'. These are only output if ENABLE LEARN is in operation, and are intended to provide extra information while learning to use the program.

The occurrence of a 'MOAN' or 'NASTY' error will result in any macros and command files being abandoned, and LITES2 returning to interactive input, unless ENABLE CONTINUE is used.

EDITING OPERATIONS

FEATURE SELECTION

A fundamental concept of the editor is the concept of the FOUND-FEATURE, and of the FEATURE-IN-HAND. The found-feature is a feature selected by the operator to be the subject of editor operations. Selection is normally by positioning the cursor close to the desired feature and issuing the FINd command, but there are alternative provisions for finding a feature by global searches. Refer to the FIND, SEARCH, and LOCATE commands below for more information.

When an editing command is given, any found-feature becomes the FEATURE-IN-HAND in order that a second feature can be found if needed for the editing operation. For example, during a complex editing operation such as JOIn, there will be both a feature-in-hand which is the line to join from, and also a found-feature, which is the line to join to.

The current found-feature, and feature-in-hand, if any, are highlighted in refresh mode on the display screen. For linear, arc, curve and symbol string features, the string of line segments linking the data points is highlighted (or a portion of it if the whole cannot be refreshed). For symbol features the whole symbol is highlighted. For text features each character is highlighted, or on some workstations a highlighted box is drawn around the text,

ATTRIBUTES OF POINTS

When carrying out geometrical edits on features which have attributes associated with their defining points, it is not always possible, or meaningful, to retain these attributes.

In particular, when linear features are FILTERed, then the whole new feature will be created with no point attributes. (Note that squaring and offsetting does retain point attributes)

When new points are created within features (e.g. with the various PART operations or with the CLIP, INSERT or BRIDGE commands) then the new point created does not inherit any of the attributes of the points adjacent to it. When JOINing two features together, two points are condensed into one; in this case the resulting point inherits the attributes of the point that was found when the JOIN command was given.

LITES2 COMMAND LANGUAGE

This section is not concerned with the functions of LITES2 editing commands, which are described individually below, but rather with the use of the command language and programming facilities to set up menus and pucks, and to combine the primitive operations into more sophisticated procedures. Where a particular command is mentioned, its exact syntax and function should be looked up in the individual descriptions.

COMMAND LINES

LITES2 command lines are lines of text, up to 255 characters long, which may be obtained from the keyboard, or other interactive controls, or from a command file on disc. (The interactive interface ensures that button presses and menu probes have the identical effect to typing commands at the keyboard.)

A command line consists of zero or more commands, separated by the character " ", followed by an optional comment preceded by the character "_!". The characters " " and "_!" may never be used for any other purpose.

For example:  FIND   DELETE _! deletes the nearest feature

COMMANDS

LITES2 commands consist of an optional label (beginning with "." and ending with ":"), optionally followed by a primary command. In some cases, this may form the entire command (eg FIND). Some primary commands must be followed by one of several secondary commands (eg SEARCH ALL). In some cases a default secondary command is assumed if this is omitted (eg SEARCH is equivalent to SEARCH NEXT). Both primary and secondary commands may be shortened to the minimum non-ambiguous abbreviation.

Commands may be followed by compulsory or optional arguments

eg TOLERANCE FIND 3.0   (argument is compulsory)
   POSITION 400.0 450.0 (arguments are optional)
   POSITION             (position to centre of screen is assumed)
The precise effect of omitting an optional argument is described with each individual command.

ARGUMENTS

Command arguments are in general integer numbers, real numbers, or text strings. An integer number may not have a decimal point. Where a real number is required, the decimal point may be omitted when an integral value is desired, and scientific or exponent notation (eg 1.3E-3 = 0.0013) is permitted. Real numbers may also be entered in a 'rational' format (eg 2/3 for two thirds, or 0.6666667).

In the case of text arguments, exactly what is required is described with the individual commands, but it should be noted that in the case of commands taking an arbitrary text string (eg for insertion in the map data, or as a message), any leading spaces or tab characters are ignored. The text may be enclosed in double quotation marks, within which a repeated quotation mark may be used to include a quotation mark in the text. Quotation marks must be used if leading spaces or tabs are to form part of the text.

A few commands that deal with ancillary codes (ACs) or point attributes take a special form of argument, consisting of a code, (usually referred to as a "type" when referring to ACs), possibly followed by a value.

The code is either an integer which identifies the attribute, or a name that corresponds to this integer. Laser-Scan has defined some codes and names that are available to all users, but it is possible for the user to define his own in addition. This is done in the ACD (attribute code definition) part of the FRT.
Details of the Laser-Scan standard codes and of how to define further codes can be found in the "FRT User Guide".

The format of the value part of the argument depends on the data type associated with the attribute code. Each of the Laser-Scan standard attribute codes has a data type associated with it; user defined attribute codes have data types associated with them when they are defined in the FRT.

The possible data types are:-

COMMAND FILES

LITES2 commands may be stored in a disk file. Each line of the file is a single command line as described above. The command file is invoked by the command @filename, optionally followed by parameters. The commands in the file are then obeyed until the end of file is reached, when control returns to the command following the @filename directive. Command files may invoke other command files up to a certain level of nesting.

The most common use of command files is for LITES2 initialisation, but their use is not restricted to this. A possibly lengthy and rarely used sequence of editing commands may be better stored as a command file than as a macro (see below). A macro could still be set up to invoke the file rather than having the user type @filename.

MACROS

Macros provide a mechanism for the user to extend the LITES2 command language by adding new 'commands' which perform sequences of existing commands. The definition of a macro is begun using the MACRO command, after which all commands are stored as part of the macro (rather than being obeyed immediately) until the ENDMACRO command is encountered. Any calls to other macros, or @filename directives are merely checked for syntax during macro definition. Once defined, a macro is invoked merely by giving its name, optionally followed by parameters. It may also be used in JUMP commands (see below).

It is possible to define a macro with the same name as one of the LITES2 primitive commands (or whose abbreviation is the same as that of a primitive command). In these circumstances, the macro will take precedence. If the primitive command is intended, the command name should be preceded by the character "_%" which prevents the command being looked up as a macro.

It is good practice to use the "_%" escape character with primitive commands in macros and command files, so that these will continue to work even if macros with ambiguous names are defined later. (Command decoding will also be slightly faster.)

PARAMETERS

Parameters may be passed to command files and macros using the commands @file, JUMP, JTRUE, JFALSE, and the normal macro call invoked by giving the name of the macro. All these commands may be followed by a line of parameters, each delimited by one or more spaces or tabs, or enclosed in double quotes. Within the command file or macro, the values of the parameters are available in the character system variables $P1, $P2 etc. The number of parameters is available in $PCOUNT, and the whole line of parameters in $PLINE.

The parameters are only available within the command file or macro actually called. If this calls another command file or macro, then a new set of parameters will be available within the inner procedure. When the flow of control returns to the outer procedure, then the first set of parameters will be available again.

For example:
* add_text Red House
calls a macro passing two parameters. $P1 = "Red", $P2 = "House", $PCOUNT = 2, and $PLINE = "Red House" (the parameters do not actually contain the quotes).

* add_text "Red House"
This time there is only one parameter, $P1 = "Red House". $PLINE does contain the quotes.

PUCKS AND MENUS

Programmable menus and pucks are implemented using macros. Once defined, using a PUCK or MENU command, the macros menuname1 up to menunameN (where menuname is the name of the menu or puck, and N is the number of boxes or buttons) are available to be defined using MACRO commands.

Spaces between the menu name and the box number are optional. The macros for unused boxes or buttons should be left undefined - they will then do nothing. Menu or puck macro commands are normally generated automatically by the interactive interface when the boxes are probed or the buttons pressed, but there is nothing to prevent them being used at the keyboard, or in command files or other macros.

KEYBOARD FUNCTION KEYS

The function keys on DEC VDU terminals may be used as a programmable puck in LITES2. Use the PUCK command to define a puck on device 0, and then program the puck macros to execute the desired LITES2 commands. Buttons 1-49 are used, though not all of these have a corresponding keyboard key. This facility depends on a key transmitting the appropriate escape sequence to the computer and cannot utilise any key definitions using the DCL DEFINE/KEY command. Some terminals may allow keys to be programmed to send a string of characters to the computer just as if they had been typed - such a facility may be used instead of the mechanism described here.

F1 through to F5 cannot be used to give LITES2 commands. Which of the other keys are available depends on the terminal settings using the DCL commands SET TERM/[NO]LINE_EDITING, and SET TERM /APPLICATION_KEYPAD or /NUMERIC_KEYPAD. If the terminal is set to perform line editing, then F6 through F14 and the arrow keys will perform their line editing function and cannot be used to give LITES2 commands. If line editing is disabled, then these keys may be programmed. The keypad numeric keys, and also '.' '-' ',' and Enter may only be programmed if APPLICATION_KEYPAD is set, otherwise they just transmit their own character. The remaining keys (there are 16 of them) may always be programmed. The DCL SET TERM commands may be SPAWNed from LITES2, and some settings (particularly APPLICATION or NUMERIC KEYPAD) may sometimes be set locally on the terminal.

The layout of a VT220 type keyboard is shown below, with the puck button number shown below each key

F1 F2 F3 F4 F5  F6 F7 F8 F9 F10  F11 F12 F13 F14  Help Do  F17 F18 F19 F20
 x  x  x  x  x   6  7  8  9  10   11  12  13  14   15  16   17  18  19  20
                                            Fin Ins Rem    PF1 PF2 PF3 PF4
                                             40  41  42     21  22  23  24
                                            Sel Prv Nxt     7   8   9   -
                                             43  44  45    37  38  39  25
                                                Up          4   5   6   ,
                                                46         34  35  36  26
                                          Left Down Right   1   2   3
                                           48   47   49    31  32  33
                                                            0       .  Ent
                                                           30      28   27

LABELS

Any command may be preceded by a label. This begins with ".", consists of letters, numbers, and underline characters, and is terminated by ":". The case of the letters in a label is not significant. The label may be used as a target for JUMP, JTRUE, and JFALSE commands (qv), and must be in the same command line, or macro as the command which refers to it. These is no need for labels in different macros to be different, but if duplicate labels occur in the same macro, then the first one will always be found.

FLOW OF CONTROL

The command file directive (@filename) and the macro call (macroname), which have already been introduced, pass execution to the appropriate command file or macro. Calls may be nested up to a certain limit.

Unless affected by the mechanisms described below, commands are obeyed in order one by one until the end of a command line is reached. A new line is then obtained from the current source (command file or interactively). A macro is treated internally as a single line with multiple commands separated by " ". When the current source is exhausted, execution continues at the command following that which invoked the command file or macro.

One way in which the flow of control can be altered is if a command causes a MOAN or NASTY type error. Unless ENABLE CONTINUE has been used, this causes all currently active command files and macros to be abandoned, and control is returned to interactive. This mechanism (with DISABLE CONTINUE in force) can be used to terminate a repetitive sequence (eg when SEARCH NEXT gives an error because there are no more features), but this method is not recommended since it will fail if there is no interactive input available (as for instance in a batch job).

The next method of altering the flow of control is the JUMP command. This transfers control to a named macro or label. In the case of a JUMP to a macro, any commands following the JUMP at the current level (macro or command file) are abandoned and execution begins at the start of the named macro. This means that is is only sensible for JUMP to occur as the last command in a command file or macro, unless the following command has a label which is the target of a JUMP elsewhere. A label must occur in the same macro or line as the JUMP command which refers to it.

JUMP does not use up a level of macro/command file nesting, and the target of the JUMP can be the current macro. This means that simple repetitive loops can be constructed using macros which repeat until a error occurs. NB DISABLE CONTINUE must be in force, otherwise CTRL/C must be used to break out of the loop.

More versatile than JUMP are JTRUE, JFALSE, THEN, ELSE, and ABORT. The behaviour of these depends on whether the condition flag (see below) is TRUE or FALSE.

JTRUE and JFALSE are the same as JUMP, except that the jump is only made if the conditional flag is TRUE or FALSE respectively. Unlike JUMP, these therefore can usefully be followed by other commands in a command file or macro.

THEN and ELSE are followed by a command (possibly itself a macro or @filename) which is obeyed only if the condition flag is TRUE or FALSE respectively. These do use up a level of command nesting, and also differ from JUMP in that, whether or not the command is obeyed, execution continues at the next command.

The ABORT commands may be used just to terminate execution of procedures. ABORT INPUT terminates all active command files and macros and returns to interactive input, while ABORT ALWAYS (the ALWAYS secondary command is optional) just skips the rest of the current line or macro. ABORT TRUE and ABORT FALSE are the same as ABORT ALWAYS, but depend on the setting of the condition flag. ABORT FILE skips the rest of the current command file, even if called from within a macro invoked by the command file.

The condition flag used by JTRUE, JFALSE, THEN, ELSE, and ABORT is set using the commands TEST, OR, and AND. These compare the value of a LITES2 variable (see below), with an expression (see below).

The RESPOND command will pause execution of a macro or command file and prompt for the user to enter commands interactively. When finished, the CONTINUE command will return control the the command file or macro, alternatively CANCEL RESPOND or CTRL/C may be used to abandon all command files and macros and return to ordinary interactive input.

LITES2 VARIABLES

LITES2 variables are named entities which may be used to hold a character or numerical value. Variables may be one of four types:
CHARACTER: Contains a string of characters
INTEGER:   Contains an integer value in the range -2147483648 to 2147483647
REAL:      Contains a real value value in the range +/- 0.29E-38 to
           1.7E38 with a precision of 7 to 8 decimal digits. Real
           variables are displayed with 8 significant figures (with
           trailing zeros suppressed) but the eighth figure may not be
           completely accurate.
DOUBLE:    Contains a real value value in the range +/- 0.29E-38 to
           1.7E38 with a precision of 15 decimal digits.
Variables may be used in several different ways:

Some variables always exist within LITES2. These have names which begin with the character "_$", and are known as system variables. They contain values such as the current cursor position, or the current point on the found feature, and may not be set by the user. Some system variables have a compulsory argument (or subscript), e.g. $CUTREGION 2, and a few have an optional argument, e.g. $CURSINWIN 0.8. A complete list of available system variables is given below.

User variables must be declared using the DECLARE command before use. They can then be given values using the LET and INQUIRE commands. It is possible to declare array variables by following the name by the number of elements required.

By default the maximum number of user variables that may be declared is 1000. This maximum may be altered by setting the logical name LSL$LITES2_VARIABLEMAX to the required value before LITES2 is started.

The current value of variables can be displayed using the SHOW VARIABLES command, and can be tested using the TEST, AND, and OR commands.

The value of a variable may be substituted into a command by enclosing its name in single quotation marks (provided that ENABLE SUBSTITUTION is set). The trailing quotation mark may usually be omitted, as the variable name is taken to end at the first character which is not alphabetic or an underline. The trailing quote therefore must be present if two variables are to be substituted without any intervening spaces. If present, the trailing quote must immediately follow the variable name. There is no restriction on which parts of a command may use a variable. The substituted value may be a single argument, or (usually for a character variable) several arguments or even the whole command.

Eg. The command: SEARCH FSN 'NUMBER' will search for serial number 3 if NUMBER is an INTEGER variable with value 3. The effect would be identical if NUMBER were a CHARACTER variable containing the string "3", but note that only INTEGER, REAL, and DOUBLE variables can be used for arithmetic and to perform numerical comparisons.

In the case of array variables, another integer variable may be used as the subscript, thus if FSNS was an integer array containing a list of feature serial numbers, and I was an integer variable containing the required subscript, then the command: SEARCH FSN 'FSNS'I'' could be used. Both the trailing quotes are optional. A particular subscript may of course be used explicitly, as in SEARCH FSN 'FSNS4'.

The values of variables are never substituted while a macro is being defined. The presence of ' in any line in a macro will prevent the line being checked for syntax as the macro is defined, since the value of the variable is unknown at this stage.

EXPRESSIONS

Expressions are used in the commands LET, TEST, AND, OR, and INQUIRE to set and test the values of variables.

For CHARACTER variables, an expression consists simply of a string of characters. The string may be completely absent (the empty, or null string), and may optionally be enclosed in double quotation marks. Within double quotes, the character " is represented by "". The trailing quotation mark may always be omitted. The case of letters in character variables matters, so that, for instance a variable containing "A" will not be considered equal to the expression "a".

For INTEGER, REAL, or DOUBLE variables, an expression consists of one or more numbers together with the operators + - * / and _^ (exponentiate), and functions (SIN, COS, TAN, ASIN, ACOS, ATAN, ABS, LN, LOG - see below). Unary minus and functions have highest precedence, followed by _^, then * and /, then + and -. Operators of equal precedence are evaluated from left to right. Parentheses ( and ) may be used to force the order of evaluation. Note that the exponentiation operator may be used to obtain square roots, e.g. 4_^0.5 is 2.

When setting an INTEGER variable using LET or INQUIRE, an attempt is made to evaluate the expression using integer arithmetic. If this fails (due to the presence of a decimal point, an E exponent, or a real valued function), then real arithmetic is used, with the final result being truncated to integer.

When setting a REAL or DOUBLE variable, the expression is always evaluated using real arithmetic.

If an INTEGER variable is compared with a real expression in a TEST, AND, or OR command, then the integer is converted to real before the comparison.

For example (assuming I is an INTEGER variable, and R is a REAL):

   LET I=(3+8)/3 + 2/3   sets I to 3 using entirely integer arithmetic
   LET I=(3+8)/3.+ 2/3   sets I to 4 since decimal point forces real arithmetic
   LET R=(3+8)/3 + 2/3   sets R to 4.333333 (real arithmetic always used)

LOGICAL VARIABLES

Variables may be tested as logicals in a TEST, AND, or OR command. If the variable name is specified with no inequality or expression, then the logical result of the test is as follows:
INTEGER variable   True if low bit is set (value is odd)
REAL variable      True if not equal to 0.0
DOUBLE variable    True if not equal to 0.0
CHARACTER variable True if low bit of first character is set
In particular, this means that for INTEGER variables, 0 is false and -1 is true. These values are used for system variables which take a logical value. For CHARACTER variables, strings beginning with "Y" or "y" are true, while strings beginning with "N" or "n" are false. The null string is false.

SYSTEM VARIABLES

System variables have names beginning with the character $. The available system variables can be displayed using the command "SHOW VARIABLES $". An error results if an attempt is made to use a system variable which is undefined e.g. $FSN when there is no found feature. A list of available system variables follows:

FUNCTIONS

Within expressions the following functions may be used. Their argument may optionally be enclosed in parentheses.

SIN COS TAN ASIN ACOS ATAN ABS LN LOG

Trigonometric functions deal with angles in degrees, and return a real value.

ABS returns a real or an integer value, depending on the context.

LN and LOG return the natural (base e) and common (base 10) logarithm respectively as a real value.

For example, the command LET R=SIN30 will set variable R to 0.5, while the command LET R=COS('ANGLE'+30) will set R to the cosine of ANGLE+30, assuming that ANGLE is a REAL variable, and that SUBSTITUTION is enabled.