SPFLite - V3.0.24069 2024-03-09

str-var = Get_Handle$(line-ref)

Operands:

line-ref

A reference to a data line to which a Line Handle is to be assigned. The LineRef can be a numeric Line Pointer, or it can be a string containing a normal label (".ABC"), a pseudo-label (".123") or the string form of a Line Pointer ("!123"). A Line Handle name ("._123") cannot be used, nor can a Tag name(":ABC") be used.

Returns:

If the LineRef is a valid reference to a data line, the string form of a Line Handle ("._123") is returned, and RC = 0. If the LineRef is an undefined label or refers to a non-existent data line or to a line that is not a data line, a null string is returned and RC has a non-zero value.

A Line Handle exists independently of a Line Label. A Line Handle for a line is persistent, will exist after the macro which assigns it has terminated, and will be saved in the file's STATE information if STATE ON is in effect.

Special Notes

If a data line already has a Line Handle assigned to it, Get_Handle$ returns that existing Handle; a new Handle value will not be created. If you wish to force a new Handle value, you must first issue a Drop_Handle$ for the line, then call Get_Handle$.

The Get_Handle$ function supersedes Request_Label$.

All new macros should call Get_Handle$.