VarListCreatorPro ( VarType, VarName, VarValue, Mode )

Creates a variable by name or a the result of a calculation and can maintain a unique List.

Average rating: 4.3 (3 votes) Log in to vote

Joseph Arzate
IT Professional Consultants
http://itprofessionalconsultants.net

Sample input:

VarListCreatorPro ( "", "MyList", "Apple¶Orange", "")

Sample output:

Creates a GLOBAL Variable called "$$MyList" with values:

Apple
Orange

AND creates a second variable called "$$MyList.count" with the value:
2

Function definition: (Copy & paste into FileMaker's Edit Custom Function window)

/* INSTRUCTIONS / COMMENT / EXAMPLES - BEGIN
______________________________________________________________________
IT Professional Consultants Inc. 
www.itprofessionalconsultants.net
Author: Joseph Arzate (2.19.11) 
----------------------------------

Function: VarListCreatorPro ( VarType, VarName, VarValue, Mode)

*This is a recursive function. So long as you do not change it's name you should not have to modify any of the code below.

----------------------------------
[VarType] - Boolean value (0 or NULL for GLOBAL and 1 for SESSION). By Default "0" or NULL ("") value will instruct the function to create a Global ($$) variable. Sending a "1" will create a Session ($) variable.
[VarName] - The name you want the variable to be called. You must comply with FM existing variable naming convention and restrictions. No special characters.
[VarValue] - The value you want to add/remove to the variable. Send it a "List" of values separated by ¶. 
[Mode] - List or Single/Replace value operation ("L" or NULL "" ) for unique List operation. "S" for single value, replacing the variable with the value submitted.  


CODE BEGIN - VarListCreatorPro ( VarType, VarName, VarValue, Mode) 
______________________________________________________________________
*/

Let( [ 
/* Let Function - BEGIN */

ListType= Case( Mode = "S" ; 1; 0 ) ;
/* Default operation will create a unique ¶ delimited List when "L" or NULL ("") is submitted. If you need the function set a single value use "S". */  

VarTypeString = Case( Vartype = 1 ; "$" ; "$$") ; 
/* Examine the type of variable to create, by default 0 or NULL will produce a Global variable if the value is 1 it will create a Session variable */

VariableName = VarTypeString & VarName;
/* Concatenates the variable type string and the name of the variable*/

ExistingValues= ValueCount ( Evaluate ( VarTypeString & VariableName) ) ; 
/* Counts the existing values of the variable */

VarValue = Trim(VarValue) ;
/* Case( ListType= 1; VarValue; not IsEmpty( VarValue); VarValue & Case( ExistingValues > 0 and Right( VarValue; 1 ) <> "¶"; "¶" )) ; */
/*Adds a ¶ to the end of the list if the list does not already have one.*/

ValueListCount = ValueCount( VarValue)  ; 
/*Counts the number of values being passed to the function. This is a recursive function and will continue to call itself until all values have been processed.*/

ValueWorking = GetValue( VarValue; 1 );
/*Processes the list with the first value and assembles the list in the order the Values where submitted. */

VarName = Substitute( VarName ; ["$"; ""]; ["+" ; ""];["-" ; ""] ;["*" ; ""];["/" ; ""];["&" ; ""];["=" ; ""];["≠" ; ""];["<" ; ""];[">" ; ""]; ["(";""];[",";""];[";";""];[")";""];["[";""] ;["]" ; ""];["\"" ; ""] ;["::" ; ""] ;
                                                 ["}" ; ""]; [" AND " ; ""] ; [" OR " ; ""]; [" XOR " ; ""]; [" NOT " ; ""]; ["^"; ""]  
                                    ) ;
/*Precautinary Step removes special characters from the name submitted. Does not take into account if the name begins with a digit or period, or has the same name as a function, parameter or keyword. The function will return "?" if the variable name results in a error and will produce and error message. */

ListValue= Case( Evaluate( VariableName ) = "?"; "ERROR Variable Name Invalid"; Evaluate( VariableName ) )  ; /* Error captures invalid variable names */
/* Declares and list the values in the Variable being created or modified. */  

ListCount = ValueCount( ListValue)  ; 
/* Declare the number of values in the Variable being created, if any. */  

FirstValue= GetValue(ListValue;1) ; 
/* Grabs first value of the list used later for comparison */

LastValue= GetValue(ListValue; ListCount ) ; 
/* Grabs last value of the list used later for comparison */

x= Quote( 
         Case( IsEmpty(VarValue); ""; 
              Case( ListType = 1 or listCount=0 ; VarValue  ; /* Session Global or first value in the list. Adds value without a carriage return */
                     Case( PatternCount ( ¶ & ListValue & ¶; ¶ & ValueWorking & ¶  ) = 0 ;  /*Check to see if value on the list. Padding "listvalue" variable ensure exact match found */
                               ListValue & ¶ & ValueWorking ;  /* Value not found Add the Value to the List. */
                            Case(  (FirstValue = ValueWorking) and (Listcount=1) ; Substitute( ListValue; Valueworking; "") ; /* Remove first and only value with NULL */ 
                                       (FirstValue =ValueWorking) and (ListCount > 1) ; Substitute( ListValue; Valueworking & ¶ ; "" ) ;  /*Remove first vlaue from a list that contains > than 1 value  */
                                       (LastValue = ValueWorking) and (ListCount >1) ; Substitute( ListValue; ¶ & Valueworking ; "" ) ;  /* Remove last value from a list that contains > 1 value*/ 
                                       Substitute ( ListValue ; ¶ & ValueWorking & ¶ ; ¶ ) /*Remove value from the middle of the list */
                                    )   
                             )
                      )
                )
             );
/* When the VarValue submitted is empty, clears the list; when the value being worked exists, it removes it from the list; when value does not exist, adds it to the list */  

ListCount= ValueCount ( Evaluate(x) ) ; 
/* Counts the number of values in the newly created list. Used by second variable created to display the number of values in the list */ 

VarValue = Case( ListType= 1 ; "" ; RightValues( VarValue; ValueListCount - 1 ))
/* Filters the list to remove the value already evaluated. If optional parameter 'Replace' sent then were done, clear the list.*/

];
/* End Declare Variables */

Evaluate( "Let ( [" & VariableName & "=" & x  & "];" & VariableName & " )" ) & 
Evaluate( "Let ( [" & VariableName & ".count=" &  ListCount  & "];" & VariableName & ".count)" )  & 
/* Create Variables */

Case( ValueCount(VarValue) >0 ; VarListCreatorPro (  VarType; VarName ; VarValue ; Mode )  )
/* Recursive function call to process remaining items in the list if any. */

)
/* Let Function - END */

/*
______________________________________________________________________
 CODE - END: VarListCreatorPro( VarType; VarName ; VarValue ; Mode )  

 */

INSTRUCTIONS / COMMENT / EXAMPLES - BEGIN
______________________________________________________________________
IT Professional Consultants Inc.
www.itprofessionalconsultants.net
Author: Joseph Arzate (2.19.11)
----------------------------------

Function: VarListCreatorPro ( VarType, VarName, VarValue, Mode)

----------------------------------
[VarType] - Boolean value (0 or NULL for GLOBAL and 1 for SESSION). By Default "0" or NULL ("") value will instruct the function to create a Global ($$) variable. Sending a "1" will create a Session ($) variable.
[VarName] - The name you want the variable to be called. You must comply with FM existing variable naming convention and restrictions. No special characters.
[VarValue] - The value you want to add/remove to the variable. Send it a "List" of values separated by ¶.
[Mode] - List or Single/Replace value operation ("L" or NULL "" ) for unique List operation. "S" for single value, replacing the variable with the value submitted.

----------------------------------

Function Result 1: Adds/Removes/Replaces a value for the purpose to create/modify a Session or Global variable list or single value, using a text value provided. Multiple values can be sent at once using the FM functions such as "List" or "ValueList". Can be used anywhere a calculation can be defined.

Function Result 2: Creates a variable affixed with ".count" that will display the number of values in that variable list.

----------------------------------

Why: Needed an easy way to create and manage session and global variables as a list with a name as a result of a calculation. You can create variables using native FileMaker function values as the variable names, which will make the code portable. For example you can use the Get(CurrentLayoutName) as your variable name.

The function can operate with NULL value ("") for parameters, as a default mode operation. Examples below will display the use of this default operation as "Syntax1 [Alternate]"

----------------------------------
DESCRIPTION :
This custom function can create a session or global variable by name. FM only allows a variable name to be defined by hard coding it's name (as of FM16). When you call this function for the first time, it will create two variables. One is the value you sent to it and the second variable with a count of the number of values in the list. When you call this function to an already existing variable that contains a list of values, it will analyze the values you are sending to it and compare it to the existing values. If the value already exists it removes the value, if it's not on the list, it adds to it. It's main purpose was to store a List of values to a custom variable name and to facilitate the use of the "LIST" function FM Pro provides to add and remove values. However, it can also be used to store values using standard FM functions. This function helps promote modular "Portable" code.

Advance Description: You can use this function to create a variable by the result of a calculation, so long as the variable value name does not contain an illegal character. You can send the function a list of values and the function will add / remove any existing values, thus, maintaining a custom unique list. The function creates a second variable with ".count" as it's name with number of values the variable contains.

----------------------------------
How to call it in a script:

Use the "Set Variable" script step and name it whatever you want, I usually use "$Temp". Enter the function in the "Value" and once you call it you will end up with a Global or Session based variable with the values you sent to it.

-----------------------------------
Examples
-----------------------------------
Example A - Global List Variable:
Syntax1: VarListCreatorPro ( 0 , "MyList" , "Apple¶Oranges", "L" )
Syntax1 [Alternate]: VarListCreatorPro ( "" , "MyList" , "Apple¶Oranges", "" )
Result1: Creates a Global variable "$$MyList" and appends to the list the value "Apple¶Oranges", if the value already exists in the "$$List" variable the function will remove "Apple" from the list.
Result2: Creates a Global variable "$$MyList.count" with the number of values that exist in "$$MyList". Will return "2" if two values are on the list.

Example A.2 - Global unique LIST Variable:
Syntax1: VarListCreatorPro ( 0, "List" , "1¶2¶3", "L")
Syntax1 [Alternate]: VarListCreatorPro ( "" , "List" , "1¶2¶3", "")
Result1:Creates a Global variable "$$List" with the value "1¶2¶3", if any of the values already existed in the "$$List" variable the function will remove the matching numbers from the list.
Result2: Creates a Global variable "$$List.count" with a value of "3".

Example B - Global replace Value Variable:
Syntax: VarListCreatorPro ( 0 , "List" , "ABC", "S")
Syntax1 [Alternate]: VarListCreatorPro ( "" , "List" , "ABC", "S")
Result1:Creates a Global variable "$$List" with the value "ABC" and replaces any value that may existed in the variable.
Result2: Creates a Global variable "$$List.count" with a value of "1".
NOTE: For Single value or Replace operations you must specify the "S" parameter or else the function will attempt to maintain a unique list.

Example C - Session List Variable (same as Example A, except it's a Session variable [$] vs Global [$$] ):
Syntax1: VarListCreatorPro ( 1, "List", "Orange", "L")
Syntax1 [Alternate]: VarListCreatorPro ( 1, "List", "Orange", "")
Result1: Creates a Session variable named "$List" and will append the value "Orange" to the list. If the value "Orange" already exists in "$List" the function will remove "Orange" from the list.
Result2: Creates a Session variable "$$List.count" with a value of "1" when "Orange" is the only value in the variable.

Example D - Session Single Value Variable:
Syntax: VarListCreatorPro ( 1, "List", "Orange¶Apple", "S")
Syntax1 [Alternate]: None. You must use the "1" for a Session variable and you must use "S" to use replace the variable with the value your sending it.
Result1: Creates a Session variable named "$List" and will replace the variable with the value "Orange¶Apple" and replaces any value that may existed in the variable.
Result2: Creates a Global variable "$List.count" with a value of "2" when "Orange" is the only value in the variable.

Example E - Session List Value Variable:
Syntax: VarListCreatorPro (1, "List", "Grape¶Orange", "L")
Syntax1 [Alternate]: VarListCreatorPro (1, "List", "Grape¶Orange", "")
Result1: Replaces the value of a global variable with the value "Grape¶Orange". Any existing value in this variable will be replaced by the value sent to it.
Result2: Creates a Global variable "$$List.count" with a value of "2" when "Grape¶Orange" are the values in the variable.

Example F - Clear Variable:
Syntax1: VarListCreatorPro ( 0 , "List", "" , "" )
Syntax1 [Alternate]: VarListCreatorPro ( "" , "List", "" , "" )
Result: Erases the values in the Global variable named "$$List"
Result2: Creates a Global variable named "$$List.count" with a value of 0.

Special Note: This is a very powerful function that can promote 'Modular' portable scripting, if this function has saved you time or made your life easier in your commercial solution and you wish to make a donation feel free to send to PayPal: itpc.josepha@gmail.com :) - Enjoy!

Comments

Note: these functions are not guaranteed or supported by BrianDunning.com. Please contact the individual developer with any questions or problems.

VarListCreatorPro ( VarType, VarName, VarValue, Mode )

Comments

Support this website.

Support this website.