Introduction


Most editing tasks, particularly those involving editing source statements, end up jumping around the file. Yes, a label can be assigned to 'where you are" - e.g. .HERE so that later you can do a LOCATE .HERE to go back to where you were and continue editing.  Or you could just remember the current line number to go back to.


This 'jump' to another location may simply be to review code in another location, or perhaps to copy a code fragment for re-use. But interrupting your thought patterns to remember a line number, or set a label is disruptive.


What if this setting of a return point was painless and automatic? Well, with SPFLite tracking support, it now is.  


Many of the built-in commands will now automatically create a 'Track Point' before the command is processed, and another 'Track Point' when the command completes. This includes commands such as FIND, LOCATE, CHANGE, RFIND etc. 


How to "Go Back"


Returning to your previous location is now trival. A single key. There are three new KB primitives - (TRACK) (TRACKF) and (TRACKC).


(TRACK)

This will return you to the position in Edit of the most recent 'Track Point'.  The screen will be positioned to the same Top-Of_Screen location, and the cursor placed where it was when the command was initiated.


Note: If you press (TRACK) and the cursor is still sitting exactly where the most recent 'Track Point' would take you (i.e. nowhere) then the next previous T'rack Point' will be used.


(TRACKF)

This companion operation is for those cases where you simply hit (TRACK) too many times. It goes Forward again in location.


(TRACKC)

This will create a new Track Point at the current screen location. Intended for use mainly in KB macros where the other commands may not cause a Track Point to be created.


What about Macros, or Other Commands


The built-in list of commands that automatically "track" can be extended to include whatever other commands and/or macros you wish. This is done using the SPFLite SET facility. To add a macro or command to this list simply:


Issue the command  SET TRACK.cmdname = Y


at the SPFLite command line.


What about SPF_CMDs issued by Macros


The tracking support will ignore tracking during macro execution.  e.g. if the macro issues FIND or LOCATE commands, those internally issued commands will NOT create track entries. A Track entry is created before and after the macro is run (assuming a TRACK.macroname = Y has been created) but no new Track entries will be created during macro execution.


How far back can I go?


Currently the backtrack limit is 200 positions.  This should be more than sufficient for any normal editing requirement.

 


Can Macros access the internal TRACK support?


Yes, three  macro functions are available.


Get_Trk_Pos$(index-number)


The index-number indicates which Track position is desired, where: (1) indicates the latest, (2) indicates the prior entry, (3) the next previous, etc.   If the index number is not specified, the default is (1).


The answer returned is a simple comma delimited String of the format  

TOS-Line,Csr_LPtr,CSR_Coll 


Where:        

TOS-Line        The Lptr of the Top-of-Screen line in character format.


Csr_LPtr        The Lptr of the line containing the cursor in character format. If this value is zero, it indicates the cursor was on the command line.


Csr_Col        The location of the cursor within the text line in character format. If zero it indicates the cursor was in the Line-number area.


The Return-code should be checked before using the return value, since errors are possible. Currently the two error conditions are:

  • The index-number references a Stack entry which has never been used.
  • The Stack entry has been used, but now references a Top-of-Screen line which no longer exists (i.e. it has been deleted)


Get_Trk_TrkID(line-pointer)


Every line in an Edit session has a permanently assigned Track ID. The ID is assigned once, and is never changed or removed. Obtaining this ID allows a macro to obtain a guaranteed pointer to a specific data line.


The operand is a normal line-pointer (NOT a Line Number)


The answer returned is the assigned Track ID (a simple numeric value)


The Return-code should be checked before using the return value, since an invalid line-pointer will simply return a zero.  This could occur if the line-pointer references a line which has been deleted.


Get_Trk_LPtr(track-ID)


This function is the reverse of Get_Trk_TrkID, it accepts a track-ID as an operand, and returns the Lptr of the line.


The operand is a track-ID obtained by a prior Get_Trk_TrkID call.


The answer returned is a the Lptr for the requested ID.


The Return-code should be checked before using the return value, since the track-ID could be for a line which has been deleted.



Created with the Personal Edition of HelpNDoc: Simplify Your Help Documentation Process with a Help Authoring Tool