Introduction


The SPFLite macro language provides for the storage and retrievel of numeric and string values in a Global manner.  That is, the data is stored in a single data area associated with a single SPFLite Instance. The data is shared by all active Edit tabs (and the FM tab) and is only freed when the whole SPFLite window is terminated.


Thus, a macro (or multiple co-operating macros) can pass data between separate Edit tabs and/or separate invocations of the macros. Think of it as a sort of ‘scratch-pad’ of data, available throughout all SPFLite macros.


Storage Structure


Tables


Global data is saved in tables which are identified by a table number.

This table number is optional. If no table number is specified, SPFlite will use table number 0.  


You may use any numbers you choose, they do not have to be consecutive, and all table numbers are treated equally.


There is no limit to the number of tables, the range of numbers used, or the total amount of data stored (well, limited by available memory)



Entries


Each entry in a table consists of a  'Name' and 'Value' pair.

Entries are organised according to the data type of the 'value' being stored.


Use the ...Gbl_Num... functions to manipulate numeric 'value' entries and the ...Gbl_Str... functions to manipulate string 'value' entries.


There are two complete sets of functions, whose only difference is the type of data being stored.


The available functions are:

Numeric values

String Values

Set_Gbl_Num

Set_Gbl_Str

Get_Gbl_Num

Get_Gbl_Str$

Get_Gbl_Num_Count

Get_Gbl_Str_Count

Get_Gbl_Num_Name$

Get_Gbl_Str_Name$

Get_Gbl_Num_TableName$

Get_Gbl_Str_TableName$

Delete_Gbl_Num

Delete_Gbl_Str



Storing and Retrieving data in Global Storage


Storing


   Set_Gbl_Num([Table-Num,],Name,Value)  is used to create/replace a numeric 'value' entry

   Set_GBL_Str([Table-Num,],Name,Value)   is used to create/replace a string 'value' entry


Both functions accept the following operands:


Table-Num

Optional

If specified, it must be the first operand. If omitted, table number 0 is assumed.

Name

Required String

This is a Name to identify the 'value' to be stored.

Value

Required String/Number

This is actual 'value' to be associated with the preceding Name.


Retrieving


   variable = Get_Gbl_Num([Table-Num,],Name)  is used to retrieve  a numeric 'value' entry

   variable = Get_Gbl_Str([Table-Num,],Name)   is used to retrieve  a string 'value' entry


Both functions accept the following operands:


variable

Required

The variable to receive the data value. The function can also be used directly as a macro numeric operand.

Table-Num

Optional

If specified, it must be the first operand. If omitted, table number 0 is assumed.

Name

Required String

This is a Name to identify the 'value' to be retrieved.


Removing / Deleting Table entries


Deleting an Individual Table Item


   Delete_Gbl_Num([Table-Num,],Name)  is used to delete a single numeric 'value' entry. i.e. a 'name' and 'value' pair.

   Delete_Gbl_Str([Table-Num,],Name)   is used to delete a single string 'value' entry. i.e. a 'name' and 'value' pair.


Both functions accept the following operands:

    

Table-Num

Optional

If specified, it must be the first operand. If omitted, table number 0 is assumed.

Name

Required String

This is a Name to identify the 'value' to be deleted.


Deleting an entire Table's Contents


   Reset_Gbl_Num([Table-Num])  is used to delete all numeric entries. i.e. 'name' and 'value' pairs from the specified table.

   Reset_Gbl_Str([Table-Num])   is used to delete all string entries. i.e. 'name' and 'value' pairs from the specified table.


Both functions accept the following operand:

    

Table-Num

Optional

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


           

Retrieving/Scanning All Data in a Table


Usually Gbl data is accessed directly using the table-number and the name. Retrieval of all items in a table is also possible. It is not, however, as straightforward as it might be. Accessing items in this way requires additional effort in the macro in order to enumerate the table-number and name fields with which to retrieve the stored information. Once these are known, data can be accessed using  the normal Get_Gbl_xxx functions.


The following three additional functions permit such enumeration.


   Get_Gbl_xxx_Count([Table-Num])  is used to fetch the current item count in the table

   Get_Gbl_xxx_Name$(Index-Num)  is used to fetch the Name for the entry specified by Index-Num.

   Get_Gbl_xxx_TableName$(Index-Num)  is used to fetch the table-num and Name for the entry specified by Index-Num.


Get_Gbl_xxx_Count([Table-num])


This returns the count of items in the table. If Table-Num is omitted, the count is for all items in all tables. If Table-Num is provided, the count is for that table.



Get_Gbl_xxx_Name$(Index-Num)


This will normally be used in a loop, from 1 to the # returned by Get_Gbl_xxx_Count.  It will return the name associated with that specific Index-Num.  The returned name can then be used in a Get_Gbl_xxx function to retrieve the actual data value.


Note: This returns the name regardless of the table in which it is found.  If the table number is significant, use the next function (Get_Gbl_TableName$).


Get_Gbl_xxx_TableName$(Index-Num)


This will normally be used in a loop, from 1 to the # returned by Get_Gbl_xxx_Count. It will return a string of format   Table-Num,name   associated with that specific Index-Num.  With the returned string in str-var, the table number is easily accessed vie VAL(str-var). Similarly, the Name value can be accessed via REMAIN$(str-var, ",") The returned value can be easily parsed into Table-Num and label-str. 


Note: This function provides the table-num and the name which allows you to select only items in a specific table-num.




Created with the Personal Edition of HelpNDoc: Effortlessly create a professional-quality documentation website with HelpNDoc