Function Overview

This section provides an overview of the various interface functions and their usage.  For full details of syntax, allowed parameters, return values etc. click on the  Function Name on the left to switch to the detailed description for the function.



Understanding SPFLite status values


A macro you run from your edit session, by placing a macro name on the primary command line, or on the sequence area of a data line, will return a status when it completes.  A status consists of two values: a numeric Return Code value (often referred to as RC), and a Message string.  This status is displayed on the upper-right portion of the edit screen, in the form of the Message string, and an optional Warning or Error message prefix in case a non-zero Return Code has been set.


When you call an SPFLite-supplied interface function (such as Get_Line$), that function will also return a status.  You may retrieve this status using the functions Get_RC and Get_Msg$.


There are thus two sets of status information.  The status returned to you (as an edit user that executed a macro command) that is visible on the edit screen as a message is called the top-level status.  The status returned to a user-defined macro by a call to an SPFLite interface function is called the function-level status.


It it important to understand that the top-level status and the function-level status are completely different and separate values.  


This means that if you issue a call to Set_Msg(my_RC, my_Message) it will change the top-level status values for the RC and Message, but will not change the function-level values that are returned by Get_RC and Get_Msg$.  Another way to look at this is that the function-level status is "lower" than the top-level status, and that status values can go "up" (via Set_Msg) but cannot go "down".


Example:


DIM rc as NUMBER

DIM msg as STRING

' ... some macro code

Set_Msg (8, "user defined error occurred")

rc = Get_RC

msg = Get_Msg$

' at this point, rc = 0, and msg = "", not the values set by Set_Msg


The other key point to keep in mind is that SPFLite interface functions do not "communicate" the function-level RC and Message values between themselves.  So, if one SPFLite function set an RC value of 8, the next SPFLite function you call will know nothing about that; it won't "look" at the RC=8 value set by the prior function call.  Each function "starts over from scratch" in terms of setting the function-level status values, by assuming each time that the RC will be 0 and the Message will be an empty (null) string, unless conditions require them to be changed.



Return codes and returned messages from SPF-supplied functions

All SPF-supplied functions set the function-level Return Code (RC) variable and the standard Message text appropriately based on the success of the function.  This is done in addition to providing the return value from the function directly.   In a few cases, the value returned by the function will be the RC value itself, but most functions will return values other than the RC.


Functions built into thinBasic do not set the RC and message values.  That only applies to functions we provide as part of the SPFLite macro interface.  So, if you call a thinBasic function like MID$ to get a substring of a value, that does not change the RC or message.


The function-level status values can be obtained with the Get_RC and Get_Msg$ functions.   A  successful return will usually result in RC=0 and a message text of "" (null).   However, some successful functions may result in a RC=0 but with a completed message text string.   For example, invoking an SPF_Cmd("QUERY EOL") function may result in a RC=0, but a Get_Msg$ return string of "EOL set to CRLF".


When a function returns a value which is not important to you, you can call it directly without assigning its returned value to a variable.  For example, you can call


       RC = SPF_Exec("MyProgram")


but if the return code isn't important, you can shorten this to:


       SPF_Exec("MyProgram")


Return codes and returned messages from Set_Msg to the edit user

The function Set_Msg is used to pass back a top-level return code and message to the edit user (you) that is displayed in the upper-right corner of the edit screen.  


It is important to understand that function-level 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 top-level status message to be displayed back to the user once the macro completes execution.


The values set by Set_Msg will be overridden by any other subsequent call to Set_Msg.  If you call this function more than once, only the RC and Message of the last call will be used as the top-level status, and displayed on the edit screen when the macro completes.


If you execute a macro that never calls Set_Msg, it is treated the same as if Set_Msg(0,"") were called; that is, no message will appear on the edit screen when the macro completes.


Supposing you wanted to "pass along" the function-level status values up to the top-level status after an SPFLite function call, it would require you to call the Set_Msg function.  If you did this, the call would take the form Set_Msg(Get_RC, Get_Msg$).


Example:


SPF_Cmd ("LINE 'R5' .1234")

Set_Msg (Get_RC, Get_Msg$)

' at this point, the visible top-level RC and Message are

' set to the status returned by the SPF_Cmd function call



List of available macro functions


The functions here are divided by categories of interest, for ease of lookup.



Functions that manage macro invocation and arguments


Get_Arg$(n)

Get_Arg$(f,n)

Returns a specified macro operand number n,   or a range of operand numbers separated by single blanks.

Get_Arg_Count

Returns the number of supplied macro arguments.  


Get_MacName$

Returns the name of the current macro


SPF_Parse

Performs full operand parsing of command operands


Get_Arg_KW

Returns True/False based on a Keywords presence in the macro command line


Get_Arg_KWGroup$

Returns the entered keyword fro a list of mutually exclusive items


Get_Arg_LRef$(n)

Returns the requested relative Line Reference from the macro command line


Get_Arg_Tag$(n)

Returns the requested relative Tag Operand from the macro command line


Get_Arg_TextLit$(n)

Returns the requested relative Text Literal from the macro command line


Get_Arg_NumLit$(n)

Returns the requested relative Numeric Literal from the macro command line


SPF_Quote$

Returns a string value properly enclosed in quotes


SPF_UnQuote$

Returns a string value with any existing paired outer quotes removed.


Get_FullPath$(file-name)

Returns a fully qualified path for a filename.


Is_Line_Cmd

Returns TRUE if macro launched as a line-command macro, otherwise FALSE


Is_Primary_Cmd

Returns TRUE if macro launched as a primary-command macro, otherwise FALSE


Set_Msg([rc-num,] msg-str)

Sets the visible (top-level) return code and message that is returned to the user


Halt([rc-num,] msg-str)

Sets the visible (top-level) return code and message that is returned to the user and then immediately terminates the macro



Functions that manage environment and SET variables


Get_EnvVar$(env-var-str)

Returns the specified Windows Environment Variable data.


Get_SETVar$(set-var-str)

Returns the specified variable value from the SPFLite SET variable pool.

Set_SETVar(set-var-str, value-str)

Sets the specified variable value in the SPFLite SET variable pool.


         

Functions that manage the Edit file


Get_FilePath$

Returns the current file path for the current file.


Get_FileBase$

Returns the base filename of the current edit file.


Get_FileName$

Returns the filename of the current edit file.


Get_FileExt$

Returns the current file extension.


Get_FileDate$

Returns the last modified date of the current file.


Get_FileTime$

Returns the last modified time of the current file.


Get_First_LPtr

Returns a Line Pointer to the first line of the Edit session


Get_Last_LPtr

Returns a Line Pointer to the last line of the Edit session


Get_Select_First_LPtr

Returns a Line Pointer to the first line of a selected text block


Get_Select_Last_LPtr

Returns a Line Pointer to the last line of a selected text block


Get_Select_Col

Returns a number indicating the leftmost selected column


Get_Select_Len

Returns a number indicating the length of the selected data


Get_Profile$

Return a PROFILE setting as a string.



Functions that manage the Edit session


Get_RC

Contains the Return Code from the last executed SPFLite function call.


Get_Msg$

Contains the text of the message issued by the last executed SPFLite function call


Set_Csr(line-ptr,col-num

   [, len-num])

Set the desired location for the cursor following macro execution.



Get_Csr_Col

Returns the column number of the current cursor line


Get_Csr_LPtr

Returns the line pointer of the line containing the cursor


Get_TopScrn_LPtr

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


Set_TopScrn_LPtr

Sets the line pointer which is to appear at the top of screen on macro exit.


Get_Curr_Line$

Returns the contents of the data line where the cursor was located at the start of macro processing


Get_Curr_Word$

Returns the contents of the current 'word' where the cursor was located at the start of macro processing


Get_Curr_Path$

Returns the full path of the Windows current working directory


Get_EXE_Path$

Returns the full path of the folder where SPFLite.EXE resides.


Get_INI_Path$

Returns the full path of the SPFLite data storage folder.


Get_LBound

Returns the current Left bounds value.


Get_RBound

Returns the current Right bounds value


Get_Modified

Returns the current file modified status as TRUE or FALSE.


Get_Modified_Filename

Returns the modified status for an individual file within an MEdit session


Get_Session_Type$

Returns a string containing the 'type' of the current edit tab.


Get_Uniq_ID

Returns a unique ID number that identifies this particular edit session.



Functions that manage Edit text data


Get_Line$(line-ptr)

Returns the current Edit text data for the specified line-ptr


Get_Clr_Line$(line-ptr)

Returns the current color control line for the specified line-ptr


Get_Line_Len(line-ptr)

Returns the length of the current Edit text data for the specified line-ptr


Get_Line_Type$(line-ptr)

Returns a text string indicating the particular line type


Get_XLines(line-ptr)

Returns the number of Excluded lines in an Exclude block


Get_XStatus$(line-ptr)

Returns an X/NX string value indicating the Exclude status of a data line


IS_xxxx(line-ptr)

Tests if a specific line (line-ptr) is a particular line type


Set_Line(line-ptr, data-str)

Will replace the current Edit text data for the specified line-ptr with the new string specified by data-str


Set_Clr_Line(line-ptr, clr-str)

Will replace the current color control string for the specified line-ptr with the new string specified by clr-str


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

Will insert StrVar into the text of line-ptr at the indicated column col-num


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

Will replace text in line-ptr with StrVar starting at the indicated column col-num


SPF_OVR(line-ptr,col-num,StrVar)

Will overlay text in line-ptr with StrVar starting at the indicated column col-num


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

Will overlay replace text in line-ptr with StrVar starting at the indicated column col-num


Get_Next_LPtr(line-ptr, adjust-amount, line-type)

Will adjust a line-pointer by moving it either forward or backward a specified number of lines of a specified line type.


Get_LPtr(line-ref)

Convert an external line reference to a line pointer


Get_LNum(line-ptr)

Convert a line pointer to an external line number


Get_Uniq_ID

Return a unique ID for this particular edit session.


SPF_Exempt_File(file-ext)

Test if a file extension is in the Text-Exempt list



Functions that manage FIND and LOCATE commands


Get_LOC_LPtr

Returns the line pointer of the last line found by the LOCATE command


Get_FIND_LPtr

Returns the line pointer of the last line found by a FIND / CHANGE command


Get_FIND_Col

Returns the column number where the last FIND / CHANGE was located


Get_FIND_Len

Returns the length of the last FIND / CHANGE search argument




Functions that manage line command operands


Label and Tag functions:


Get_Label$

Returns the .LABEL for a given data line


Get_Tag$

Returns the :TAG for a given data line


Release_Label$

Releases a label obtained via the Request_Label$ function


Request_Label$

Returns a label for a data line, creating a temporary one if needed


Source line-range functions:


Get_Src_LCmd$

Returns a string containing the name of the source line command.


Get_Src1_Lptr

Returns the line pointer of the last line in the source line range, or 0 if not applicable.


Get_Src2_Lptr

Returns the line pointer of the last line in the source line range, or 0 if not applicable.


Get_Src_Op

Returns the optional n value on the source line range.


Get_Src_LMOD$

Returns the source line command modifiers.


Destination line-range functions:


Get_Dest_LCmd$

Returns a string containing the name of the source line command.


Get_Dest1_Lptr

Returns the line pointer of the first line in the destination line range, or 0 if not applicable.


Get_Dest2_Lptr

Returns the line pointer of the last line in the destination line range, or 0 if not applicable.


Get_Dest_Op

Returns the optional n value on the destination line range command.


Get_Dest_LMOD$

Returns the destination line command modifiers.



Functions that manage globally-stored values


Set_Gbl_Num(key-str, value-num)

Stores the numeric value under the associated string key.


Set_Gbl_Str(key-str, value-str)

Stores the string value under the associated string key.


Get_Gbl_Num(key-str)

Retrieves the numeric value associated with key.


Get_Gbl_Str$(key-str)

Retrieves the string value associated with key.


Get_Gbl_Num_Count

Returns the current number of variables stored in the Numeric pool.


Get_Gbl_Str_Count

Returns the current number of variables stored in the String pool.


Get_Gbl_Num_Name$(index-num)

Returns the key name of the specified item in the Numeric pool.


Get_Gbl_Str_Name$(index-num)

Returns the key name of the specified item in the String pool.


Reset_Gbl_Num

Deletes the entire contents of the Gbl_Num storage area;  all Keys and Values are deleted


Reset_Gbl_Str

Deletes the entire contents of the Gbl_Str storage area;  all Keys and Values are deleted



Functions that manage external command execution


SPF_Cmd(cmd-str)

Execute the provided SPFLite primary command.


SPF_Shell(cmd-str)

Execute the provided command under the System's CMD.EXE command processor.


SPF_Exec(cmd-str)

Execute the provided command directly, not under the CMD.EXE command shell.



Functions that manage macro debugging


SPF_Debug(msg-str)

Display a message on the debugging console


SPF_Loop_Check(option-num)

Fetch and Set the SPFLite Macro loop monitoring function ON or OFF.


SPF_Trace(mode-num)

Set SPFLite trace mode to ON, OFF or ERROR


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