For various reasons, I wanted to automatically "stamp" all new items (top level or otherwise) with a unique serial number. This is similar to the well known method for stamping items with the date.
 
This was my excuse to finally delve into LUA scripts.
 
I thought I would share the method I created to perform this stamping function. I learned a lot from examples in this forum about eccoext and LUA while developing this method, and other eccoext enthusiasts may find my method a useful example of using LUA scripts in eccoext, whether or not they want the stamping function.
 
After learning the basic relationship between LUA and eccoext, may main stumbling block was how to maintain a variable representing the next serial number available for assignment to the next new item. I needed to maintain a LUA variable across ecco sessions in order to ensure unique serial numbers for all my items.
 
I considered keeping the variable in a file but chose instead to dedicate a single item in my ecco file to serve as a persistent and global LUA variable.
 
This item, which will have item text "LUA variables", will have one value in one folder per desired variable i.e. if I need 3 variables then this item will have values in 3 folders.
 
For my present application I only need one variable of type "number" and hence one folder of type "number" which I will call currSerialNbr. The folder value of the item will keep track of the next serial number that my LUA script will use when stamping new items. However this technique is useful to hold other variables, one per folder. The type of the variable can be number or checkmark or date just like the folder type.
 
My ecco file will have the following folders dedicated to serial number stamping:
 
currSerialNbr -- the next serial number available for use. This folder has only one item.  
serialNbr   -- the unique serial number for each item  
 
The auto-assign rule for folder serialNbr is:
 
++:L:assign_sn(item_id) -- calls a user-defined function which I defined in luacmd.lua.  
 
This function assigns the unique serial number if the item does not have one.
 
 
For debugging I also used this folder whose values display the ecco-assigned item_ID of each item:
 
myitemID of type "number"
 
and auto-assign rule:  
 
++:L:set_folder_value("myitemID",item_id,item_id)
 
This built-in LUA function puts item_id as value in folder myitemID for item item_ID.
 
 
I will be uploading an example file called auto_serial_nbr.eco and the required lua function defintion in luacmd.lua, but those are not really necessary as I have documented here all that is required.
 
I intend to document in the near future a couple of other stumbling blocks that I faced during this learning process in the hope that I might help others avoid them.
 
 
================================================================
 
 
The single function I defined  in luacmd.lua (this is the entire contents of the file) is:
 
function assign_sn(item_id)
 
-- I call this function in the auto-assignment rule of folder (of type Number) serialNbr of file auto_serial_nbr.eco
-- to assign unique serial numbers to items as they are created.
-- The single argument is the ecco-assigned item_ID that uniquely identifies the item within ecco.
-- The Flags that are normally used with auto-assign rules to determine when the rule is triggered do not work with LUA scripts.
-- Since I cannot use the flags,I will first test if the folder already has a value so I do not change an existing serial number.
 
 
-- ASSUMPTIONS:
-- the folder currSerialNbr (of type Number) has only one item (with item text LUA variable)
-- the value represents the next serial number available
 
 
-- my code below does not confirm these assumptions
 
 
-- find the item_id of the variable that holds the next serial number to be used
 
x = get_folder_items("currSerialNbr")  -- get the item_id of all items in folder. There should only be one item in the x array, and it must have a value.
SN=get_folder_value("currSerialNbr",x[1])  --  get the serial number to be used
 
 
 
if get_folder_value("serialNbr",item_id) ~=""  -- test if folder has a value (not empty).
 
     then  -- Don't change anything. Don't want to change existing serial numbers
     
     else
     
     set_folder_value("serialNbr",item_id, SN) -- assign serial number to current item
     
     set_folder_value("currSerialNbr",x[1],SN+1) -- update (increment) the current serial number
 
end  -- of If statement
 
 
end -- of function definition
 
 
 
 

Here is the luacmd.lua file

very nice.
 
note,
 
set_file_var(name, value)
     value must be string
 
get_file_var(name)
 
Use the above function you can store or load some information in you file, the value is persistent. You can only set at most 20 file variable, each variable can store at most 64K stuff.  
 
alternative way to store global variable,    but your own solution very elegant.
 
 
also note,  number folders have limit if about 10k  total items in single folder,
 
thus,
 
to make safe for 64k items,
 
use 6 folders.
 
place in folder based on value, eg.,  
 
ten thousands numeric value.   (ie., 23,302   = 2;  4,323 = 0;  323 = 0; 33,423 = 3)
 
use that as in  safefolder_X  with X being the item id number ten thousands numeric.
 
(hopefully this is clear enough).
 
 
that way you can assign serial number to 64k items,  not just 10k.
 
 
can use serial number ten thousands numeric,  and have more than 6 folders as file ages (ie., serial # will increase past 64k ).
 
 
folder column with subfolders is easy way to display the serial number.
 
 
 
----  
 
alternative approach is to remove the value in item with current serial number - 10,000.      will insure always that no more than 10k items with serials are active.
 
 
hope helpufl.
 

I have one more question related to this project.
Why does eccoext add the itemID folder? What is its intended purpose?