Passing parameters between PB objects

I would like to share with you a small, but useful object (NVO) named nvuo_parm which helps in the very common task of passing parameters between application units (for example, between windows). It is extremely important for communication between objects to be easy for developers, type-safe (bugs-prone) and effective (quick), so nvuo_parm is a good candidate!

1. Save the file nvuo_parm.sru on your hard disk.
2. Import the saved file into one of the application's PBLs.

Passed parameters are added to the NVO using its public setter methods. The names of these methods are constructed by the pattern uf_set_{type} where {type} is a type identifier - one or two letters taken from the standard PB variables naming convention (like "s" for string, "i" for integer etc.). Each setter method has 2 arguments: the keyword (in fact, the "name" of the passed parameter - of course, its type is always string) and the value (its type depends on the {type}). The passed parameters are accepted by the destination object using public getter methods (uf_get_{type}) which has only one argument - the keyword - and returns the passed value (so, the getters return different types).

The following table lists all the public methods of nvuo_parm:

As you see, special getters and setters are used for for parameters of different types. This approach is type-safe, but if you prefere a generic solution (one getter and one setter for all data types) then use a class named n_parm (downloadable here) - the new, more lightweight version. It is more convenient in use but, unfortunately, not type-safe: compiler will not prevent you from getting an integer parameter into a string variable... But if that problem doesn't stop you (anyway, you will get a run-time error doing a unit test), that class is easier to use. It will not be mentioned anymore in the page you are currently reading.

Situation: we want to pass parameters from window A to window B. Write in window A (in a function which opens window B):

Open event of window B:

1. Parameter name can contain any characters including dashes and internal spaces (external spaces are Trim()med). So, the following names are the same: "first_name", " first_name", "first_name ", " first_name ", but the following are different: "first_name", "first name", "firstname".
   
   
2. Parameter name is NOT case-sensitive. For exmaple, "order_id", "ORDER_ID" and "Order_Id" are treated as the same parameter.
   
   
3. Parameter name is mandatory, it cannot be NULL or empty string.
   
   
4. Parameter value is NOT mandatory, it can be NULL or empty string.
   
   
5. Parameter names must be unique per data type. Subsequent call of uf_set_... with a same name overrides (replaces) the existing (old) parameter having that name and data type. Let's experiment:
   
   uf_set_i("today", 30) // parameter of type "integer" is created
uf_set_i("today", 31) // 30 is lost
li_day = uf_set_i("today") // li_day contains 31
uf_set_d("today", Today()) // absolute new parameter is created - this time of type "date"
li_day = uf_set_i("today") // li_day still contains 31
   
   
6. uf_get_... methods return NULL (for arrays - an array with zero upper bound) of the appropriate data type if the asked parameter doesn't exist (i.e. no parameter with that name has been ever added, or it was added and NULLified later - see the next remark).
   
   
7. To delete a parameter, simply override it sending NULL for the value (for an array send a zero upper bound array):
   
   int li_null
long ll_empty_arr[]

SetNull(li_null)
lnv_parm.uf_set_i("birth_year", li_null)
lnv_parm.uf_set_a("departments", ll_empty_arr)
   
   
8. The class is autoinstantiated - no CREATEs and DESTROYs!
   
   
9. It's a good idea to create in n_parm public string constants for the names of parameters, widely passed in the application, and use them with both uf_add and uf_get instead of hard-coded names. For example, if your application deals a lot with invoices then you can create a constant INVOICE_NUM (keeping the value "invoice_num") and write
   
   lnv_parm.uf_set_l(lnv_parm.INVOICE_NUM, ll_invoice_num) // source object's script
   ...
   il_invoice_num = anv_parm.uf_get_l(lnv_parm.INVOICE_NUM) // target object's script
   
   instead of
   
   lnv_parm.uf_set_l("invoice_num", ll_invoice_num) // source object's script
   ...
   il_invoice_num = anv_parm.uf_get_l("invoice_num") // target object's script
   
   So, there never will be a situation when a source sets "invoice_num" but a target tries to obtain "inv_num", "invoice_number", "invoice_id" or whatever else. To know more about NVOs, created especially for constants, read here.
   
   
10. The maximum quantity of passed parameters of each type is 65535 (the max. value of uint). So, you can pass up to 65535 integers, up to 65535 booleans etc. There is no chance it will be not enough in a real-life application, so the object doesn't check overflow (it would downgrade performance).
    
    
11. A transported parameter itself can be of type n_parm, so you can pass nested constructions of any depth.
    
    
12. Methods for passing parameters of types any (uf_..._a), GraphicObject (uf_..._go) and NonVisualObject (uf_..._nv) are NOT type safe - on types mismatch you will get a run-time failure instead of a compilation error. If the passed parameter is not really of the functions' type (any, GraphicObject or NonVisualObject accordingly) then two conversions between data types are required. So, don't use them for types having their own setter/getter even if it is possible technically:
    
    
    • Don't use uf_..._a methods to pass strings, integers, user objects etc. - use them only to transport parameters, physically having datatype "any", and also for arrays and structures.
    • Don't use uf_..._go methods to pass Windows and DataWindows (these types have their own setters and getters).
    • Don't use uf_..._nv methods to pass DataStores (by the same reason).
      
      
13. You can add to nvuo_parm your own uf_set_... and uf_get_... functions for other classes if their objects are passed intensively in your application. It will make development more type-secure!
    
    
14. A passed parameter may be itself of the type nvuo_parm, so you can pass nested constructions of any depth. For example, you can pack into one nvuo_parm data for one worker (first and last names, array of departments he has worked etc.), and create an array of such workers to be passed in the outer (main) nvuo_parm.