ASCII Data Import

Introduction

ASCII Data Import is a scriptable language for assigning properties to components. For the most part users will have no need to use this method of property manipulation as the Design Explorer and the Bill of Materials Property Editor both provide a convenient GUI driven front end to the language.

However, there may be times where the full flexibility of writing ADI scripts is preferred and for completeness of documentation the following is a reference guide to the language.

The idea of ADI is that much of the data you would store within components (e.g. costs, stock codes, tolerances) will remain the same for each component type across all your designs. ADI allows you to specify data for different component types in a simple ASCII file and to import it all into a design with just one command.

The ADI source file can be created with any ASCII text editor, for example Ultraedit or Notepad. The file can contain any number of separate commands, each of which starts on a new line with its command keyword and ends on a new line with the keyword END. A single asterisk closes a command block in exactly the same way as END. Anything following a semi-colon is treated as a comment and discarded, unless the semi-colon falls inside a quoted string.

There are three ADI commands: the BLOCK command, the IF...END command and the DATA...END command.

The ADI interpreter is run by invoking the ASCII Data Import Tool command on the Tools menu and then selecting an ADI file with the file selector, which filters on ADI files/*.ADI. The commands within the ADI file are loaded and pre-compiled, and Proteus then applies each command in the file, in order, to every object on every sheet of the design. The walk is over objects rather than over components alone, so a command whose test matches something other than a component will be applied to it.

Any errors are written to an error log which is displayed automatically in a window titled ADI ERRORS, and which closes with the line Done: No Errors. or Done: <n> Errors. A command block containing an error is discarded whole rather than partly applied, so one mistyped line costs you the whole block it sits in, and a file whose last block is never closed logs Unexpected end of file. Unlike the Electrical Rules Check report, this log cannot be saved to a file of your choosing.

See Also : Using ADI to Index Libraries.

The BLOCK Command

Properties in Proteus are held in named text blocks, and by default an ADI assignment is made to the object's normal property block. The BLOCK command changes that default for every command which follows it in the file. It takes the form:

BLOCK=<NAME>

It occupies a single line and has no closing END. Once given it stays in force until another BLOCK command replaces it or the end of the file is reached. This is the mechanism by which ADI writes into a library's index block rather than into a component's own properties.

Using ADI to Index Libraries

The IF...END Command

The IF...END command allows you to test the existing properties of each component via an expression, and if the expression evaluates TRUE, then the sub-commands within the IF...END block are applied to the component in succession. The syntax is best explained by example:

IF DEVICE="CAP ELEC" AND NOT VALUE=10p

   VALUE=1n,HIDEKWD

   TOLERANCE,HIDE

   STOCKCODE,REMOVE

END

The expression to be applied to the component follows the keyword IF. Expressions consist of one or more terms separated by operators. Each term consists of a property value, optionally followed by an equals sign and a value.

  • A term only evaluates TRUE if the property named exists, and in the case where a value has been specified, the property value matches the value specified, case-sensitively. The ? and * wildcards described under the DATA...END command may be used here too.
  • Operators consist of brackets, which may be used to enclose sub-expressions, and the keywords AND, OR and NOT. The operators AND and OR are executed left to right; there is no precedence. The AND operator evaluates TRUE only if the evaluation so far is TRUE and the term or sub-expression following it evaluates TRUE. The OR operator evaluates TRUE if the evaluation so far is TRUE or the term or sub-expression following it evaluates TRUE. The NOT operator is unary and has the effect of negating the single term that follows it; it cannot be applied to a bracketed sub-expression.
  • A special expression, consisting of the single keyword TRUE allows you to affect all components in the design.

In the example, the expression tests that the component is an instance of the CAP ELEC library device and that it does not have a value of 10p. If this is the case, then the three sub-commands after the IF expression and before the closing END keyword are applied to the component. Note that, because the device being tested for contains a space (CAP ELEC), it is enclosed in double quote ('"') characters.

Each sub-command consists of a property name optionally followed by an equals sign and a new value and/or a comma and a command. If a value is specified, the property named is either created with the new value or has its existing value modified. If a command is specified it is executed after any assignment, with the exception of REMOVE, which removes the property instead of assigning to it:

Command Description

SHOW

Both the property name and its value are made visible.

HIDE

Both the property name and its value are hidden.

HIDEKWD

The property name is hidden; the visibility of the property value is unchanged.

HIDEVAL

The property value is hidden; the visibility of the property name is unchanged.

REMOVE

The property name and any value is removed from the component.

If no command is specified then the existing visibility of the property name and value is unchanged.

In the example, the property VALUE is assigned the value 1n and the property name is hidden, the value of the property TOLERANCE is left unchanged but the property/value pair is hidden and finally, the property STOCKCODE is removed from the component.

Two further forms are available within an IF sub-command.

  • A property name can be qualified with a target block name and a colon, so that INDEX:CATEGORY=Resistors writes to the INDEX block for that one assignment whatever the current BLOCK command says.
  • An assignment value can pull in the value of another of the object's properties by naming it in chevrons, so STOCKCODE=LX-<VALUE> assigns the text LX- followed by the component's own value. Two chevrons together give a single literal chevron.

The DATA...END Command

The DATA...END command allows multiple test values to be tested against a fixed list of property names, and given a match, allows a set of separate values to be assigned to a separate set of fixed properties.

Consider the following example of a DATA...END command:

DATA DEVICE   + (VALUE) : COST+, TOLERANCE, STOCKCODE-

     RES         1k    : 0.01,  1%,        100-1001

     RES         1k2   : 0.01,  1%,        [REMOVE]

     "CAP ELEC"  1n    : 0.03,  5%,        200-1001

     SWITCH      *     : 0.25,  [SKIP] ,    300-1001

END

The DATA keyword is followed by the name or names of the properties to be tested, separated by plus characters. A test property name wrapped in round brackets, as VALUE is in the example above, is compared numerically rather than textually; this is described under the two unusual features below. The list of test properties is followed by a colon and then a list of the name or names of the properties to be assigned, separated by commas. Each property name to the right of the colon may optionally be directly followed by a plus or minus character that reflects whether you want the property named and the value assigned to it to be shown or hidden respectively; no character indicates that existing visibility should be maintained.

Either side of the colon, [SKIP] can be given in place of a property name. That nulls out a whole column, so a column can be taken out of use without your having to delete the corresponding value from every data line beneath it.

In the example, the DEVICE and VALUE properties are tested. Given a match, new values are assigned to the COST, TOLERANCE and STOCKCODE properties; the COST property and its value being made visible and the STOCKCODE property and its value being hidden.

Each line between the DATA keyword line and the END keyword consists of a list of the property values that you want to test for (separated by one or more spaces, commas or tabs), a colon, and then the list of property values you want to assign, separated by commas. Each line is executed in turn; the value of each property named in the list to the left of the colon on the DATA line is tested against the corresponding test value on current line. If all property values match, then each property named on the right of the colon on the DATA line is assigned the corresponding assignment value on the current line.

In the example, the first line tests the DEVICE property for the value RES and the VALUE property for the value 1k; if both match then the COST property is assigned a value of 0.01, the TOLERANCE property a value of 1% and the STOCKCODE property a value of 100-1001. Similarly the third line tests the DEVICE property for the value CAP ELEC (because the device name contains a space it must be enclosed in double quotes) and the VALUE property for the value 1n; if both match then the COST property takes a value of 0.03, the TOLERANCE property a value of 5% and the STOCKCODE property a value of 200-1001.

Note that the CAP ELEC device name is enclosed in double quotes. You must do this for any of the match values to the left of the colon as these are space delimited. If this were not done, Proteus would have complained it was expecting a colon since it would have assumed you  wanted to test DEVICE property against the value CAP and VALUE property against the value ELEC; the 1n would then be unexpected. Similarly, the assignment values to the right of the colon are comma delimited, so if you wanted to assign a new value that contains a comma, then you would have to enclose the value  in double quotes.

There are two unusual features of the property values that ADI tests for.

  • The values can contain the wild-card characters: '?' and '*'. The question mark indicates that any single character may appear in the property value being tested in same position as the question mark. The asterisk indicates that any number of characters may appear in the property value being tested between the sets of characters to the left and right of the asterisk.  In our example above, we test for a DEVICE property with the value SWITCH but choose not to test such a component's VALUE property by specifying a test value of a single asterisk.
  • Numerical values, including values that contain exponent suffixes such as 'k' or 'u'. Numeric matching is not automatic and it is not a property of the value: it is switched on for a whole column by wrapping that test property's name in round brackets in the DATA line, as VALUE is in the example above. Where it is switched on, both the test value and the property value are converted into a textual representation with six decimal places and an exponent, and the two representations are then compared. In our example, a component placed from the library device RES and assigned a value of 1k, 1000 or 1.0k matches the test condition in the first line, because all three convert to the same representation. Without the brackets the comparison is textual and only 1k matches.

Matching in a DATA...END command is case-insensitive, whereas matching in an IF...END expression is case-sensitive. This is the one place where the two commands deliberately behave differently.

Whilst the list to the right of the colon normally consists of a new value to be assigned to the respective property named on the DATA line, you can instead specify a command, as follows:

Command Description
[NULL] Assign the respective property an empty string. Only the property name and the following equals sign will appear in the component's properties text block.
[REMOVE] Remove the property; the property name and its value are removed from the component's text property block.
[SKIP] Skip assignment to the respective property. This keyword is required as an empty assignment (nothing between the commas) will cause an error. Any existing property in the component's text property block is left unchanged.
[PROPNAME] Assign the respective property the value of the object's own PROPNAME property, so [VALUE] copies the component's value across. Any bracketed value which is not one of the three keywords above is treated this way, which means that an assignment value which genuinely begins and ends with square brackets will be read as a property copy rather than as literal text.

The second line of the example specified that the STOCKCODE property of any component placed from a RES device with a VALUE of 1k2 should be removed. Similarly, line four, specifies that there should be no assignment to the TOLERANCE property of a component placed from a SWITCH device.

See Also:

Property Assignment Tool

Using ADI to Index Libraries