Experimental Physics and
Industrial Control System

Andrew Johnson <[email protected]> · Fri, 16 Dec 2005 16:59:45 -0600

Rees, NP (Nick) wrote:

Part of the problems we experience is due to the confusion about what is
happening at the
template interface. In part, this is due to the conflict between
macros used as text substitution macros and macros used as port macros -
these are subtly different. If a port macro is not resolved then it
shouldn't be an error, I believe it should be treated as if it never
existed in the first place.

I strongly disagree. If a parent diagram is trying to use information

from a port that a template it's expanding doesn't actually define, then

the parent diagram is wrong and this should cause an error at

instantiation time.

If a text substitution macro is not resolved then it
should remain as the macro to be substituted at a later time.

That I might agree with, although I can see some people wanting the

other behaviour and I'm not sure how you'd indicate which you prefer.

This may be related: In about R3.14.6 we extended macLib so the macro

expansion syntax may also include a default value, in the form

$(name=value). The default is used if no macro by that name is found. I

suspect this syntax has not been introduced to VDCT yet, and I can see

that it would cause some complications if you're expecting an undefined

macro that has a default to remain as a macro in the instanciation -

maybe you never should.

I propose that we clarify this by declaring a port macro as such in
the template declaration. There are then two types of ports - ones
that take data in from above (which is done by string substitution)
and ones that pass data back.

I don't see the need for an additional declaration, and I don't agree

with the statement in your second sentance at all. VDCT should be able

to scan any template.vdb file and find all the macros it uses and the

ports that it defines.

The original spec says that ports make internal information from a

template available to the parent file, and macros pass information

downwards from the parent into the template instance. There is no such

thing as a port that passes information downwards; I deliberately used

the name 'port' in order to try and avoid confusion as to the direction

of the information flow.

As Benjamin said, the difference between a port and a macro is not

related to input vs output links - I think you already understand that.

While we are at it, I think it would
also be good to declare any string macros used in the template
statement as well. For example:

template() {
# The following creates a port that passes the string "t1" to an upper
level file.
  port( UP, "t1" )
# The following declares a port that, if defined in an upper level

diagram

          ^ Incomplete sentance

  portmacro( DOWN )
# The following declares a string substitution macro.
  macro( STRING )
}

I think I may be able to understand your language now, which was

actually rather confusing initially.

I can see why you might want to add descriptions to the macros that a

template.vdb uses; my objection is that they serve no purpose to the

template expansion code, and they could cause problems if a manually

edited template gets out of step with the actual macros used in the

file. I therefor think this kind of documentation belongs either in the

documentation for the template or in its comment text.

I don't like your idea of trying to separate out what you're calling a

"port macro" and a "string substitution macro" - I assume the latter is

intended for expansion only in a dbLoadRecords() statement. I don't

think you can make this kind of distinction though; in some cases the

template may have all its macros expanded on the host by a parent.vdb

file, and in others the same template parameters may be provided to

dbLoadRecords().

The template statement thus becomes an interface statement (a bit like
the record declaration in a dbd file) and not just means of passing

information up. As such, it should also be possible to attach metadata

to it (such as a description field).

As I said above, macro and other descriptions can be provided by VDCT,

but they are not needed to expand the template hierarchy so they

shouldn't be part of the basic syntax.

If you open an existing hierarchy the tool should always check the
interfaces for consistency - validating the expand statements against
their corresponding template statements and prompting the user to
resolve conflicts (or failing with an error, or resolving in a default
way with a message), if any.

The more duplication you add to the syntax (declaring macros as well as

using them), the more possibility there is for inconsistancy. The

original syntax minimized the places where inconsistancy is possible; I

favour the KISS approach.

- Andrew
--
* * Matt Santos / / Leo McGarry * * For a Brighter America * *

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System