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("DCB ?") function may result in a RC=0, but a Get_Msg$ return string of "DCB set to RECFM=U, EOL=CRLF, LRECL=0".

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

With the introduction of macro support for File Manager, it meant a new series of functions were created to interface with File Manager. Obviously, if these functions are invoked by a macro running in a normal Edit session, they would not work. Similarly, many of the original functions designed for an Edit session will not function in the File Manager tab.

So we have three classes of functions:

Those that will work in all environments
Those that will work only in File Manager
Those that will work only in Edit sessions.

SPFLite will check for these conditions and terminate a macro which is using a function in the incorrect environment.

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

	Functions for handling command line arguments	FM	Edit
Get_Arg$(n) Get_Arg$(f,n)	Returns a specified macro operand number n, or a range of operand numbers separated by single blanks.	Yes	Yes
Get_Arg_Count	Returns the number of supplied macro arguments.	Yes	Yes
Get_MacName$	Returns the name of the current macro	Yes	Yes
Get_Primary_Cmd$	Returns the name of the last issued Primary command.	Yes	Yes
SPF_Parse	Performs full operand parsing of command operands	Yes	Yes
Get_Arg_KW	Returns True/False based on a Keywords presence in the macro command line	Yes	Yes
Get_Arg_KWGroup$	Returns the entered keyword from a list of mutually exclusive items	Yes	Yes
Get_Arg_LRef$(n)	Returns the requested relative Line Reference from the macro command line	Yes	Yes
Get_Arg_LRef_Count	Returns the number of Line Reference type macro operands.	Yes	Yes
Get_Arg_Tag$(n)	Returns the requested relative Tag Operand from the macro command line	Yes	Yes
Get_Arg_Tag_Count	Returns the number of Tag type macro operands.	Yes	Yes
Get_Arg_TextLit$(n)	Returns the requested relative Text Literal from the macro command line	Yes	Yes
Get_Arg_TextLit_Count	Returns the number of Text Literal type macro operands.	Yes	Yes
Get_Arg_NumLit$(n)	Returns the requested relative Numeric Literal from the macro command line	Yes	Yes
Get_Arg_NumLit_Count	Returns the number of Numeric Literal type macro operands.	Yes	Yes
SPF_Quote$	Returns a string value properly enclosed in quotes	Yes	Yes
SPF_UnQuote$	Returns a string value with any existing paired outer quotes removed.	Yes	Yes
SPF_InvChar$	Returns a string with invalid display characters 'cleaned up'	Yes	Yes
Get_FullPath$(file-name)	Returns a fully qualified path for a filename.	Yes	Yes
Is_Line_Cmd	Returns TRUE if macro launched as a line-command macro, otherwise FALSE	Yes	Yes
Is_Primary_Cmd	Returns TRUE if macro launched as a primary-command macro, otherwise FALSE	Yes	Yes
Is_FM	Returns TRUE if macro launched in the File Manager tab, otherwise FALSE.	Yes	Yes
Set_Msg([rc-num,] msg-str)	Sets the visible (top-level) return code and message that is returned to the user	Yes	Yes
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.	Yes	Yes
Get_RC	Contains the Return Code from the last executed SPFLite function call.	Yes	Yes
Get_Msg$	Contains the Return Code from the last executed SPFLite function call.	Yes	Yes
Get_EXE_Path$	Returns the full path of the folder where SPFLite.EXE resides.	Yes	Yes
Get_INI_Path$	Returns the full path of the SPFLite data storage folder.	Yes	Yes
SPF_Shell(cmd-str)	Execute the provided command under the System's CMD.EXE command processor.	Yes	Yes
SPF_Exec(cmd-str)	Execute the provided command directly, not under the CMD.EXE command shell.	Yes	Yes
SPF_Post_Do(Do-string)	Specify a standard DO macro string which will be executed immediately when this macro has terminated.	Yes	Yes
	Functions that manage globally-stored values	FM	Edit
Delete_Gbl_Num([Tblnum,] key-str)	Deletes a current item (key-str) from the specified table (Tblnum)	Yes	Yes
Delete_Gbl_Str([Tblnum,] key-str)	Deletes a current item (key-str) from the specified table (Tblnum)	Yes	Yes
Set_Gbl_Num([TblNum,]key-str, value-num)	Stores the numeric value under the associated string key.	Yes	Yes
Set_Gbl_Str([TblNum,]key-str, value-str )	Stores the string value under the associated string key.	Yes	Yes
Get_Gbl_Num([TblNum,]key -str )	Retrieves the numeric value associated with key.	Yes	Yes
Get_Gbl_Str$([TblNum,]key -str )	Retrieves the string value associated with key.	Yes	Yes
Get_Gbl_Num_Count([TblNum])	Returns the current number of variables stored in the Numeric pool.	Yes	Yes
Get_Gbl_Str_Count([TblNum])	Returns the current number of variables stored in the String pool.	Yes	Yes
Get_Gbl_Num_Name$(index-num )	Returns the key name of the specified item in the Numeric pool.	Yes	Yes
Get_Gbl_Num_TableName$(index-num )	Returns the Table-number and key name of the specified item in the Numeric pool.	Yes	Yes
Get_Gbl_Str_Name$(index-num )	Returns the key name of the specified item in the String pool.	Yes	Yes
Get_Gbl_Str_TableName$(index-num )	Returns the Table-number and key name of the specified item in the String pool.	Yes	Yes
Reset_Gbl_Num([TblNum])	Deletes the entire contents of the Gbl_Num storage area; all Keys and Values are deleted	Yes	Yes
Reset_Gbl_Str([TblNum])	Deletes the entire contents of the Gbl_Str storage area; all Keys and Values are deleted	Yes	Yes
	Functions that manage environment and SET variables	FM	Edit
Get_EnvVar$(env-var-str)	Returns the specified Windows Environment Variable data.	Yes	Yes
Get_Instance$	Returns the name of the Instance for the current SPFLite session.	Yes	Yes
Get_SETVar$(set-var-str )	Returns the specified variable value from the SPFLite SET variable pool.	Yes	Yes
Set_SETVar(set-var-str, value-str)	Sets the specified variable value in the SPFLite SET variable pool.	Yes	Yes
	Functions that manage macro debugging	FM	Edit
SPF_Debug(msg-str)	Display a message on the debugging console	Yes	Yes
SPF_Loop_Check(ON \| OFF)	Fetch and Set the SPFLite Macro loop monitoring function ON or OFF.	Yes	Yes
SPF_Trace(mode-num)	Set SPFLite trace mode to ON, OFF or ERROR	Yes	Yes
	Functions that manage the Edit file	FM	Edit
Get_FilePath$	Returns the current file path for the current file.	No	Yes
Get_FileBase$	Returns the base filename of the current edit file.	No	Yes
Get_FileName$	Returns the filename of the current edit file.	No	Yes
Get_FileExt$	Returns the current file extension.	No	Yes
Get_FileDate$	Returns the last modified date of the current file.	No	Yes
Get_FileTime$	Returns the last modified time of the current file.	No	Yes
Get_First_LPtr	Returns a Line Pointer to the first line of the Edit session	No	Yes
Get_Last_LPtr	Returns a Line Pointer to the last line of the Edit session	No	Yes
Get_Select_First_LPtr	Returns a Line Pointer to the first line of a selected text block	No	Yes
Get_Select_Last_LPtr	Returns a Line Pointer to the last line of a selected text block	No	Yes
Get_Select_Col	Returns a number indicating the leftmost selected column	No	Yes
Get_Select_Len	Returns a number indicating the length of the selected data	No	Yes
Get_EOL_STR$	Returns a string containing the EOL specified in the current Profile	No	Yes
Get_Profile$	Return a PROFILE setting as a string.	No	Yes
Get_MARKLine$	Returns NONE or the current MARK line contents	No	Yes
Get_BNDSLine$	Returns the current BNDS line.	No	Yes
Set_MARK	Sets a new value for the MARK line	No	Yes
Get_MASKLine$	Return the current MASK line contents	No	Yes
Set_MASK	Sets a new value for the MASK line	No	Yes
Get_TABSLine$	Return the current TABS line contents	No	Yes
Set_TABS	Sets a new value for the TABS line	No	Yes
Get_WordChar$	Return the current WORD line contents	No	Yes
Set_WORD	Sets a new value for the WORD line	No	Yes
	Functions that manage the Edit session	FM	Edit
Add_Array(line-ptr, array-name)	Adds all lines in an array to the edit session.	No	Yes
Add_Line(line-ptr, data-str)	Adds a new line to the edit following the line-ptr	No	Yes
Get_Uniq_ID	Returns a unique ID number that identifies this particular edit session.	No	Yes
Set_Csr(line-ptr,col-num [, len-num])	Set the desired location for the cursor following macro execution.	No	Yes
Get_Csr_Col	Returns the column number of the current cursor line	No	Yes
Get_Csr_LPtr	Returns the line pointer of the line containing the cursor	No	Yes
Get_TopScrn_LPtr	Returns the line pointer of the line which is currently at the top of screen.	No	Yes
Get_BottomScrn_LPtr	Returns the line pointer of the last datra line on the screen.	No	Yes
Get_LeftScrn_Col	Returns the column number of the Left side of the screen	No	Yes
Get_RightScrn_Col	Returns the column number of the Right side of the screen	No	Yes
Set_TopScrn_LPtr	Sets the line pointer which is to appear at the top of screen on macro exit.	No	Yes
Get_Trk_TrkID	Gets the unique Track-ID for a single LPtr	No	Yes
Get_Trk_LPtr	Gets the LPtr for a single Track-ID	No	Yes
Get_Trk_Pos$	Gets the positioning info from an entry in the Track stack.	No	Yes
Get_Curr_Line$	Returns the contents of the data line where the cursor was located at the start of macro processing	No	Yes
Get_Curr_Word$	Returns the contents of the current 'word' where the cursor was located at the start of macro processing	No	Yes
Get_Curr_Path$	Returns the full path of the Windows current working directory	No	Yes
Get_LBound	Returns the current Left bounds value.	No	Yes
Get_RBound	Returns the current Right bounds value	No	Yes
Get_Modified	Returns the current file modified status as TRUE or FALSE.	No	Yes
Get_Modified_Filename	Returns the modified status for an individual file within an MEdit session	No	Yes
Get_Session_Type$	Returns a string containing the 'type' of the current edit tab.	No	Yes
	Functions that manage Edit text data	FM	Edit
Get_ANSI2SOURCE_Table$ Get_SOURCE2ANSI_Table$	Returns a 256 byte string translate table to convert from ANSI to the current SOURCE format. Returns a 256 byte string translate table to convert from the current SOURCE format to ANSI.	Yes	Yes
Get_Line$(line-ptr)	Returns the current Edit text data for the specified line-ptr	No	Yes
Get_Clr_Line$(line-ptr)	Returns the current color control line for the specified line-ptr	No	Yes
Get_Line_Len(line-ptr)	Returns the length of the current Edit text data for the specified line-ptr	No	Yes
Get_Line_Type$(line-ptr)	Returns a text string indicating the particular line type	No	Yes
Get_XLines(line-ptr)	Returns the number of Excluded lines in an Exclude block	No	Yes
Get_XStatus$(line-ptr)	Returns an X/NX string value indicating the Exclude status of a data line	No	Yes
IS_xxxx(line-ptr)	Tests if a specific line (line-ptr) is a particular line type	No	Yes
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	No	Yes
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	No	Yes
SPF_INS(line-ptr,col-num,data-str)	Will insert StrVar into the text of line-ptr at the indicated column col-num	No	Yes
SPF_REP(line-ptr,col-num,data-str)	Will replace text in line-ptr with StrVar starting at the indicated column col-num	No	Yes
SPF_OVR(line-ptr,col-num,StrVar)	Will overlay text in line-ptr with StrVar starting at the indicated column col-num	No	Yes
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	No	Yes
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.	No	Yes
Get_LPtr(line-ref)	Convert an external line reference to a line pointer	No	Yes
Get_LNum(line-ptr)	Convert a line pointer to an external line number	No	Yes
SPF_Exempt_File(file-ext)	Test if a file extension is in the Text-Exempt list	No	Yes
SPF_Cmd(cmd-str)	Execute an Edit Primary command.	No	Yes
	Functions that manage FIND and LOCATE commands	FM	Edit
Get_LOC_LPtr	Returns the line pointer of the last line found by the LOCATE command	No	Yes
Get_FIND_LPtr	Returns the line pointer of the last line found by a FIND / CHANGE command	No	Yes
Get_FIND_Col	Returns the column number where the last FIND / CHANGE was located	No	Yes
Get_FIND_Len	Returns the length of the last FIND / CHANGE search argument	No	Yes
	Functions that manage line command operands	FM	Edit
Get_Handle$	Returns the .HANDLE for a given data line. Handles are only created by the Get-Handls$ function.	No	Yes
Drop_Handle$	Removes a previously assigned Handle	No	Yes
Has_Handle	Returns True / False as to whether a Handle exists for a line.	No	Yes
Get_Label$	Returns the .LABEL/HANDLE for a given data line. If a User created label exists it is selected first. If no User created label, the HANDLE is returned. If neither exist, a Null is returned.	No	Yes
First_Handle$ Last_Handle$	These functions return the current Lowest or Highest issues Handle for the file.	No	Yes
Next_Handle$ Prev_Handle$	These functions support looping through the assigned Handles. Each will return the Previous or Next Handle (in Handle issued sequence). A Null ("") is returned when no more exist in the specified direction	No	Yes
Get_Tag$	Returns the :TAG for a given data line	No	Yes
Get_Src_LCmd$	Returns a string containing the name of the source line command.	No	Yes
Get_Src1_Lptr	Returns the line pointer of the last line in the source line range, or 0 if not applicable.	No	Yes
Get_Src2_Lptr	Returns the line pointer of the last line in the source line range, or 0 if not applicable.	No	Yes
Get_Src_Op	Returns the optional n value on the source line range.	No	Yes
Get_Src_LMOD$	Returns the source line command modifiers.	No	Yes
Get_Dest_LCmd$	Returns a string containing the name of the source line command.	No	Yes
Get_Dest1_Lptr	Returns the line pointer of the first line in the destination line range, or 0 if not applicable.	No	Yes
Get_Dest2_Lptr	Returns the line pointer of the last line in the destination line range, or 0 if not applicable.	No	Yes
Get_Dest_Op	Returns the optional n value on the destination line range command.	No	Yes
Get_Dest_LMOD$	Returns the destination line command modifiers.	No	Yes
	Functions that retrieve File Manager Overall Data	FM	Edit
FMGet_Mode	Returns the general Mode of the File Manager display.	Yes	No
FMGet_FilePath$	Returns the contents of the File Path field - EVEN IF the display is not in FilePath mode.	Yes	No
FMGet_FilePattern$	Returns the current File Pattern mask - EVEN IF the display is not in FilePath mode.	Yes	No
FMGet_FListName$	Returns the current FLIST name being displayed. If in FilePath mode, Null is returned.	Yes	No
FMGet_FCount	Returns the current number of line of file data being displayed.	Yes	No
FMGet_Folder_Class({pathname})	Returns the Backup / Normal class of the folder. If a Pathname provided, it returns the status of that folder. If no Pathname, and in FilePath mode, returns the status of the current FilePath.	Yes	No
	Functions that retrieve File Manager Individual File Line Items	Fm	Edit
FMGet_AbbrevName$(FNum, length)	Returns an abbreviated version of the Filename. Useful when a long filename might cause formatting problems when including the filename in messages. The length parameter allows you to specify the desired length.	Yes	No
FMGet_Attr$	Returns a short string of 1 character designations representing the file attributes
FMGet_Backup_Versions(FNum)	Returns the available # of Backup versions for the specified file at line number FNum.	Yes	No
FMGet_Cmd$(FNum)	Returns the current contents of the Line command area for the specified file at line number FNum.	Yes	No
FMGet_Extension$(FNum)	Returns the file extension (including the period) for the specified file at line number FNum.	Yes	No
FMGet_FileAttributes(FNum)	Returns the file attribute area for the specified file at line number FNum. This is a binary DWORD of bit flags describing the type of file system entry.	Yes	No
FMGet_File_Class(FNum)	Returns the general file class for the specified file at line number FNum. The Class is one of: a normal file; a Backup of a data file; or a Backup of an associated STATE file.	Yes	No
FMGet_FileName$(FNum)	Returns the filename for the specified file at line number FNum.	Yes	No
FMGet_FileSize(FNum)	Returns the size of the file specified at line number FNum. The value is returned as a QUAD integer	Yes	No
FMGet_FileSize$(FNum)	Returns the size of the file specified at line number FNum. The value is returned as a formatted string value. e.g. 9,999,999.	Yes	No
FMGet_FType(FNum)	Returns the type of File Manager entry for the line specified by FNum. e.g. Directory folder (Up or Down), file, FLIST entry etc.	Yes	No
FMGet_Lines(FNum)	Returns the number of Lines in the file (if available) for the file specified at line number FNum. If the Lines value is not available, -1 will be returned	Yes	No
FMGet_Note$(FNum)	Returns the contents of the Note field (if available) for the file specified at line number FNum. If the Note field is not available, a Null is returned.	Yes	No
FMGet_Path$(FNum)	Returns the Path to the file (including the trailing \) for the file specified at line number FNum.	Yes	No
FMGet_PRPn$	Returns the extended property selected by the PRPn column specification
FMGet_CreationTime$(FNum)	Returns the Creation time for the file specified at line number FNum. The format returned is: yyyy-mm-dd hh:mm	Yes	No
FMGet_LastWriteTime$(FNum)	Returns the Last Write time for the file specified at line number FNum. The format returned is: yyyy-mm-dd hh:mm	Yes	No
	Functions that Act on or modify the File Manager Environment	FM	Edit
SPF_FMLCmd(FNum, cmd-string)	Execute a normal FM line command against a specified file at line number FNum. See the Function details for the supported line commands.	Yes	No
FMSet_Cmd(FNum, string)	Modify the line command field for a specified file at line number FNum.	Yes	No
FMSet_Msg(FNum, string)	Issue a message to temporarily overlay the filename for a file line specified by FNum.	Yes	No

Created with the Personal Edition of HelpNDoc: Ensure High-Quality Documentation with HelpNDoc's Hyperlink and Library Item Reports