Synopsis: Programming With Modules and IndependentModules

Share icon

Fri, 08/06/2010 - 07:06 am

Here is a short synopsis of the aspects of ModuleName and IndependentModule designations. It summarizes the pros/cons of Modules/Independent Modules as well as the scope and methods of accessing functions within a Module or an Independent Module. In the table below, FNAME is the function name, MNAME is the module name, and IMNAME is the independent module name. Note that, without a #pragma IndependentModule designation, a procedure file is compiled in the ProcGlobal namespace. Otherwise, it is compiled in its own (IndependentModule) namespace. Without a #pragma ModuleName designation, a module is a General type. Otherwise, it is its own (Module) type. The Scope defines whether/how a given function (and its name) is seen from the outside. Cases where extra care will certainly be needed to avoid name conflicts with function names are designated with *. The call FNAME via designates how to reach a given function from outside the procedure, with NONE meaning, the function can never be called from outside the procedure (ie, it is "invisible"). This is also how you must call the procedure when it is an "action" procedure, such as one that is to be called from a panel control or as a hook, even if the call is made from a line of code within the same procedure file that contains the function.
































NameSpace: ProcGlobal

pros: all external calls possible, can use #include at the top of the procedure file

cons: possible conflicts with overlapping FNAME names, procedure file recompiles each time
Module TypeFunction TypeScopecall FNAME via
General
(no module)		* Non-Static
* Static		public
local		FNAME
NONE
Module* Non-Static
Static		public
semi-public		FNAME
MNAME#FNAME
NameSpace: IndependentModule

pros: limited (if any) conflicts with FNAME names, "crash-safe" (compiled only once when opened)

cons: external calls possible only via Execute, use of #include to been done with caveats
Module TypeFunction TypeScopecall FNAME via
General
(no module)		Non-Static
Static		semi-public
local		IMNAME#FNAME
NONE
ModuleNon-Static
Static		semi-public
semi-public		IMNAME#MNAME#FNAME
IMNAME#MNAME#FNAME




In summary:


  • If you write procedure files primarily for your own use, you likely need never use #pragma ModuleName or #pragma IndependentModule designations, otherwise

  • If you want to avoid name conflicts among functions in various procedure files (distributed or otherwise), either a) use #pragma ModuleName designations and static functions or b) use very well randomized function names, and

  • If you want to assure that your procedure file is reliably (if not perfectly) self-contained, use #pragma IndependentModule designations



Comments and updates are welcomed.
The summary's second point should read:

  • use #pragma ModuleName designations and static functions to avoid name conflicts in procedure files that you distribute to others, and


    • --Jim Prouty
    Software Engineer, WaveMetrics, Inc.

    August 6, 2010 at 04:51 pm - Permalink

    JimProuty wrote:
    The summary's second point should read:

  • use #pragma ModuleName designations and static functions to avoid name conflicts in procedure files that you distribute to others, and


    • Fixed. Thank you!

    --
    J. J. Weimer
    Chemistry / Chemical & Materials Engineering, UAHuntsville

    August 8, 2010 at 06:55 pm - Permalink