Function Details

Introduction


For the descriptions below, each function is shown as it would be called to return a value to a local variable within the script.  


All functions which return a string contain a trailing $ and are shown returning a value to str-var, a string variable.

All functions which return a numeric value do not contain a trailing $ and are shown returning a value to num-var, a numeric variable.


Note that in the macro language, there is no requirement that the data returned by a function be assigned to a local script variable before using it.   For example, to check if the current Edit file has been modified, it is perfectly correct to code:

if Get_Modified = TRUE then ...


It does not have to be coded as:


LocalVar = Get_Modified

if LocalVar = TRUE then ...


In fact, because the Get_Modified function returns a TRUE or FALSE value already, you don't even have to compare it explicitly to TRUE or FALSE.  You can use the value returned by the function directly, like this:

if Get_Modified then ...


This is different - and much simpler - than the IBM Rexx / ISREDIT interface, in which this technique was not available.


To illustrate, here is a simple macro that emulates a built-in command that existed in Tritus SPF:


' QMOD.MACRO

IF GET_MODIFIED THEN

  SET_MSG (OK, "DATA MODIFIED")

ELSE

  SET_MSG (OK, "DATA NOT MODIFIED")

END IF


With the * on the status line, and color-coded edit tabs, a macro to show the modified state isn't really necessary in SPFLite.  It's shown here just as an example.



Detailed description of functions


Note that in the descriptions below, names like  line-ptr  are just symbolic for an actual name or expression you might use.  In real code, you can't literally have variable names with minus signs in them (underscores are allowed, though).


Function operands may be either variables or expressions, providing they are of the correct type; you are not limited to just using variables.  For a given function, consult the function description as to whether a particular operand should be numeric-valued or string-valued.


Operands whose descriptions end in -num or -ptr are numeric.  Operands whose descriptions end in -str are strings.  


When the results of a function are not important to you, it is not necessary to assign the results to a variable; you can just call this function as a "procedure call" statement, by simply specifying the function name and its parameters on a single line, with no variable name and = equal sign preceding it.



str-var = Get_Arg$(arg-num)

str-var = Get_Arg$(first-arg-num,last-arg-num)


Operands:

arg-num


first-arg-num

last-arg-num


the number of the only macro operand


the number of the first macro operand

the number of the last macro operand


Returns:


For (arg-num), it returns the specified macro operand number arg-num, where the operands are numbered left to right starting at 1.  


For (first-arg-num,last-arg-num) it returns a range of operands from operand number first-arg-num through operand number last-arg-num, where the operands are numbered left to right starting at 1.  


Unless last-arg-num is 0, then first-arg-num must be <= last-arg-num.


Macro arguments are treated as simple space delimited operands.  If an undefined / illegal argument number is specified, a "" (null) will be returned.


If a valid argument number, RC will be 0 and Msg$ will be "" (Null)

If an invalid argument number, RC will be 8, and Msg$ will contain an error message


Special Notes:


If Get_Arg$(0) is requested, the complete macro arguments are returned as one string, where the individual arguments are separated from each other by blanks.  





num-var = Get_Arg_Count


Operands:

none



Returns:


Returns the number of supplied macro arguments.  If no arguments are specified, 0 will be returned.  When the macro header contains one or more default values, the number of default values supplied will be the minimum value returned by Get_Arg_Count.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Arg_KW("keyword")


Operands:

keyword

The literal value of the keyword to be tested.


Returns:


Returns True of False depending on whether the specified Keyword has been entered as an operand.


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Arg_KWGroup$("list-name")


Operands:

list-name

The literal value of the Keyword list-name for which the value of the entered keyword is to be returned.


Returns:


Returns the actual keyword which was entered on the command operand line.  If no keyword in the list of valid keywords was entered, this function will return "" (Null)


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Arg_LRef$(n)


Operands:

n

The relative Line Reference  value desired, counting from left to right.


Returns:


Returns the specified Line Reference value.


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Arg_NumLit$(n)


Operands:

n

The relative Numeric Literal value desired, counting from left to right.


Returns:


Returns the specified Numeric Literal value.


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Arg_Tag$(n)


Operands:

n

The relative Tag Operand value desired, counting from left to right.


Returns:


Returns the specified Tag Operand value.


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Arg_TextLit$(n)


Operands:

n

The relative Text Literal value desired, counting from left to right.


Returns:


Returns the specified Text Literal value.


Note: this function is only valid following successful completion of an SPF_Parse function call to parse the command line operands.


RC will always be 0 and Msg$ will be "" (Null) on successful completion.

RC will be 8 and Msg$ set to an error message on any error.  e.g. an invalid 'n' value


Special Notes:


A full description of using this function will be found in How do I access the parsed out Operands?




str-var = Get_Clr_Line$(line-ptr)


Operands:

line-ptr

the line pointer for the desired color control line to be fetched.


Returns:


Returns the current color control line data for the specified line-ptr.  Line-ptr must be a line pointer for a data line.


str-var will be "" ( zero-length string) if the line-ptr value is invalid.


RC will be 0 and Msg$ will be "" (Null) for successful completion

RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line-ptr)


Special Notes:





num-var = Get_Csr_Col


Operands:

none



Returns:


Returns the column number of the current cursor line.   If the cursor is not on a valid line in the text area, then 0 (zero) will be returned.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Csr_LPtr


Operands:

none



Returns:


Returns the line pointer of the line containing the cursor.  If the cursor is not on a valid line in the text area, then 0 (zero) will be returned.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_Curr_Line$


Operands:

none



Returns:


Returns the contents of the edit data line where the cursor was located at the start of macro processing.   If the cursor is not located on a valid data line, the value returned will be "" (a zero-length string).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_Curr_Path$


Operands:

none



Returns:


Returns the full path of the Windows 'current' working directory.  This is the current directory in effect when SPFLite is started up from a command prompt, or is the Start directory property when SPFLite is run from an icon, such as from the Windows Desktop.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


None





str-var = Get_Curr_Word$


Operands:

none



Returns:


Returns the contents of the current 'word' where the cursor was located at the start of macro processing.   If the cursor is not located on a valid data line, or located on white space or delimiters within the line, the value returned will be "" (a zero-length string).   Note that 'word' means the same here as it does when used with a FIND 'xxx' WORD command.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


An entire 'word' will be returned regardless of where within the word the cursor is located. It doesn't matter whether the cursor is on the first, last, or any other character of the word.


For purposes of determining what a 'word' is, the same rules are used as for a FIND/CHANGE command using the WORD operand. i.e. based on the contents of the Profile WORD character setting.




str-var = Get_Dest_LCmd$


Operands:

none



Returns:


The string containing the destination line command if present.  This may be an empty (null) string if no destination line range was specified.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


Get a string containing the name of the destination line command.  This may be an A/AA, B/BB, H/HH, W/WW, O/OO, or OR/ORR command, or may be an empty (null) string if no destination line range was specified.




num-var = Get_Dest_Op


Operands:

none



Returns:


Returns the optional numeric line operand, if it is entered, for the destination line command if one is used.  If none is entered, this will return 0 (zero).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


For example, if you have a destination line range of H5, Get_Dest_Op will return the number 5.  The function returns 0 when no explicit command operand number is specified.  For instance, if you define a destination block such as HH which happens to be 5 lines long, the function will still return 0, because the number 5 was not actually specified on the HH block.





str-var = Get_Dest_LMOD$


Operands:

none



Returns:


Gets the + or - (post-unexclude or post-exclude) modifier and K (Keep) modifier if one is present on the destination line range.  The returned value is always two characters long.  Position 1 containing + or - or blank, and position 2 will contain a K or blank.  


The / and \ line command modifiers are processed, if present, and this gets reflected in first and last LPTR values for the line range, but the  / and \ codes themselves are not returned as LMOD values.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:





num-var = Get_Dest1_LPtr


Operands:

none



Returns:


Get the line pointer of the first (or only) line in the destination line range, or 0 if not applicable.


The destination line range may be defined by A/AA, B/BB, H/HH, W/WW, O/OO, or OR/ORR command(s), if present.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


Note that for A/AA and B/BB, the value returned is not normalized to be treated as an A line command.  You will have to look at Get_Dest_LCmd to determine the line command used, and act accordingly.



num-var = Get_Dest2_LPtr


Operands:

none



Returns:


Get the line pointer of the last (or only) line in the destination line range, or 0 if not applicable.


The destination line range may be defined by A/AA, B/BB, H/HH, W/WW, O/OO, or OR/ORR command(s), if present.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


Note that for A/AA and B/BB, the value returned is not normalized to be treated as an A line command.  You will have to look at Get_Dest_LCmd to determine the line command used, and act accordingly.




str-var = Get_ENVVAR$(env-var-str)


Operands:

env-var-str

the name of the environment variable for which the data is to be returned.


Returns:


Returns the string value for the specified var-name.  If an unknown variable name is specified, a "" (a zero-length string) will be returned.


If a valid env-var-str, RC will be 0 and Msg$ will be "" (Null)

If an invalid env-var-str, RC will be 8, and Msg$ will contain an error message


Special Notes:


For example, Get_ENVVAR$("COMSPEC") would return the name of the system's command processor (Typically C:\Windows\System32\Cmd.EXE)





str-var = Get_EXE_Path$


Operands:

none



Returns:


Returns the full path of the folder where SPFLite.EXE is run. This will usually be C:\Program Files\SPFLite.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_FileBase$


Operands:

none



Returns:


Returns the base filename of the current edit file.   e.g. for MYFILE.TXT it would return MYFILE


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_FileDate$


Operands:

none



Returns:


Returns the last modified date of the current file in the format YYYY-MM-DD.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_FileName$


Operands:

none



Returns:


Returns the filename of the current edit file.   e.g. MYFILE.TXT


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_FileExt$


Operands:

none



Returns:


Returns the current file extension, including the leading period.  e.g. for MYFILE.TXT it would return .TXT


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_FilePath$


Operands:

none



Returns:


Returns the current file path for the current file.    e.g. C:\Users\Me\Documents


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_FileTime$


Operands:

none



Returns:


Returns the last modified time of the current file in the format  hh:mm:ss


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_FIND_Col


Operands:

none



Returns:


Returns the column number where the last FIND / CHANGE was located.   Until the first FIND / CHANGE command is issued for the current Edit file, this will return 0 (zero).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_FIND_Len


Operands:

none



Returns:


Returns the length of the last FIND / CHANGE search argument.   Until the first FIND / CHANGE command is issued for the current Edit file, this will return 0 (zero).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_FIND_LPtr


Operands:

none



Returns:


Returns the line pointer of the last line found by a FIND / CHANGE command.   Until the first FIND / CHANGE command is issued for the current Edit file, this will return 0 (zero).        


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_First_LPtr


Operands:

none



Returns:


Returns a Line Pointer to the first line of the Edit session.  If there are no lines in the dataset, Get_FIRST_LPTR returns 0 (zero).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_FullPath$(file-name)


Operands:

file-name

The file name to be fully qualified.


Returns:


Returns a fully qualified filename including Drive:\path\filename


If the macro call is issued from a temporary session (CLIP, Set-Edit, (Empty), etc.) the path assumed will be the last displayed path in File Manager.


If the call is issued from a normal Edit/Browse session, the path assumed will be that of the currently loaded file.Line Pointer to the first line of the Edit session.  If there are no lines in the dataset,


If the passed file-name is Null, or already appears to be qualified, it is returned untouched and the RC will be 8, and Msg$ will contain an appropriate error message.  


Otherwise the RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_Gbl_Num([TblNum,]key-str)


Operands:

TblNum

Optional.  The sub-table number to be searched.  If omitted, zero is assumed.



key-str

the desired key for which the associated value is desired.


Returns:


Returns the requested value to num-var.  If the key-str is invalid / not found, zero (0) is returned.


A successful retrieval will set RC to 0 and Msg$ will be "" (Null)

An unsuccessful retrieval, will set RC to 8 and Msg$ to an error message.


Special Notes:







num-var = Get_Gbl_Num_Count


Operands:

none



Returns:


Returns the current number of stored numeric key/value pairs.


RC is always set to 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_Gbl_Num_Name$(index-num)


Operands:

index-num

the index number of the desired numeric entry.


Returns:


Returns the current key name associated with this entry to str-var.


If successful, RC is always set to 0 and Msg$ will be "" (Null)

If unsuccessful (invalid index-num), RC will be 8, and Msg$ will contain an error message.


Special Notes:






str-var = Get_Gbl_Num_TableName$(index-num)


Operands:

index-num

the index number of the desired numeric entry.


Returns:


Returns the current Table-Number and key name associated with this entry to str-var. The Table-number precedes the key name separated by a comma.  e.g.  4,VARNAME


The table number is easily accessed via VAL(str-var)

The keyname may be accessed via REMAIN$(strvar, ",")


If successful, RC is always set to 0 and Msg$ will be "" (Null)

If unsuccessful (invalid index-num), RC will be 8, and Msg$ will contain an error message.


Special Notes:







str-var = Get_Gbl_Str$([TblNum,]key-str)


Operands

TblNum

Optional.  The sub-table number to be searched.  If omitted, zero is assumed.



key-str

the desired key for which the associated value is desired.


Returns:


Returns the requested value to str-var.  If the key-str is invalid / not found, "" (null) is returned.


A successful retrieval will set RC to 0 and Msg$ will be "" (Null)

An unsuccessful retrieval, will set RC to 8 and Msg$ to an error message.


Special Notes:







num-var = Get_Gbl_Str_Count


Operands:

none



Returns:


Returns the current number of stored numeric key/value pairs.


RC is always set to 0 and Msg$ will be "" (Null)


Special Notes:







str-var = Get_Gbl_Str_Name$(index-num)


Operands:

index-num

the index number of the desired numeric entry.


Returns:


Returns the current key name associated with this entry to str-var.


If successful, RC is always set to 0 and Msg$ will be "" (Null)

If unsuccessful (invalid index-num), RC will be 8, and Msg$ will contain an error message.


Special Notes:






str-var = Get_Gbl_Str_TableName$(index-num)


Operands:

index-num

the index number of the desired numeric entry.


Returns:


Returns the current Table-Number and key name associated with this entry to str-var. The Table-number precedes the key name separated by a comma.  e.g.  4,VARNAME


The table number is easily accessed via VAL(str-var)

The keyname may be accessed via REMAIN$(strvar, ",")


If successful, RC is always set to 0 and Msg$ will be "" (Null)

If unsuccessful (invalid index-num), RC will be 8, and Msg$ will contain an error message.

Special Notes:








str-var = Get_INI_Path$


Operands:

none



Returns:


Returns the full path of the SPFLite data storage folder.  i.e. the folder where SPFLite data files are stored (INI files, Profiles, Macros, etc.)


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_Label$(line-ptr)


Operands:

line-ptr

The line pointer of the data line whose line pointer is to be obtained.


Returns:


If the line-ptr argument is a valid line pointer to a data line, the function will return the label associated with that data line, if one exists; otherwise it will return a null (empty) string; the RC value will be set to 0 when the line-ptr is associated with a data line.


The string value of the returned label will be just as it appears in the edit session, with a leading . dot and one to five letters in upper case.


If line-ptr is an invalid line pointer value, or is the line pointer of a non-data line, the function will return a null (empty) string and set RC to 8.


Special Notes:





num-var = Get_LBound


Operands:

none



Returns:


Returns the current Left bounds value.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Last_LPtr


Operands:

none



Returns:


Returns a Line Pointer to the last line of the Edit session.    If there are no lines in the dataset, Get_LAST_LPTR returns 0 (zero).


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_Line$(line-ptr)


Operands:

line-ptr

the line pointer for the desired line to be fetched.


Returns:


Returns the current Edit text data for the specified line-ptr.  Line-ptr can be a line pointer for a data line or a special line.


str-var will be "" ( zero-length string) if the line-ptr value is invalid.


RC will be 0 and Msg$ will be "" (Null) for successful completion

RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line-ptr)


Special Notes:






num-var = Get_Line_Len(line-ptr)


Operands:

line-ptr

the line pointer of the desired line.


Returns:


Returns the length of the current Edit data line for the specified line-ptr.  Line-ptr must be a line pointer for a data line, not for a special line.


num-var will be 0 if the line-ptr value is invalid or is not the line pointer of a data line.


RC will be 0 and Msg$ will be "" (Null) for successful completion

RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line-ptr)


Special Notes:







str-var = Get_Line_Type$(line-ptr)


Operands:

line-ptr

the line pointer for which the line's type is to be returned


Returns:


Returns a string containing one of the following values:


DATA, EXCL, TOP, BOT, TABS, BNDS, COLS, WORD, MARK, MASK, PROF, FILE or NOTE.


If the extended NOTE types are used, the returned string will be xNOTE (e.g.  ANOTE,  BNOTE, XNOTE etc.)


If line-ptr is invalid, RC will be set to 8.  Otherwise, RC is set to 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_LNum(line-ptr)


Operands:

line-ptr

the specific line-ptr for which the line number is desired.


Returns:


If the line-ptr is valid, the associated external line number is returned; RC is set to 0 and Msg$ set to "" (null)


If the line-ptr is invalid, "" (null) is returned,  RC is set to 8, and Msg$ is set to an error message.


Special Notes:


Only data lines have line numbers, so if you attempt to use Get_LNum$ using a line-ptr value for which a call to IS_DATA(line-ptr) would have returned False, the call to GET_LNUM$(line-ptr) will with RC=8 and a returned value of 0.


Assuming the edit session is not operating in Fast Renumber mode, the line number of the last line of the file, and the number of lines in the file, are the same number; call this number N.  If you call Get_LNUM with an LPTR value <= 1 or > N+2, the Line Pointer parameter is out of range, and Get_LNUM will return 0.





num-var = Get_LOC_LPtr


Operands:

none



Returns:


Returns the line pointer of the last line found by the LOCATE command.  If the last LOCATE was for a special line type (FILE,  SPECIAL, etc.) which would be a non-data line, this will return zero (0).   Until the first LOCATE command is issued for the current Edit file, this will return 0 (zero).        


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_LPtr(line-ref)


Operands:

line-ref

a line reference.   This could be a line number as it is displayed on the screen, or a line label (.HERE, .THERE, etc.)


If the line reference is a simple line number, the line-ref value may be specified either as a string expression or as a numeric expression.


Returns:


If the line reference is valid, the associated line pointer is returned; RC is set to 0 and Msg$ set to "" (null)


If the line reference is invalid, 0 (zero) is returned,  RC is set to 8, and Msg$ is set to an error message.


Special Notes:







str-var = Get_MacName$


Operands:

none



Returns:


Returns the name of the currently running macro.  For a macro called ABC.MACRO, the value of the string returned will be "ABC".


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:





str-var = Get_MASKLine$


Operands:

none



Returns:


Returns the current MASK line data.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Modified


Operands:

none



Returns:


Returns TRUE or FALSE.   True is returned if the current Edit file has been modified since loaded or the last SAVE command; otherwise false if the file is unmodified.  


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


Get_Modified would return True under the same conditions that would produce an * asterisk on the Edit status line or would change the color of the Edit tab (assuming the color palettes for modified and unmodified tab colors have been properly set).  


In the case of an MEDIT session, Get_Modified will return True if any file in the MEDIT session has been modified.




num-var = Get_Modified_FileName


Operands:

filename

The name of the file within a MEdit session for which the modified status is required.


Returns:


Returns TRUE or FALSE.   True is returned if the specified file has been modified since loaded or the last SAVE command; otherwise false if the file is unmodified.  


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


If the function is used in a non-MEdit session, it will act exactly like the basic Get_Modified function.




str-var = Get_Msg$


Operands:

none



Returns:


Contains the text of the last message issued by an SPFLite interface function.   If a non-successful Return code had been issued by a function, the message associated with that error can be fetched with this function call.


Get_Msg$ and Get_RC do not themselves modify the function-level RC or Message status values, but simply report them.  That is, Get_Msg$ and Get_RC do not have, or set, function-level status values of their own, but only return the last RC or Message value set by some other SPFLite interface function.


Special Notes:






num-var = Get_Next_LPtr(line-ptr, adjust-amount, line-type)


Operands:

line-ptr

The starting line-pointer to be adjusted and returned.



col-num

The number of lines by which the line-ptr is to be adjusted.  Positive values indicate adjustment downward in the file (towards the last line) and negative values indicate adjustment upward in the file (towards the top line).



line-type

This is a string operand which may be one of:

DATA        Adjustment is made where adjust-amount is measured by counting only DATA line types


SPECIAL        Adjustment is made where adjust-amount is measured by counting only non-DATA (i.e. SPECIAL) line types


:tagname        Adjustment is made where adjust-amount is measured by counting only lines which have a matching line tag.



Returns:


The adjusted line-ptr as requested.   If it is impossible to satisfy the request (e.g. movement has reached either the top or bottom of the file, depending on direction) then 0 (zero) will be returned and RC and Msg$ set with appropriate error indications.


Special Notes:


The Get_Next_LPtr function will typically be used in line scanning loops to move from a currently processed line to the next/previous line of a particular type.




str-var = Get_Profile$(option-str)


Operands:

option-str

A string containing the name of a PROFILE option.  The permitted options are:




Option name


NAME    

AUTOBKUP

AUTOSAVE

CAPS    

CASE    

CHANGE  

COLS    

EOL      

HEX      

HIDE    

HILITE  

IMPORTTABS

LRECL

MARK

MASK    

MINLEN

NOTIFY  

PAGE    

PRESERVE

RECFM    

SCROLL  

SETUNDO

SOURCE  

START    

STATE    

SUBARG  

TABS

WORD    



Return value


profile-name [USING(alt-prof-name)] LOCKED | UNLOCKED  

ON | OFF

ON | OFF PROMPT | NOPROMPT

ON | OFF  |  AUTO:on | AUTO:off

C | T

DS | CS

ON | OFF

CRLF | LF | CR | NL | X'xx'

ON | OFF

ON | OFF

OFF | FIND ON | OFF AUTO ON | OFF

nnn

nnn

ON | OFF

the current MASK string

nnn

NONE | EDIT | ALL

ON | OFF [ +/-nn ]

ON | OFF | C

F | V | U

CSR | PAGE | HALF |  ... ETC.

nnn

ANSI | UTF8 | UTF16 | UTF16BE | EBCDIC

PRIOR | LABEL | FIRST | LAST | NEW

ON | OFF

OFF | string

ON | OFF

A string containing all characters which are considered valid Word characters for the current Profile.


Returns:


The string value of the requested option is returned.


RC will be 8 if the option-str is not a valid string PROFILE option name; otherwise 0.


Special Notes:


There is no corresponding general function to set a PROFILE option.  To accomplish that, issue an SPF_CMD for the desired setting.  For example: SPF_CMD("EOL AUTO").


For numeric settings like LRECL, if you need to work with the returned value in numeric form, you can enclose the request in a VAL() function, or assign the result to a numeric variable first.


Example:

DIM MyLRECL, myLRECL1 as NUMBER

myLRECL = Get_Profile$("LRECL")

myLRECL1 = val(Get_Profile$("LRECL")) + 1





num-var = Get_RBound


Operands:

none



Returns:


Returns the current Right bounds value.  If the right bounds is MAX, 0 (zero) is returned.  


RC will always be 0


Special Notes:


Note that a return value of 0 here means that there is no maximum (the right boundary has no arbitrary limit), rather than implying that the right boundary were "column 0".





num-var = Get_RC


Operands:

none



Returns:


The Return Code from the last executed SPFLite function call.   The return codes will generally be 0, 4 or 8, where 0 = success, 4 = warning and 8 = failure.  


The specifics of the error can be obtained via Get_MSG$.    In many cases, depending on the particular function, the RC may be returned directly from the function call as well.   See the specifics for each function call.


Get_Msg$ and Get_RC do not themselves modify the function-level RC or Message status values, but simply report them.  That is, Get_Msg$ and Get_RC do not have, or set, function-level status values of their own, but only return the last RC or Message value set by some other SPFLite interface function.


Special Notes:






num-var = Get_Select_First_LPtr


Operands:

index-num

None


Returns:


Returns the line-ptr to the first line of a selected text block.   If no block is currently selected, 0 (zero) will be returned.


RC is always set to 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Select_Last_LPtr


Operands:

index-num

None


Returns:


Returns the line-ptr to the last line of a selected text block.   If no block is currently selected, 0 (zero) will be returned.


RC is always set to 0 and Msg$ will be "" (Null)

Special Notes:






num-var = Get_Select_Col


Operands:

index-num

None


Returns:


Returns the left-hand column number of the selected block.   If no block is currently selected, 0 (zero) will be returned.


RC is always set to 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_Select_Len


Operands:

index-num

None


Returns:


Returns the length of the current selected area.   If no block is currently selected, 0 (zero) will be returned.


RC is always set to 0 and Msg$ will be "" (Null)



Special Notes:






str-var = Get_Session_Type$


Operands:

none



Returns:


Returns a string containing the 'type' of the current edit tab.   This will be one of:

BROWSE

EDIT

CLIP-EDIT

SET-EDIT

MEDIT

RDONLY


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


This value could be saved and used, for example, to return the screen display back to it's original position using the Set_Csr_Pos if macro processing had caused it to be altered.




str-var = Get_SETVAR$(set-var-str)


Operands:

set-var-str

the name of the SPFLite SET variable for which the data is to be returned.


Returns:


Returns the string value for the specified SET variable named by set-var-str.  If an unknown variable name is specified, a "" (a zero-length string) will be returned.


If a valid set-var-str, RC will be 0 and Msg$ will be "" (Null)

If an invalid set-var-str, RC will be 8, and Msg$ will contain an error message


Special Notes:


For example, Get_SETVAR$("ABC") would return the value assigned to the SPFLite SET variable ABC.




str-var = Get_Src_LCmd$


Operands:

none



Returns:


Contains the line command used to mark the source line range for use by the macro.  e.g. C/CC, M/MM or the macro name itself if this is a line command macro.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


For line-command macros, this is the macro name (possibly a plural/block form) of the macro name.


For primary-command macros, this may be a C/CC or M/MM command, or may be an empty (null) string if no C/CC/M/MM was used with a primary-command macro.




num-var = Get_Src_Op


Operands:

none



Returns:


Contains the optional numeric line operand, if it is entered, for the source line range if used.  If none is entered, this will return 0 (zero).  For example, if the line command entered were C12, the value returned would be 12.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


For example, if you have a source line range of C5, Get_Src_Op will return the number 5.  The function returns 0 when no explicit command operand number is specified.  For instance, if you define a source block such as CC which happens to be 5 lines long, the function will still return 0, because the number 5 was not actually specified on the CC block.





str-var = Get_Src_LMOD$


Operands:

none



Returns:


The line command modifiers when present.


The / and \ line command modifiers are processed, if present, and this gets reflected in first and last LPTR values for the line range, but the  / and \ codes themselves are not returned as LMOD values.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


Gets the + or - (post-unexclude or post-exclude) modifier and K (Keep) modifier if one is present on the source line range.  The returned value is always two characters long.  Position 1 will contain + or - or blank, and position 2 will contain a K or blank.  


The / and \ line command modifiers are processed, if present, and this gets reflected in first and last LPTR values for the line range, but the  / and \ codes themselves are not returned as LMOD values.



num-var = Get_Src1_LPtr


Operands:

none



Returns:


Contains the line pointer of the first line in the selected line range marked for use by the macro.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:







num-var = Get_Src2_LPtr


Operands:

none



Returns:


Contains the line pointer of the last line in the selected line range marked for use by the macro.   Note: Src1 and src2 may be the same for a single-line selection.



RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_Tag$(line-ptr)


Operands:

line-ptr

The line pointer of the data line whose line tag is to be obtained.


Returns:


If the line-ptr argument is a valid line pointer to a data line, the function will return the tag associated with that data line, if one exists; otherwise it will return a null (empty) string; the RC value will be set to 0 when the line-ptr is associated with a valid data line.


The string value of the returned tag will be just as it appears in the edit session, with a leading : colon and one to five letters in upper case.


If line-ptr is an invalid line pointer value, or is the line pointer of a non-data line, the function will return a null (empty) string and set RC to 8.


Special Notes:






num-var = Get_TopScrn_LPtr


Operands:

none



Returns:


Returns the line pointer of the line which is currently at the top of screen position.  


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:


This value could be saved and used, for example, to return the screen display back to it's original position using the Set_Csr_Pos if macro processing had caused it to be altered.





num-var = Get_Uniq_ID()


Operands:

none

There are no operands.


Returns:


Returns a unique ID number for this edit session.  The number will be unique to the particular instance of SPFLite.  No other Edit/Browse tab will ever duplicate the number.   This can be useful for sets of related macros that want to store state type data and ensure the data is identified as belonging to a particular edit session.


Special Notes:






str-var = Get_WORDCHAR$


Operands:

none



Returns:


Returns a string containing all the characters which are considered valid Word characters for the current Profile.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Get_XLINES(line-ptr)


Operands:

line-ptr

The line pointer of the exclude marker for which the size of the exclude block is desired.


Returns:


If line-ptr is not a valid line, or not an Exclude line marker, then 0 (zero) will be returned, RC will be 8, and Msg$ set to an appropriate text message.


If line-ptr is valid exclude marker, the function will return the number of excluded lines in the group, RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Get_XSTATUS$(line-ptr)


Operands:

line-ptr

The line pointer of the data line whose exclude status is to be obtained.


Returns:


Returns a string containing either X or NX to indicate the line's exclude status.


If line-ptr is not a valid line, then "" (null) will be returned, RC will be 8, and Msg$ set to an appropriate text message.


If line-ptr is valid, then RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = Halt([rc-num,] msg-str [,msg-str] ...)


Operands:

[rc-num]

this optional operand provides thee numeric return code you wish SPFLite to use for the success of this macro invocation.  If the operand is omitted, then 0 (zero) is assumed.


The conventions for these return codes are:


RC=0 for success

RC=4 for a warning condition

RC=8 when a failure occurs


There are predefined symbols for these values.  OK is the same as 0; WARN is the same as 4, and FAIL is the same as 8.


To avoid issues with future versions of SPFLite, only the values 0, 4 and 8 (or their symbolic equivalents of OK, WARN and FAIL) should be used as return code values.



msg-str

a string containing the text of the message to be issued.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


Nothing is returned.  The macro is terminated by this function and control returned to normal SPFLite operation.


Special Notes:


If a message is issued with rc-num=4, SPFLite will prefix it with "Macro warning: "

If a message is issued with rc-num=8, SPFLite will prefix it with "Macro failed: "


Because the RC operand is optional, simple success messages can be issued with only the text string operand.  For example:

Halt("Normal completion")

is functionally equivalent to:

Halt(OK, "Normal completion")




num-var = Is_Line_Cmd


Operands:

none



Returns:


Returns TRUE (1) if the macro was launched as a line-command macro, by placing its name into the line sequence-area of one line (if used on a single line, or with an n or / or \ modifier) or two lines (if used in the block-mode form).  Otherwise, FALSE (0) is returned.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:





num-var = Is_Primary_Cmd


Operands:

none



Returns:


Returns TRUE (1) if the macro was launched as a line-command macro, by placing its name into the line sequence-area of one line (if used on a single line, or with an n or / or \ modifier) or two lines (if used in the block-mode form).  Otherwise, FALSE (0) is returned.


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






num-var = IS_xxxx(line-ptr)


Operands:

line-ptr

the line pointer of the line which is to be tested.


Returns:


Returns TRUE if the line at line-ptr is the indicated type, or FALSE if it is not or if the line-ptr is invalid.


The IS_xxxx function exists in the following forms:


Is_Bnds(line-ptr)                - a BNDS line

Is_Bottom(line-ptr)        - the Bottom of Data line

Is_Cols(line-ptr)                - a COLS line

Is_Data(line-ptr)                - a normal text data line

Is_File(line-ptr)                - a File line

Is_Mark(line-ptr)                - a MARK line

Is_Mask(line-ptr)                - a MASK line

Is_Note(line-ptr)                - a NOTE line

Is_Prof(line-ptr)                - a =PROF> line

Is_Tabs(line-ptr)                - a TABS line

Is_Top(line-ptr)                - the Top of Data line

Is_ULine(line-ptr)                - a User line (having a | mark)


Is_XLine(line-ptr)                - an excluded line (usually, but

                                         not always, a data line)                


Is_XMarker(line-ptr)        - an excluded line marker (the

                                         dashed "placeholder" line)


Is_Word(line-ptr)                - a WORD line


RC will always be 0 and Msg$ will be "" (Null)


Special Notes:






str-var = Release_Label$(Label-ref | "ALL")


Operands:

label-ref

the label reference which is to be released.  Normally, this will be the label reference returned to the macro by the Request_Label$ function.


If "ALL" is passed as the label-ref, it is a request to release all temporary labels.


Returns:


If label-ref is a normal temporary label returned by Request_Label$, then that label is removed from the line and the function returns a null string and RC = 0


If label-ref is a permanent label, that label is left alone on the line and is returned by the function along with a RC=0


If label-ref is a not defined, then the function returns a null string and RC = 8


If label-ref is the string "ALL", then all known temporary labels are removed.  The function returns a null string and RC = 0


Special Notes:






str-var = Request_Label$(Line-ptr)


Operands:

line-ref

the line pointer of the line for which a label is desired.


This can be a string in the form ".123" or "!456"


Returns:


If line-ptr points at a line which already has a label, then that label is returned by the function.  RC=0 is set.


If the line has no current label, a temporary label will be generated and returned.   RC=0 will be set.


Whether an existing label is returned, or a new temporary label is returned, you should only remove labels when finished by using the Release_Label$ function.  By doing so, the macro need never care of know whether the label is temporary or not, and will be assured of never accidentally removing a permanent label.


Special Notes:







num-var = Reset_Gbl_Num([TblNum])


Operands:

TblNum

Optional. The sub-table number to be cleared.  If NO TblNum operand is entered, ALL sub-tables are cleared.   Entering a 0 (Zero) is NOT the same as omitting the operand, it will simply clear sub-table 0.


Returns:


Clears the Gbl_Num storage area and returns True if successful, or False if the function fails.


Special Notes:







num-var = Reset_Gbl_Str([TblNum])


Operands:

TblNum

Optional. The sub-table number to be cleared.  If NO TblNum operand is entered, ALL sub-tables are cleared.   Entering a 0 (Zero) is NOT the same as omitting the operand, it will simply clear sub-table 0.


Returns:


Clears the Gbl_Str storage area and returns True if successful, or False if the function fails.


Special Notes:






num-var = Set_Clr_Line(line-ptr, clr-str)


Operands:

line-ptr

the line pointer for the data line to be replaced



clr-str

the new color control string to be stored in the line referenced by line-ptr.


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:







num-var = Set_Csr(line-ptr, col-num, [len-num])


Operands:

line-ptr

the line pointer of the line where the cursor is to be placed.



col-num

the column number where the cursor should be placed.  If col-num is zero, the cursor is placed in the line number field of the given line.



len-num

If a non-zero len-num is provided, then the data starting at col-num, for len-num characters will be highlighted.  When len-num is omitted, it is treated as 0; that is, the cursor will be positioned, but no highlighting will be performed.


Returns:


If line-ptr is valid, RC will be 0 and Msg$ will be "" (null)


If line-ptr is invalid, RC will be 8 and Msg$ will contain an error message.


Special Notes:


Requests SPFLite to move the cursor to the specified line and column number.





num-var = Set_Gbl_Num([TblNum,]key-str, value-num)


Operands:

TblNum

Optional.  The sub-table number in which to store this value.  If omitted, a default value of zero is assumed.



key-str

a string value under which to store the numeric value



value-num

the numeric value to be associated with key-str.


Returns:


Always returns 0 to num-var and RC.  Msg$ will be "" (Null)


Special Notes:


If a key with the value of key-str already exists, the prior value is replaced with the new value-num.   If the key does not already exist, it is created.





num-var = Set_Gbl_Str([TblNum,]key-str, value-str)


Operands:

TblNum

Optional.  The sub-table number in which to store this value.  If omitted, a default value of zero is assumed.



key-str

a string value under which to store the numeric value



value-str

the string value to be associated with key-str.


Returns:


Always returns 0 to num-var and RC.  Msg$ will be "" (Null)


Special Notes:


If a key with the value of key-str already exists, the prior value is replaced with the new value-str.   If the key does not already exist, it is created.





num-var = Set_Line(line-ptr, data-str)


Operands:

line-ptr

the line pointer for the data line to be replaced



data-str

the new data value to be stored in the line referenced by line-ptr.


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:







num-var = Set_Msg([rc-num,] msg-str [,msg-str] ...)


Operands:

[rc-num]

this optional operand provides thee numeric return code you wish SPFLite to use for the success of this macro invocation.  If the operand is omitted, then 0 (zero) is assumed.


The conventions for these return codes are:


RC=0 for success

RC=4 for a warning condition

RC=8 when a failure occurs


There are predefined symbols for these values.  OK is the same as 0; WARN is the same as 4, and FAIL is the same as 8.


To avoid issues with future versions of SPFLite, only the values 0, 4 and 8 (or their symbolic equivalents of OK, WARN and FAIL) should be used as return code values.



msg-str

a string containing the text of the message to be issued.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


The rc-num value is returned.  The value of msg-str is what will be returned by the next Get_Msg$ call.


Special Notes:


If a message is issued with rc-num=4, SPFLite will prefix it with "Macro warning: "

If a message is issued with rc-num=8, SPFLite will prefix it with "Macro failed: "


Because the RC operand is optional, simple success messages can be issued with only the text string operand.  For example:

Set_Msg("Normal completion")

is functionally equivalent to:

Set_Msg(OK, "Normal completion")


It is important to understand that RC and message values passed back by other functions (like Get_Line$, for instance) are not automatically passed through to the edit user, even when the RC value is non-zero, signifying a warning or error condition was detected.  You must explicitly call Set_Msg yourself if you wish a message to be displayed back to the user once the macro completes execution.


If Set_Msg is followed by any other SPFLite-provided function which itself sets the RC and message values, the values set by Set_Msg will be overridden.  If it is your intent to use Set_Msg to pass back a message to the edit user (yourself) that appears on the edit screen, the call to Set_Msg should be the last function you call before issuing a HALT statement.  (Or use the HALT statement itself to issue the RC and message string)





num-var = Set_SETVAR(set-var-str, value-str)


Operands:

set-var-str

a string containing the name of the SPFLite SET variable for which the data is to be changed.



value-str

the new value to be assigned to the variable named by set-var-str


Returns:


If successful, RC will be 0 and Msg$ will be "" (Null)

If a failure, RC will be 8, and Msg$ will contain an error message


Special Notes:


For example, Set_SETVAR("ABC", "New value") would set the variable ABC to the string "New value".





num-var = Set_TopScrn_LPtr(line-ptr)


Operands:

line-ptr

the line pointer for the line to be positioned at the top of screen when the macro exits.


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:


If your macro uses both Set_TopScrn_LPtr and Set_Csr, the positioning of Set_Csr will override that of the Set_TopScrn_LPtr if the desired cursor position is not within the visible screen as set by the Set_TopScrn_LPtr function.   i.e. Set_Csr 'wins'.





num-var = SPF_Cmd(cmd-str [,cmd-str] ... )


Operands:

cmd-str

the SPFLite primary command you wish executed.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


RC will be set to the return code issued by the command.  This value will also be returned in num-var.  Msg$ will be set to whatever message is issued by the command.


Special Notes:


The cmd-str expression is passed as a primary command to SPFLite


Within the cmd-str, all line references should be entered using the dotted prefix.  e.g.  the numeric values should be normal line pointers (in string format),  preceded by a dot.  Line 12 should be specified as .12 and not just 12.  


The dotted notation is referred to as "temporary line labels" or "line number pseudo-labels", since this notation is an extension to standard ISPF label syntax.  


See the section, "Line Labels: Temporary Line Labels, also known as Line-Number Pseudo Labels" in Working with Line Labels in the main Help documentation, for more information.


Because SPFLite primary commands do not deal with line pointers, any command expression string you create must contain line numbers and not line pointers.  If you are working with a line pointer, you must ensure that the line pointer is both valid and a pointer to a data line, and then convert that line pointer to a line number; otherwise the command you create will not work.  You can use the Is_Data function to confirm that a line pointer is valid and points to a data line, and Get_LNUM is used for the conversion.


For example, if you had a variable myLptr containing a valid line pointer value that points to a data line, and you wanted to build a DELETE command to delete that line, an SPF_CMD call to do that would look like this:


SPF_CMD("DELETE ." + TSTR$(Get_LNUM(myLptr)))


If you wish to use a Line Pointer directly, rather than convert it to a Line Number, you would use the ! exclamation-point notation instead of the . dot notation.  The same command above could be specified as


SPF_CMD("DELETE !" + TSTR$(myLptr))


to achieve the same thing.  This ! exclamation-point notation works only inside of macros, and only for the SPF_CMD function.  When you use this technique, you must be certain that the line pointer value used is for a data line and not for a special line.  Otherwise, the command passed to SPF_CMD will not be executed, and the function will return RC = 8.


Note:  Be aware of the difference between concatenating strings via macro syntax and concatenating strings using the multiple operand support in SPF_Cmd.


Example:

  SPF_Cmd("DELETE !" + TSTR(myLptr))

would generate a command of:

  DELETE !5


While:

  SPF_Cmd("DELETE !", TSTR(myLptr))

would generate a command of:

  DELETE ! 5


Note the 2nd version has added a blank separating the SPF_Cmd operands, which is NOT what is desired.




num-var = SPF_Debug(msg-str [,msg-str] ...)


Operands:

msg-str

the text string you wish displayed.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


Always RC = 0 and Msg$ = "" (null)


Special Notes:


During macro development, the SPF_Debug statement can be used to display information related to the macro execution.   This can be simple trace messages, or displays of internal variables.


Examples:


SPF_DEBUG ("Starting line loop")

SPF_DEBUG ("Var_b=" & TSTR$(Var_b))


The SPF_DEBUG statement will open a console window in which to display the information.





num-var = SPF_Exec([{SYNC|ASYNC},][{HIDDEN|NORMAL},]cmd-str [,cmd-str] ...)


Operands:

SYNC  |

ASYNC

This optional operand indicates how you want the command to run.   If SYNC is coded, control will not be returned to the macro until the command is complete.   If ASYNC is coded, the command will be issued and control immediately returned to the macro.



HIDDEN  |

NORMAL

This optional operand indicates whether you want the command to run in a visible window or not.   If HIDDEN is coded, no window will be seen.  (And if errors occur, they will not be visible either)  If NORMAL is coded, the command will run in a normally visible command window.



cmd-str

the command you wish executed.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


RC will be set to the return code from the executed function.  This value will also be returned in num-var.  Msg$ will be set to "" (null).


Special Notes:


Both SYNC|ASYNC and HIDDEN|NORMAL are optional operands, and if omitted, SYNC, NORMAL will be assumed.


NOTE: If you want to specify the HIDDEN|NORMAL operand, you MUST specify the SYNC|ASYNC operand as well, it can not be omitted.


The cmd-str string expression is passed as a program to be executed.  This operates similar to the SPF_Shell function, except that the command does not run under the command interpreter (CMD.EXE) but is executed directly.  The usual issues about locating the program using the current working directory and the system PATH variable apply to calls to SPF_EXEC.


Invoking programs to run under CMD.EXE can require complicated quoting and double quoting of operands when things like filenames with embedded blanks are required. With SPF_Exec only simple quoting is required, making the building of the string expression for the command much simpler.  The function SPF_Quote$ may be of assistance in creating properly quoted operand values.


Because such commands can perform powerful functions (such a deleting files), care should be taken to issue these commands correctly.



num-var = SPF_Exempt_File(file-ext)


Operands:

file-ext

This specifies a single file extension.  It may contain the leading period or no.


Returns:


RC=0 will be set if the extension is NOT in the 'exempt file' list,  RC=8 will be set if the extension IS in the 'exempt file' list.


Special Notes:


SPFLite maintains a list of file extension which are to be considered as non-text files.  For example this exempts these files from being searched by the FF (Find in Files) command. The list may be altered in the Options - File Manager options.


This function allows you to determine if a particular file is contained in this list.



num-var = SPF_INS(line-ptr, col-num, data-str)


Operands:

line-ptr

the line pointer for the data line to be modified



col-num

the column number at which the str-var contents are to be inserted.



data-str

the text string to be inserted


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:


Will insert str-var into the text of line-ptr at the indicated column col-num. Current text from col-num to the end of line will be shifted right to allow insertion of data-str.  If needed, the line's text will be extended with blanks to col-num - 1 before data-str is copied in.





num-var = SPF_Loop_Check(num-var)


Operands:

option-num

A numeric value that sets the state of the loop-checking option.  This should be TRUE or FALSE depending on setting desired.  You may also specify ON or OFF, or 1 or 0.


Returns:


The function will return the previous setting for Loop Check prior to establishing the new value.


RC is set to 0 and Msg$ = is set to "" (null)

Special Notes:


If your macro is going to perform some long running function, such as interfacing with the user by prompting, or any other long-running function, you should call this function to disable the normal SPFLite monitoring of macro execution.  


This will prevent SPFLite from popping up and informing you that the macro might possibly have gone into a loop.


Disabling the loop check should not normally be done during macro development and testing, but only after you are confident your macro is running properly.  If a macro does go into a loop after loop-checking is disabled, the only recourse is to cancel the entire SPFLite session.


When you issue any thinBasic function that causes a wait condition, such as the MsgBox function, SPFLite will detect a loop condition in progress, when in reality nothing is wrong.  To avoid such problems, you would disable loop checking before issuing a function call like MsgBox, and re-enable loop checking once MsgBox has completed.





num-var = SPF_OVR(line-ptr, col-num, data-str)


Operands:

line-ptr

the line pointer for the data line to be overlaid.



col-num

the column number at which the data-str contents are to be overlaid.



data-str

the new contents of the data line to be overlaid


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:


Will overlay text in line-ptr with data-str starting at the indicated column col-num. Other text in the line is unaffected.  If needed, the line's text will be extended with blanks to col-num - 1 before data-str is copied in.


The overlay operation consists of replacing characters from data-str into the same relative location in the line's text only when there are blanks in the original data.


Compare the functionality of SPF_OVR to the O/OO edit line commands.




num-var = SPF_OVR_REP(line-ptr, col-num, data-str)


Operands:

line-ptr

the line pointer for the data line to be overlaid.  Line-ptr is a normal Internal line pointer.



col-num

the column number at which the data-str contents are to be overlaid.



data-str

the new contents of data line to be overlaid


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:


Will overlay replace text in line-ptr with data-str starting at the indicated column col-num. Other text in the line is unaffected.  If needed, the line's text will be extended with blanks to col-num - 1 before data-str is copied in.


Overlay replace consists or replacing characters from data-str into the same relative location in the lines text only when the characters in data-str are non-blank.   i.e. similar to the previous SPF_OVR except here non-blanks in data-str take precedent over the original text.  In SPF_OVR, non-blanks in the original text take precedent.


Compare the functionality of SPF_OVR_REP to the OR/ORR edit line commands.




num-var = SPF_PARSE(TextLit-num, NumLit-Num, LinRef-num, TagOp-Num,

                   [ keyword-set, ]

                   [ keyword-set, ]

                   ... )


Operands:

TextLit-Num

Specifies the number of Text Literals allowed along with optional validation flags (see Special Notes below).  If no special options are provided, the value specifies the fixed number of this operand which must be entered.



NumLit-Num

Specifies the number of Numeric Literals allowed along with optional validation flags (see Special Notes below).  If no special options are provided, the value specifies the fixed number of this operand which must be entered.



LinRef-Num

Specifies the number of Line References allowed along with optional validation flags (see Special Notes below).  If no special options are provided, the value specifies the fixed number of this operand which must be entered.



TagOp-Num

Specifies the number of Tag Operands allowed along with optional validation flags (see Special Notes below).  If no special options are provided, the value specifies the fixed number of this operand which must be entered.



Keyword-set

Defines a set of allowable keywords.  The format of a Keyword set is:

"[list-name:]keyword,keyword,(kwalias,kwalias),keyword,..."


list-name

a name to refer to this set of keywords, to be used in the SPF_Arg_KWGroup function.


keyword

an allowable keyword.   If only one keyword is specified, it is treated as a 'present' or 'not present' keyword type.



keyword list

If multiple keywords are specified, they are treated as a set of mutually exclusive keywords.


alias list

if a keyword entry is a bracketed list of keywords, the bracketed list are treated as aliases of each other.  When retrieving information about these keywords, the left-most one in the bracketed list is treated as the preferred, normalized answer desired.




Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful parse where no errors are detected.


Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid operand, missing operand, etc.)


Special Notes:


A full discussion of using SPF_Parse will be found in Full Parse Access


Validation Flags


Validation flags, when used, are entered by adding then to the specified numeric value.  e.g. If 0 to 3 entries are desired, it would be entered as

3 + ARG_VAR

if these were tag entries which should be validated, it would be

3 + ARG_VAR + ARG_DEF


When none of the following flags are used, the number entered becomes the required number of that particular operand.


ARG_VAR     When this is specified, Parse will allow from 0 to the specified number to be entered.

ARG_OPT    When this is specified, Parse will allow either 0 or the exact specified number of operands

ARG_DEF    When this is specified, the Line Reference and Tag Operands are validated to ensure they are valid, defined references.







str-var = SPF_Quote$(data-str)


Operands:

data-str

a string value to be enclosed in quotes


Returns:


the value of data-str enclosed in quotes


RC will be 0 and Msg$ will be "" (Null).


Special Notes:


The contents of data-str are examined.  


If data-str is already in the format of a string enclosed in properly-matched, valid SPFLite quote characters of any type (either " double quotes, ' single quotes, or ` accent quotes), and data-str does not contain inner quote characters as data values that are the same as the enclosing quote characters, the contents of the data-str expression are returned as-is without modification.


If data-str does not contain any " double quote characters as data characters, the function returns the value of data-str preceded and followed by " double quotes.

If data-str already contains " double quote characters as data characters, but does not contain any ' single quotes as data characters, the function returns the value of data-str preceded and followed by ' single quotes.

If data-str already contains " double quote and ' single quote characters as data characters, but does not contain any ` accent quotes as data characters, the function returns the value of data-str preceded and followed by ` accent quotes.



 


num-var = SPF_REP(line-ptr, col-num, data-str)


Operands:

line-ptr

the line pointer of the data line to be modified.



col-num

the column number at which the data-str contents are to be replaced.



data-str

the replacement text string


Returns:


Both num-var and RC will be 0 and Msg$ will be "" (Null) for successful completion

Both num-var and RC will be 8 and Msg$ set to an error message on failure (e.g. invalid line pointer)


Special Notes:


Will replace text in line-ptr with data-str starting at the indicated column col-num. Other text in the line is unaffected.  If needed, the line's text will be extended with blanks to col-num - 1 before data-str is copied in.


The replacement operation consists of replacing characters from data-str into the same relative location in the line's original text.




num-var = SPF_Shell([{SYNC|ASYNC},][{HIDDEN|NORMAL},]cmd-str [,cmd-str] ...)


Operands:

SYNC  |

ASYNC

This optional operand indicates how you want the command to run.   If SYNC is coded, control will not be returned to the macro until the command is complete.   If ASYNC is coded, the command will be issued and control immediately returned to the macro.



HIDDEN  |

NORMAL

This optional operand indicates whether you want the command to run in a visible window or not.   If HIDDEN is coded, no window will be seen.  (And if errors occur, they will not be visible either)  If NORMAL is coded, the command will run in a normally visible command window.



cmd-str

the command you wish executed by the CMD.EXE shell.  When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


RC will be set to the return code from the Shell function.  This value will also be returned in num-var.

Msg$ will be set to "" (null).


Special Notes:


Both SYNC|ASYNC and HIDDEN|NORMAL are optional operands, and if omitted, SYNC, NORMAL will be assumed.


NOTE: If you want to specify the HIDDEN|NORMAL operand, you MUST specify the SYNC|ASYNC operand as well, it can not be omitted.


The cmd-string expression is passed as a Windows system command to the Command Shell.   The command will be performed, and control returned.  RC will be set to the Errorlevel / Exit code issued by the specified command.  The function SPF_Quote$ may be of assistance in creating properly quoted operand values.


SPF_Shell can be used for entering Windows shell commands like DEL, MKDIR, RMDIR, etc.  

Because such commands can be powerful (including commands that may delete files), care should be taken to issue these commands correctly.





num-var = SPF_Trace(mode-num)


Operands:

mode-num

Mode may be ON, OFF or ERROR.  When ON, a debugging window will appear that shows a trace record for every SPFLite function called, including the parameters it was passed, its RC and any message text generated.  When ERROR, the debugging information will be recorded only when an SPFLite function is called that does not return an RC of 0.


Returns:


RC will be set 8 if you supply an invalid mode-num operand, otherwise RC will be 0.


Special Notes:


The SPF_Trace call is itself always traced, regardless of the old or new trace mode in effect.




str-var = SPF_UnQuote$(source-str)


Operands:

source-str

The string to be 'un-quoted'.  UnQuote$ will remove the outer quotes from a string, if it is indeed quoted.   Unquoted source strings are returned unchanged.


The outer quotes may be any of the standard SPFLite supported quotes.  i.e. Single quotes ' - Double quotes " or Back quotes `


Returns:


RC will always be 0 and Msg$ = "" (Null)


Special Notes:





Created with the Personal Edition of HelpNDoc: Free PDF documentation generator