USER ROUTINES

LITES2 provides the opportunity for users to write their own programs to implement any operations that they require, that are not provided by the LITES2 commands, and that cannot be provided by the use of the MACRO command facility.

This facility is achieved by the LITES2 USER command, which allows access to one such program, and the ROUTINE command which allows access to another 10.

The programs must be linked as shareable images (see below for details) and they are accessed by logical names as follows:

Before attempting to provide their own shared image, users should have an understanding of the concept of features, as used by LITES2; in particular the various entries that are associated with different graphical types of features. For further information see Laser-Scan's documentation on IFFLIB and FRTLIB.

CALLING THE USER ROUTINES FROM LITES2

When the USER command is given to LITES2 the subroutines that the user has written and included in the shareable image, are called by LITES2. LITES2 is designed to call up to 10 routines, but note that The user routine can control the order in which the subroutines are called by setting a return code in each routine to say what routine is to be called next.

For example, when the USER command is given to LITES2, the arguments (an integer and an optional string) are passed to the initialisation routine (USRINI) along with other pieces of information (see details of the subroutines below). On completion of the routine, LITES2 examines the return code that has been set within the routine, and

The flow of control can be determined on the completion of all the routines in a similar manner. The following diagram shows the various possibilities

ACCESSING PARTICULAR SHARED IMAGES.

The shared images are only mapped when the first USER or ROUTINE n command is given. If the appropriate logical name is not set up then a warning message will be given at this stage.

THE SUBROUTINES - GENERAL.

The subroutines are listed, by functional group, in the order that they are called by the USER routine, and appear in the diagram above.

INITIALISE

This is the first subroutine to be called, whenever the USER command is given. There is only one routine that can be supplied in this group - USRINI

It is used to pass initial data to the shared image. This initial data consists of:-

Having received this information, the subroutine must set the return code, to tell LITES2 which subroutine to call next. The possibilities are:- Any other value will cause a fatal error (see routine USRERR below for details on error handling).
Entering 1,2 or 3 when there is no found feature will also cause a fatal error. Attempting to get ACs from a feature that has none will cause the routine not to be called, and the next routine called will depend on the value of the return code supplied.
If the routine USRINI is not supplied in the shareable image, or if the return code is greater than 100, and the routine to get map header information is not supplied, USRDO will be the next routine that is called.

GETTING AND WRITING FILE HEADER INFORMATION

This routine is used to read and write information that is particular to the specified map. There is only one routine that can be supplied in this group - USRGMH

This subroutine is used to read any map header (MH) and map descriptor (MD) entries associated with the specified map. The map is specified by giving a return code > 100 - the map is the difference between the return code and 100.
It supplies the map header and the map descriptor (as arrays of 16 bit integers - INTEGER*2 in Fortran) and allows them to be altered and optionally written back to their files.

The possible return codes are:-

GETTING ACS

This subroutine is used to read any AC entries associated with the found feature. There is only one routine that can be supplied in this group - USRGAC

This subroutine is used to read any AC entries associated with the found feature.
It reads one AC at a time and returns its type, value and any text associated with it.

The possible return codes are:-

GETTING COORDINATES

This group of subroutines are used to get the coordinates associated with the found feature. As the number of coordinates varies between feature and feature these subroutines pass the coordinates a block at a time. This means that arbitrarily long features can be processed by the USER command - although the user's shared image must of course have a method of dealing with them.

LITES2 decides how many points to pass to the routine; it will generally be 200, or the number of points remaining in the feature if that is less, but for composite texts the points will be passed one at a time.

The coordinates associated with each point in a feature can be simple or complex, according to the way in which LITES2 is being used. To avoid the user having to deal with unnecessary complexities, when he does not require the complex information, there are at several routines that may be called at this point. They are :

If two (or more) of these routines are included in the shared image, then the one higher up the list will be used.

In addition to passing the coordinates, the subroutines also pass a byte array of flags associated with each point. At present, only the bottom bit is significant, and it indicates whether the vector up to this point is to be visible (1) or invisible (0). In general, the flag for the first point has no significance. The possible return codes are:-

If the feature is a text feature, after the relevant routine has been called to get the coordinates, the routine USRGTX is called if it is present in the image. This returns data about the (sub)text associated with the coordinate information that has just been received. It does not require a return code to be supplied. The flow of control depends on the return code supplied in the coordinate passing routine.

PROCESSING

There is only one routine that can be supplied in this group - USRDO

By the time this routine is called, all the information has been passed from LITES2 to the user routines. This routine is used to process this data. Its return code controls the transfer of data back to LITES2.

The possible return codes are:-

START A NEW FEATURE

There is only one routine that can be supplied in this group - USRSTO

If a new feature is to be constructed (code 5 or 6 returned by the processing routine), then the routine to start a new feature is called. This allows the shared image to define the type of feature that is to be constructed. Entering -1 as the value of the FSN, FC, MAP, LAYER or THICK allows default values of these to be used in the construction of the new feature (set TEXTF true if default text feature code is to be used), otherwise values can be explicitly set in these variables.

See IFFLIB documentation for the meaning of the 4 elements of the FC (or feature status entry)

The number of coordinated points and the number of ACs in the feature must be given at this stage.

The possible return codes are:-

OUTPUTTING AN AC

This subroutine is used to output any AC entries to be associated with the ne construction. There is only one routine that can be supplied in this group - USRPAC

This routine is called after the routine that started a new feature, if the return code was set to 1 and there were some ACs to add to the feature. As long as its return code is set to 1, it is called NACS (as returned by the start feature routine) times.

The possible return codes are:-

OUTPUTTING COORDINATES

This group of subroutines are used to output the coordinates of the new feature.

The coordinates are passed to LITES2 in blocks, in repeated calls of one of the output routines, in a similar manner to the way in which coordinates are passed out of LITES2 by the routines that get coordinates. The size of each block of coordinates is determined by the shared image - but it must not be larger than the value that is passed to the user image in the argument SIZE.

When constructing non-text features, for efficiency, the largest possible blocks of data should be supplied to this routine. For texts however, only one point should be supplied at a time, so that a call of USRPTX can be associated with each coordinate

In a manner similar to the routines that get coordinates, depending on the amount of data required, there are several routines that may be called at this point. They are :

If two (or more) of these routines are included in the shared image, then the one higher up the list will be used.

In addition to passing the coordinates, the subroutines also pass a byte array of flags associated with each point. At present, only the bottom bit is significant, and it indicates whether the vector up to this point is to be visible (1) or invisible (0). In general, the flag for the first point has no significance.

The possible return codes are:-

If the feature is a text feature, after the relevant routine has been called to get the coordinates, the routine USRPTX is called if it is present in the image. This provides data about the (sub)text associated with the coordinate information that has just been sent. It does not require a return code to be supplied. The flow of control depends on the return code supplied in the coordinate passing routine.

COMPLETING THE USER COMMAND

There are four routines that can be supplied in this group - USRRET and the ancillary routines, USRDEF, USRANO and USRDRW.

USRRET is the last user routine to be called by the USER command. It allows the condition flag (used for determining the flow of control in macros) to be set and also allows a LITES2 command string to be entered. This command string will be obeyed immediately after the current USER command is completed.

By supplying a suitable return code, LITES2 can be instructed to call an ancillary completion routine : USRDEF, USRANO or USRDRW. After this ancillary routine has completed, USRRET is called again.

The possible return codes to USRRET are:-

USRRET must exist if an ancillary routine is to be called.

There is no return code supplied to these ancillary routines; after they have completed successfully USRRET is called again. If an error occurs while carrying out the action required by the routine (for example if a variable to be set does not exist, or a drawing command is given in an inappropriate state) the user routine aborts.

ERROR HANDLING

There is only one routine that can be supplied in this group - USRERR.


If the FATAL argument is TRUE, then the USER command will be aborted, as soon as control returns from this routine - abandoning any feature that is being constructed.
If the FATAL argument is FALSE, then the USER command will continue after outputting a warning message.

See the details of the routine for the meaning of the error numbers.

THE SUBROUTINES - SPECIFICATIONS.

There are template files supplied in LSL$PUBLIC_ROOT:[LITES2.ROUTINES.TEMPLATE] for all the following routines

INITIALISE

USRINI
	SUBROUTINE USRINI(ACTION,STRL,STR,CURSOR,CNDFLG,STATE,
     &	                  GOTFO,NCOORD,NACS,FSN,FC,MAP,LAYER,GT,
     &	                  ROTAT,THICK,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
C Arguments
C
	INTEGER*4	ACTION		! action to carry out
	INTEGER*4	STRL		! number of characters in STR
	CHARACTER*(*)	STR		! string passed to USER command
	REAL		CURSOR(2)	! coordinates of cursor
	LOGICAL		CNDFLG		! condition flag.
	CHARACTER*(*)	STATE		! current state
	LOGICAL		GOTFO		! TRUE if there is a found
					! object, FALSE otherwise, when
					! the next 4 arguments are 
					! undefined
	INTEGER*4	NCOORD		! number of coords
	INTEGER*4	NACS		! number of ACS
	INTEGER*4	FSN		! number of feature
	INTEGER*4	FC(4)		! feature status 
	INTEGER*4	MAP		! map
	INTEGER*4	LAYER		! layer
	INTEGER*4	GT		! graphical type
	REAL		ROTAT		! rotation if text or oriented
					! symbol (in radians)
	INTEGER*4	THICK		! size of text
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call 
					!     processing routine
					! = 1 for get coords and ACs
					! = 2 for get coords without ACs
					! = 3 for get ACs without coords
					! = 4 for call processing without
					!     coords or ACs
					! = 5 for call completion 
					!     routine
					! > 100 - call the routine to get
					!  map header information (for map
					!  RETCOD - 100)
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only

GETTING FILE HEADER INFORMATION

USRGMH
	SUBROUTINE USRGMH(MH_LEN,MH,WRITE_MH,MD_LEN,MD,WRITE_MD,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
C Arguments
C
	INTEGER*4	MH_LEN		! input  - length of original MH
					! output - length of updated MH
	INTEGER*2	MH(MH_LEN)	! map header - NOTE INTEGER*2
	LOGICAL*4	WRITE_MH	! input  - TRUE if MH is writable
					! output - TRUE if MH is to be written
	INTEGER*4	MD_LEN		! input  - length of original MD
					! output - length of updated MD
	INTEGER*2	MD(MD_LEN)	! map descriptor - NOTE INTEGER*2
	LOGICAL*4	WRITE_MD	! input  - TRUE if MD is writable
					! output - TRUE if MD is to be written
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call processing
					!     routine
					! = 1 for get coords and ACs
					! = 2 for get coords without ACs
					! = 3 for get ACs without coords
					! = 4 for call processing routine
					!     without
					!     coords or ACs
					! = 5 for call completion routine
					!     without coords or ACs
					! > 100 - call this routine again
C
C	All these arguments may be considered writable but note that
C	the new lengths of the arrays MUST not be longer than the
C	original arrays
C
C	Trying to write a map header or a map descriptor to a file that
C	has been opened for READing only will cause an error.
C
C	Writing a new map header or map descriptor will not affect the
C	idea that LITES2 has of the origin and scale, and the system,
C	variables $MHARR, $MHLEN, $MDARR and $MDLEN although the output
C	file will contain the changes.
C
C	Changes to the projection parts of the map descriptor (ie apart
C	from the origin and scale) require an intimate knowledge of
C	Laser-Scan's projection software. It is recommended that such
C	changes are made using the program ITRANS.
C

GETTING ACS

USRGAC
	SUBROUTINE USRGAC(ACTYPE,ACIVAL,ACTXTL,ACTXT,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
C Arguments
C
	INTEGER*4	ACTYPE		! type of AC
	INTEGER*4	ACIVAL		! AC value
					! note: to read a real AC value,
					! a copy of this will have to
					! be equivalenced to a real
	INTEGER*4	ACTXTL		! number of characters in ACTXT
	CHARACTER*(*)	ACTXT		! text (maximum of 80 chars)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call USRDO
					! = 1 for get more ACs if there
					!     are any, or start getting
					!     coords if reqd, or call
					!     USRDO if coords not reqd
					! = 2 stop getting ACs, start
					!     getting coordinates
					! = 4 for call USRDO right away
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only

GETTING COORDINATES

USRGCB
	SUBROUTINE USRGCB(SIZE,USERXY,USRFLG,
     &	                 MAX_ATTR,USERNATT,USERATTC,
     &	                 USERDATATYPES,USERNAMELENS,USERNAMES,USERIATTV,
     &	                 USERRATTV,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! number of coords passed
					! with this call
	REAL		USERXY(2,SIZE)	! coordinates
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER		MAX_ATTR	! maximum number of attributes
	INTEGER		USERNATT	! number of attributes present
	INTEGER		USERATTC(MAX_ATTR)	! attribute codes
	INTEGER		USERDATATYPES(MAX_ATTR)	! datatypes of attributes
	INTEGER		USERNAMELENS(MAX_ATTR)	! name lengths
	CHARACTER*(*)	USERNAMES(MAX_ATTR)	! names of attributes
C
C the following two arrays are equivalenced in the calling routine
	INTEGER		USERIATTV(MAX_ATTR,*)	! integer values
	REAL		USERRATTV(MAX_ATTR,*)	! real values
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call 
					!     processing routine
					! = 1 for get more coords
					!     or call processing routine,
					!     if no more
					! = 4 for abort, but call
					!     processing routine
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only
C
C	the following parameter is for testing if an attribute value
C	is present for a particular point
C
C	NOTE: this must be tested against an integer, which has
C	been equivalenced onto the real value to be tested
C
	INTEGER*4	IABSENT
	PARAMETER	(IABSENT = '80000000'X)

USRGZS
	SUBROUTINE USRGZS(SIZE,USERXYZ,USRFLG,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! number of coords passed
					! with this call
	REAL		USERXYZ(3,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call
					!     processing routine
					! = 1 for get more coords
					!     or call processing routine,
					!     if no more
					! = 4 for abort, but call
					!     processing routine
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only
C
C	the following parameter is for testing if a Z coordinate value
C	is present for a particular point
C
C	NOTE: this must be tested against an integer, which has
C	been equivalenced onto the real value to be tested
C
	INTEGER*4	IABSENT
	PARAMETER	(IABSENT = '80000000'X)

USRGST
	SUBROUTINE USRGST(SIZE,USERXY,USRFLG,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
					! with this call
	REAL		USERXY(2,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call
					!     processing routine
					! = 1 for get more coords
					!     or call processing routine,
					!     if no more
					! = 4 for abort, but call
					!     processing routine
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only

USRGPT
	SUBROUTINE USRGPT(SIZE,USERXY,USRFLG,TEXTL,TEXT,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! number of coords passed
					! with this call
	REAL		USERXY(2,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	TEXTL		! number of characters in TEXT
	CHARACTER*(*)	TEXT		! text string, if text feature
	INTEGER*4	RETCOD		! return code
					! = 0 abort, don't call
					!     processing routine
					! = 1 for get more coords
					!     or call processing routine,
					!     if no more
					! = 4 for abort, but call
					!     processing routine
C
C	All these arguments, apart from RETCOD, should be considered
C	as read only
C

USRGTX
	SUBROUTINE USRGTX(TEXT,TEXTL,TS,HEIGHT,ROTAT,AUX)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	TEXTL		! number of characters in TEXT
	CHARACTER*(*)	TEXT		! text string, if text feature
	INTEGER*4	TS(4)		! text component status
	REAL		ROTAT		! rotation of text component
	INTEGER*4	HEIGHT		! height of text (in points or
					! 0.01mm)
	REAL*4		AUX(8)		! data about text (in IFF units)
					! AUX(1) = angle (in radians)
					! AUX(2) = cosine of angle
					! AUX(3) = sine of angle
					! AUX(4) = height (in IFF units)
					! AUX(5) = minimum X value 
					!         (rel to locating point)
					! AUX(6) = maximum X value
					! AUX(7) = minimum Y value 
					! AUX(8) = maximum Y value
C

PROCESSING

USRDO
	SUBROUTINE USRDO(RETCOD)
C
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call completion
					!     routine
					! = 4 for abort, call completion
					!     routine
					! = 5 to create a new feature
					!     (and keep old one if there
					!      was one)
					! = 6 to create a new feature
					!     and delete old one
C

STARTING A NEW FEATURE

USRSTO
	SUBROUTINE USRSTO(FSN,FC,MAP,LAYER,TXTF,NOPTS,NAC,
     &	                  ROTAT,THICK,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	FSN		! feature serial number to use
					! (set to -1 for unknown)
	INTEGER*4	FC(4)		! feature status to use
					! (set FC(I) to -1 for unknown)
	INTEGER*4	MAP		! map to put feature in
					! (set to -1 for unknown)
	INTEGER*4	LAYER		! layer to use
					! (set to -1 for unknown)
	LOGICAL		TXTF		! .TRUE. if FC =-1 and want
					! to create a text feature
	INTEGER*4	NOPTS		! number of points in feature
	INTEGER*4	NAC		! number of ACs in feature
	REAL		ROTAT		! rotation if text or oriented
					! symbol (in radians)
	INTEGER*4	THICK		! size of text
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call completion
					!     routine
					! = 1 for ask for data
					! = 4 abort, call completion
					!     routine
C
C all the arguments in this subroutine are writable
C

OUTPUTTING AN AC

USRPAC
	SUBROUTINE USRPAC(ACTYPE,ACIVAL,ACTXTL,ACTXT,RETCOD)
C
C       Copyright Laser-Scan Laboratories Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C	Dummy routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	ACTYPE		! type of AC
	INTEGER*4	ACIVAL		! AC value
					! note: to read a real AC value,
					! a copy of this will have to
					! be equivalenced to a real
	INTEGER*4	ACTXTL		! number of characters in ACTXT
	CHARACTER*(*)	ACTXT		! text (maximum of 255 chars)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, no call completion
					!     routine
					! = 1 for write another AC if
					!     there are any, or else
					!     start writing coords
					! = 2 for start writing coords
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable
C

OUTPUTTING COORDINATES

USRPCB
	SUBROUTINE USRPCB(SIZE,USERXY,USERFLG,
     &	              MAX_ATTR,USERNATT,USERATTC,
     &	              USERIATTV,USERRATTV,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! input:  maximum number of
					!         coords to pass back
					! output: actual number of
					!         coords passed back
					! with this call
	REAL		USERXY(2,SIZE)	! coords
	LOGICAL*1	USERFLG(SIZE)	! flags (visibility only)
	INTEGER		MAX_ATTR	! maximum number of attributes
	INTEGER		USERNATT	! number of attributes present
	INTEGER		USERATTC(MAX_ATTR)	! attribute codes
C
C the following two arrays are equivalenced in the calling routine
	INTEGER		USERIATTV(MAX_ATTR,*)	! integer values
	REAL		USERRATTV(MAX_ATTR,*)	! real values
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call completion
					!     routine
					! = 1 for write more coords, if
					!     there are any, or else
					!     call USRRET
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable.
C
C don't send more than maximum number of attributes -- most important
C ===================================================================
C

USRPZS
	SUBROUTINE USRPZS(SIZE,USERXYZ,USRFLG,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! input:  maximum number of
					!         coords to pass back
					! output: actual number of
					!         coords passed back
					! with this call
	REAL		USERXYZ(3,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call 
					!     completion routine
					! = 1 for write more coords, if
					!     there are any, or else
					!     call USRRET
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable.

USRPST
	SUBROUTINE USRPST(SIZE,USERXY,USRFLG,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! input:  maximum number of
					!         coords to pass back
					! output: actual number of
					!         coords passed back
					! with this call
	REAL		USERXY(2,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call 
					!     completion routine
					! = 1 for write more coords, if
					!     there are any, or else
					!     call USRRET
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable.

USRPZS
	SUBROUTINE USRPZS(SIZE,USERXYZ,USRFLG,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C	Dummy user routine
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! input:  maximum number of
					!         coords to pass back
					! output: actual number of
					!         coords passed back
					! with this call
	REAL		USERXYZ(3,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call 
					!     completion routine
					! = 1 for write more coords, if
					!     there are any, or else
					!     call USRRET
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable.

USRPPT
	SUBROUTINE USRPPT(SIZE,USERXY,USRFLG,TEXTL,TEXT,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C
        IMPLICIT NONE
C
C Arguments
C
	INTEGER*4	SIZE		! input:  maximum number of
					!         coords to pass back
					! output: actual number of
					!         coords passed back
					! with this call
	REAL		USERXY(2,SIZE)	! coords
	LOGICAL*1	USRFLG(SIZE)	! flags (visibility only)
	INTEGER*4	TEXTL		!  input: max size of TEXT
					! output: actual size of TEXT
	CHARACTER*(*)	TEXT		! text string, if text feature
	INTEGER*4	RETCOD		! return code
					! = 0 abort, dont call completion
					!     routine
					! = 1 for write more coords, if
					!     there are any, or else
					!     call completion routine
					! = 4 for abort, call completion
					!     routine
C
C	All these arguments are writable.
C

USRPTX
	SUBROUTINE USRPTX(TEXT,TEXTL,TS,THICK,ROT)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
C Arguments
C
	CHARACTER*(*)	TEXT		! text string, if text feature
	INTEGER*4	TEXTL		!  input: max size of TEXT
					! output: actual size of TEXT
	INTEGER*4	TS(4)		! feature status for texts
	INTEGER*4	THICK		! height of text
	REAL		ROT		! angle of text
C
C	All these arguments are writable.
C

COMPLETING THE USER COMMAND

USRRET
	SUBROUTINE USRRET(CNDFLG,RTSTRL,RTSTR,RETCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines.
C
        IMPLICIT NONE
C
C Arguments
C
	LOGICAL		CNDFLG		! LITES2 conditional flag
	INTEGER*4	RTSTRL		!  input: maximum size of RTSTR
					! output: size of RTSTR
	CHARACTER*(*)	RTSTR		! LITES2 command line, to be 
					! executed before any other
					! command
	INTEGER*4	RETCOD		! return code
					! = 0 for abort
					! = 1 for CNDFLG to be set
					!     and command to be executed
					! = 2 for call processing routine
					!     again
					! = 3 for call USRDEF before calling 
					!     this routine again
					! = 4 for call USRANO before calling 
					!     this routine again
					! = 5 for call USRDRW before calling 
					!     this routine again
C
C all these arguments are writable
C

USRDEF
	SUBROUTINE USRDEF(VARNAM_LEN,VARNAM,INDEX,INTVAL,REALVAL,
     &	                     DBLVAL,CHARVAL_LEN,CHARVAL)
C
C       Copyright Laser-Scan Laboratories Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
C Arguments
	INTEGER		VARNAM_LEN	! input: maximum size of VARNAM
					! output: size of VARNAM
	CHARACTER*(*)	VARNAM		! variable name to set
	INTEGER		INDEX		! element if VARNAM is array
	INTEGER		INTVAL		! integer value to set
	REAL		REALVAL		! real value to set
	REAL*8		DBLVAL		! double value to set
	INTEGER		CHARVAL_LEN	! input: maximum size of CHARVAL
					! output: size of CHARVAL
	CHARACTER*(*)	CHARVAL		! character value to set
C
C all these arguments are writable.	
C

USRANO
	SUBROUTINE USRANO(RTSTRL,RTSTR)
C
C       Copyright Laser-Scan Laboratories Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
	INTEGER*4	RTSTRL		! input: maximum size of RTSTR
					! output: size of RTSTR
					! if 0 is returned no ANNOTATION
					! command is executed.
	CHARACTER*(*)	RTSTR		! secondary command (with
					! arguments) for the ANNOTATION
					! command
C
C all these arguments are writable.	
C

USRDRW
	SUBROUTINE USRDRW(RTSTRL,RTSTR)
C
C       Copyright Laser-Scan Laboratories Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
	INTEGER*4	RTSTRL		! input: maximum size of RTSTR
					! output: size of RTSTR
					! if 0 is returned no DRAW command
	CHARACTER*(*)	RTSTR		! secondary command (with
					! arguments) for the DRAW command
C
C all these arguments are writable.	
C

ERROR HANDLING

USRERR
	SUBROUTINE USRERR(FATAL,ERRCOD)
C
C       Copyright Laser-Scan Ltd., Cambridge, England.
C
C Description
C
C	LITES2 cartographic editor user command routines .
C
        IMPLICIT NONE
C
C Arguments
C
	LOGICAL		FATAL		! .TRUE. if user routine is
					!        about to be aborted
					! .FALSE. if only a warning
	INTEGER*4	ERRCOD		! error code
C
C  Error numbers passed to USRERR
C  (errors marked with * are fatal)
C
C* trying to get ACs or coordinates when there is no found feature
	PARAMETER	USR_NOFEATURE	=  1
C
C trying to get ACs from feature with none
	PARAMETER	USR_NOACS	=  2
C
C* tried to create a feature, while in an invalid state to do so
	PARAMETER	USR_NONEWCONSTR	=  3
C
C* tried to create a feature in an non-existant map
	PARAMETER	USR_MAPNOTEXIST	=  4
C
C* tried to create a feature in a read only map
	PARAMETER	USR_MAPREADONLY	=  5
C
C* tried to create a feature in an non-existant layer
	PARAMETER	USR_LAYNOTEXIST	=  6
C
C* tried to create a feature with an non-existant feature code
	PARAMETER	USR_BADCODE	=  7
C
C* tried to create a generated feature with an impossible feature code
	PARAMETER	USR_INVALFC	=  8
C
C* tried to create a feature with the wrong number of points
	PARAMETER	USR_WRNGNOPTS	=  9
C
C trying to create text feature with a height of an illegal point size
C (defaulted to 24)
	PARAMETER	USR_UNKPTSIZ	= 10
C
C trying to create an AC that is too long. It has been truncated
	PARAMETER	USR_ACTOOLONG	= 11
C
C* trying to construct a feature with a coordinate outside the limits
C  of the map
	PARAMETER	USR_PTOUTRANGE	= 12
C
C* trying to create a feature with zero length text
	PARAMETER	USR_TEXTTOOSHORT= 13
C
C* other error while constructing feature.
C The feature has been abandoned.
	PARAMETER	USR_FTABANDONED	= 14
C
C* unrecognised return code returned by a USR* routine
	PARAMETER	USR_UNKRETCOD	= 15
C
C  trying to create text feature with an illegal height (in mms). Default
C  value used.
	PARAMETER	USR_UNKHTSIZ	= 16
C
C* error while setting a variable by a call of USRDEF
	PARAMETER	USR_VARIABLEERR	= 17
C
C* error while calling USRGMH
	PARAMETER	USR_MH_MD_ERR   = 18
C
C* error while calling USRANO
	PARAMETER	USR_ANNO_ERR    = 19
C
C* error while calling USRDRW
	PARAMETER	USR_DRAW_ERR    = 20

COMPILING AND LINKING A SHARED IMAGE.

For detailed information about shared images, reference should be made to the appropriate VAX VMS manuals.
This section is intended only as a guide, to allow users to compile and link their own simple images.

The required routines should be compiled normally, and then linked into a shareable image by using the /SHARE qualifier in the link command.

To allow LITES2 to locate the entry points of the routines that it calls it is necessary to include an options file that declares the required routines as UNIVERSAL. (Other routines used within the image should not be declared UNIVERSAL).

If the user routine image contains any common blocks, then they must be set to be non-shareable using the PSECT_ATTR linker command.

There is an example user image supplied with LITES2 in the directory LSL$PUBLIC_ROOT:[LITES2.ROUTINES.EXAMPLE]. This may be built with the command file EXAMPLE_ROUTINE.COM which calls USRLNK.COM.
These illustrate the use of a library, USRLIB, which contains the specified user routines and any other subroutines that they call. They also show how common blocks must be included as non-shareable PSECTs in the link file.

EXAMPLE_ROUTINE.COM

$	SET ON
$	ON ERROR THEN GOTO EXIT
$	SET VERIFY
$	LIBR/CREATE USRLIB
$	FORTRAN/NOOPT/DEBUG USRDO,USRERR,USRGAC,USRINI,USRPAC
$	FORTRAN/NOOPT/DEBUG USRRET,USRSTO,USRGCB,USRGTX
$	FORTRAN/NOOPT/DEBUG USRPCB,USRPTX,USRDEF
$	LIBR/REPL USRLIB USRDO,USRERR,USRGAC,USRINI,USRPAC,-
	                 USRRET,USRSTO,USRGCB,USRGTX,USRPCB,USRPTX,USRDEF
$!
$! and link it
$	@USRLNK
$EXIT:
$	PURGE USR*.*
$	SET NOVER

USRLNK.COM

$	LINK/DEBUG/SHARE=EXAMPLE_ROUTINE SYS$INPUT:/OPT
USRLIB/INCLUDE=(USRDO,USRGAC,USRINI,USRPAC,USRRET,-
USRSTO,USRGCB,USRGTX,USRPCB,USRPTX,USRERR,USRDEF)/LIB
UNIVERSAL = USRDO,USRGAC,USRINI,USRPAC,USRRET,USRSTO
UNIVERSAL = USRERR,USRPTX,USRGCB,USRGTX,USRPCB,USRDEF
PSECT_ATTR=USRKEEP,NOSHR
PSECT_ATTR=USRKEEPC,NOSHR
PSECT_ATTR=USRFEAT,NOSHR
PSECT_ATTR=USRFEATC,NOSHR
$!

To use this routine the logical name LSL$LITES2ROUTINES_1 should be set to point to the shared image. Then the command ROUTINE 1 1 can be given from LITES2, which gives instructions on how to use the rest of the shared image.

It should be noted that the above command files link a debugged version of this image. It is possible to use the debugger to examine the working of the image by giving the LITES2 command DEBUG. To set a break point on USRINI, for example, give the commands

DBG> SET IMAGE LSL$LITES2ROUTINES_1
DBG> SET BREAK USRINI
DBG> GO