A Line Handle provides a means for a macro to reference a data line in the current Edit session. This is in addition to Line Labels, Line Numbers and Line Pointers.


Line Tags can also be used to refer to data lines, but because Tags can refer to multiple lines, they are very different from Line Labels or Line Numbers. Tags are not considered further here.



What is a Line Handle?


A Line Handle is essentially a unique ID that is used to identify a data line. In theory, any data line can have a Line Handle. In practice, only lines that are "of interest" to a macro writer will have Line Handles. The presence of a Line Handle on a line is optional.



Why use Line Handles?


When a macro uses functions that refer to data lines, nearly all of those functions take Line Pointers as arguments. While Line Pointers work relatively well, they have certain shortcomings:


    • Line Pointers can become invalidated. This can happen if any lines are inserted or deleted before the line pointed-to by the line pointer. That includes not just data lines but NOTE and PROFILE lines, and lines which are excluded or unexcluded. So, a macro writer must be very careful to avoid any logic that would invalidate a Line Pointer. Invalidation is the main drawback to Line Pointers.
    • Line Pointers are not "persistent" like labels are. The only way for a macro to re-establish a Line Pointer is for it to find the associated data line again through some kind of search logic. So, any work previously done to find such lines has to be repeated each time.



What about Request/Release?


Macro users may be familiar with the former functions Request_Label$ and Release_Label$. Can't these be used as handles? Yes, up to a point, but their implementation had certain limitations:


    • Labels used with Request/Release are temporary, and are deleted as soon as the macro creating them terminates, even if the macro did not explicitly request for them to be released. So, there is no opportunity to save them as persistent STATE information.
    • Request/Release labels are stored where normal labels are. (Users don't notice that currently, because temporary labels disappear as soon as a macro ends.) So, if these were made "persistent", they would become visible on the Edit screen, where they would be a distraction to users with their unusual appearance.
    • Because of how they are stored, a data line can have either a normal label or a Request/Release label, but not both. So, these labels are used inconsistently.


The current Request_Label$ and Release_Label$ functions will be deprecated when Line Handles are implemented. It is recommended that you replace Request_Label$ with Get_Handle$, and replace Release_Label$ with Drop_Handle$ in your macro code. The new functions are not totally identical to the old ones, but are close enough to be used as substitutes in old macros. Eventually, these old function names will be removed. All new Handle-related functions will contain the word Handle in their function name.


For now,  Request_Label$ will be treated as an alias name for Get_Handle$, and Release_Label$ will be treated as an alias name for Drop_Handle$. Even though the old names will continue to exist for a while, they will be just alternate names for the new Handle-related function calls.



Internal properties of Line Handles


    • Only data line can have line handles. (Compare to Line Pointers, which can point to anything visible on the Edit screen, like Profile lines, NOTES, etc.)
    • When requested by a macro function, a data line is assigned a Line Handle value. This value is a unique ID, no other line will have the same ID. 
    • The Line Handle ID is a string value that can be used in building SPFLite commands in all the same ways as a Line Label. .
    • Line Handles are created in the order they are assigned, not in the numeric order of the underlying data lines.
    • A Line Handle is a separate attribute of a data line, just like labels, tags and User marks are.
    • Although Line Handles can be used like a normal Line Label, they exist independently, so a data line can have a Label, a Handle, or both.
    • A Line Handle is part of the file's STATE information. If STATE ON is in effect, Line Handle information is saved and is persistent between Edit sessions, like other STATE information is.
    • It is possible to remove a Line Handle from a line with the function Drop_Handle$. If that same data line is assigned a Line Handle again via the function Get_Handle$, the new Handle that is assigned is the "next available" Handle value. The old Handle is not restored, but is permanently discontinued for this Edit file.
    • You can remove all Handles from an entire file via Drop_Handle$("ALL").



External properties of Line Handles


Line Handles essentially behave as if they were a second Line Label on a data line. Since Line Labels are used in Primary Edit Commands, they have these external properties:


    • A Line Handle can be used anywhere a Line Label can be used. They may be thought of as a specialized kind of Label, similar to how "pseudo-label" line numbers like .123 are used.
    • The main use of Line Handles on primary commands will be those primary commands that are issued by a macro using a call to SPF_CMD().
    • The primary command RESET will be extended to support RESET HANDLE. RESET LABEL will not clear any Line Handles. That protects any existing handles from being accidentally cleared by a RESET LABEL command.
    • The primary command LOCATE will be extended to support LOCATE HANDLE. LOCATE LABEL will not locate lines with Line Handles. When LOCATE HANDLE is issued, an information message will be displayed in the usual message-location to identify the Handle that was found, since Handles are not otherwise visible on the screen nor on the status line.



Behaviour of Line Handles when multiple files are involved


If you edit two files that have saved STATE information, it is possible that Labels and/or Handles in one file are duplicated in another. If you edited such files together, those duplication's could be confusing. To avoid this problem, SPFLite takes the following actions:


    1. If you are editing a single file with Line Labels and/or Line Handles as STATE information, these are accepted as a normal part of the data file. If you COPY a second file with Line Labels and/or Line Handles, any Labels or Handles in the second file are discarded.
    2. In a Multi-Edit session, all existing Line Labels and Handles are discarded. You can run macros that utilize Handles, but these will have to be reestablished after the MEdit session is started. (In other words, an MEdit session begins as though a function call of Drop_Handle("ALL") had been issued.) 


Note: If the files included in an MEdit session have Labels and/or Handles, and the file is not saved from the Medit session, then the handles for the individual file will not be disturbed. 


If you wish to ensure that existing Labels and Handles are not lost during an MEdit session, you need to treat the session as though it were a Browse session, and when finished, be sure to issue a CANCEL command.

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?