# Template Property

In this topic:

## Overview

The Template property provides a method of customising the netlist entry for a schematic part. Normally a single line is created in the netlist for each schematic part (except 'F' and 'H' devices which are defined by two lines). The line is created according to the values of various properties most importantly the ref, model, and value properties. If, however, a Template property is specified this system is bypassed and the netlist entry is defined by the value of this property.

The Template property value can contain a number of special keywords and characters that will be substituted during the netlist creation. Values that can be substituted include node names, pin names and the value of any property.

There are three template keywords that define multiple lines to implement series or/and parallel combinations, ladder networks or arrays of devices.

## Template Property Format

The netlist entry for a device with a Template property will be the literal text of the Template property's value with certain special characters and words substituted. Text enclosed by '<' and '>' are keywords and have a special meaning. Text enclosed with '%' is substituted with the value of the property whose name is enclosed by the '%' character. Finally text enclosed by curly braces, '{' and '}' will be treated as an expression and will be evaluated. Each of these is described in more detail in the following sections.

### Property Substitution

Any text enclosed with '%' is substituted with the value of the property whose name is enclosed by the '%' character. So %REF% would be substituted with the value of the ref property.

### Expressions

Text enclosed by curly braces, '{' and '}' will be treated as an expression and will be evaluated. Note that property substitutions are performed before expressions are evaluated, so the result of an expression can depend on any combination of property values.

If the attempt to evaluate the expression fails the result will be empty. No error message will be reported.

### Keywords

Any text enclosed by '<' and '>' represents a keyword. The keyword along with the '<' and '>' will be substituted according to the keyword as defined in the following table. There are two types of keyword: simple and compound. Simple keywords are just a single word whereas compound keywords consist of sequence of names and values separated by colons (':'). Compound keywords are used to generate multiple netlist lines for applications such as creating series and parallel combinations.

### How Template Properties are Evaluated

Template properties are processed in two passes. In the first pass the property names enclosed by '%' are substituted, while keywords and expressions pass through untouched. In the second pass, keywords and expressions are processed and the '%' character is treated literally.

This makes it possible to use property values in expressions and the control values for the multi line keywords. For example:

%MODEL%$%REF% <nodelist> %VALUE% L=%L% W=%W% AD={%W%*0.5u} if L=1u, W=0.5u, MODEL=M, REF=Q23 and VALUE = N1, this would resolve to the following after the first pass: M$Q23 <nodelist> N1 L=1u W=0.5u AD={0.5u*0.5u}

The second pass would then be able to evaluate the expression and resolve <nodelist> (see below). The value of AD will be calculated according to whatever W is set to. This is an alternative method of setting MOSFET area and perimeter values. (The method used with the standard symbols is different in order to remain compatible with earlier versions).

Note that if the property value contains any of the special characters ('<', '>', '{', '}', '%'), these will be treated literally. So if for example a property value was {tailres}, no attempt would be made to evaluate {tailres} in the second pass.

### Keyword Summary

The keywords available are summarised in the following table and explained in detail below.

 Keyword Description BUS Returns name of bus connected to the specified pin FOREACHPIN Repeats for each pin IFD Conditional on whether a property is defined IF Conditional on the result of an expression INODE Generates an internal node. JOIN, JOIN_PIN, JOIN_NUM, JOIN_REF Returns information about a connected device. Used for current probes. MAPPEDNODE[n] As 'node' but order defined by mapping property if present MAPPEDPINNAMES As pinnames but order is altered according to mapping property if present NODELIST, NODELIST_H Substituted with full list of nodes for device. NODENAME This is not replaced by any text but signifies that the item following is a node name. The netlist generator must be able to identify any text that is a node so that it can correctly substitute the name when required. NODE[n] Substituted for individual node NUMPINS Returns the number of pins on a symbol PARALLEL Start of compound keyword to create a parallel combination. PARAMSVALUE Returns passed parameters PINLIST Substituted with full list of pin names for symbol PINNAMES Equivalent to 'pinnames: ' except that no substitution takes place if the /nopinnames switch is specified for the Netlist command. PROBE Similar to node but resolves mapped nodes in SIMPLIS mode REF SPICE compatible part reference REPEAT Start of compound keyword to create a general purpose repeating sequence ROOTDIR Root schematic directory in hierarchical design ROOTPATH Root schematic full path in hierarchical design SCHEMDIR This schematic directory SCHEMPATH This schematic full path SEP Returns separator character. (Usually '$') SERIES Start of compound keyword to create a series combination STEP Used by series and parallel to return sequence number. T Substitutes a property value treating it as a template VALUE Returns the resolved value In the following descriptions the square bracket character is used to denote an optional item. Square brackets in bold ('[', ']') mean the literal square bracket symbol. ### BUS <BUS[n]> Returns the name of the bus connected to the n'th pin. ### FOREACHPIN <FOREACHPIN:var:<body>> Repeats body for each pin on the symbol. var is a variable that will be assigned with the pin number being processed and may be used inside an expression. body may also use keywords <node> and <pin> to access connected nodes and pin names respectively. ### IFD <IFD:propname:action1[:action2]> If propname is present and not blank, action1 will be substituted otherwise action2 will be substituted. Example ifd:value:<%value%>:1> In the above, if the property value is present it will be substituted otherwise the value '1' will be substituted. ### IF <IF:test:action1[:action2]> If test resolves to a non-zero value action1 will be substituted otherwise action2 will be substituted. Typically test would be an expression enclosed in curly braces. ('{' and '}'). For example, the following implements in a somewhat complex manner a series connection of resistors. (This should actually all be on one line) <REPEAT:line:%SERIES%:<%REF%$R{line} <if:{line==
1}:<<NODE[1]>>:$%REF%${line}> <if:{line==
%SERIES%}:<<NODE[2]>>:$%REF%${line+1}> %VALUE%;>>

Note that usually each action should be enclosed with '<' and '>'. They can be omitted if the action does not contain any keywords. If in doubt, put them in.

### INODE

<INODE:name>
Resolves to a unique node number that is guaranteed not be used anywhere else. The value name may be used to identify the number for repeated use within the same TEMPLATE. For example <inode:a> will always resolve to the same node number if used more than once within the same TEMPLATE definition.

INODE is intended to be used to create devices that need multiple netlist lines with connected nodes. This can also be done using a subcircuit but for simple cases INODE may be more convenient.

### JOIN

<JOIN:prop_name[:index]>

This can only be used with instances of symbols with one and only one pin. Returns the value of prop_name on an instance attached directly to the single pin of the device. For example in the following:

<JOIN:REF> on the probe (R1-P) would return R1 as this is the value of the REF property of the resistor. In situations where more than one instance is connected to the pin, index may be used to specify which one. index may have a value between 0 and 1 less than the number of devices connected. Use <join_num> to determine how many devices are connected.

Note that the pin of the device must be directly connected i.e. with pins superimposed and not by wires.

<JOIN> is intended to be used for current probes.

### JOIN_REF

<JOIN_REF>
Similar to <JOIN:REF> except that instead of the literal REF property, it returns how the connected instance is identified in the netlist. This takes account of any TEMPLATE property the connected instance possesses or the MODEL property prefix if it does not have a TEMPLATE property.

### JOIN_NUM

<JOIN_NUM>
Only valid for single pin instances. Returns number of joined devices. See <JOIN> for details.

### JOIN_PIN

<JOIN_PIN[:index]>
Only valid for single pin instances. Returns connected pin name for another device connected to this device's only pin. This can be used in conjunction with <JOIN> to return the current vector for a part. E.g.
<JOIN:REF>#<JOIN_PIN>

for the probe device in:

would return R1#p.

In situations where more than one instance is connected to the pin, index may be used to specify which one. index may have a value between 0 and 1 less than the number of devices connected. Use <join_num> to determine how many devices are connected.

### MAPPEDNODE

<MAPPEDNODE[n]>
Same as NODE except that the mapping property is applied. The mapping property is used to rearrange nodes in a different order than defined on the symbol. It is used by the model-symbol association system to allow a single symbol to be associated with multiple models that may not necessarily have the same terminal order.

### MAPPEDPINNAMES

<MAPPEDPINNAMES>
As PINNAMES but with the mapping property applied. See MAPPEDNODE above.

### NODELIST, NODELIST_H

<NODELIST[:map[|nox]]>
<NODELIST_H[:map[|nox]]>
Replaced by the nodes connected to the device's pins. NODELIST_H includes hidden global pins (see Global Pins) used in hierarchical schematics whereas NODELIST omits these. Has two options:
 map If present will order the nodes according to the MAPPING property. nox If present, will disable XSpice pin attributes. See Adding XSpice Pin Attributes for details.

### NODENAME

<NODENAME>

This is not replaced by any text but signifies that the item following is a node name. The netlist generator must be able to identify any text that is a node so that it can correctly substitute the name when required. For example, the following is the template definition of the N-channel MOSFET with bulk connected to VSS:

%model%$%ref% <nodelist> <nodename>vss %value% If VSS were actually connected to ground, the netlist generator would replace all nodes called VSS with 0 (meaning ground). If the <nodename> keyword were not present in the above the netlist generator would not be able to determine that VSS is a node and the substitution would not take place. ### NODE <NODE[n]> Replaced by the individual node identified by n starting at 1. So node[1] is node name connected to the first pin on the symbol. ### NUMPINS <NUMPINS> Returns the number of pins on the symbol owning the TEMPLATE property. ### PARALLEL <PARALLEL:num:<line>> Creates a parallel combination of the device described in line. For example: <parallel:%parallel%:<<ref> <nodelist> %VALUE%>> creates a parallel combination of parts. The number in parallel is determined by the property PARALLEL. Note that the REF keyword returns the part reference appropriately modified by the MODEL property and appended with the sequence number. If PARALLEL=5, REF=R1, VALUE=1k, MODEL=R and the device is connected to external nodes R1_P and R1_N, this is the end result. R1$1 R1_P R1_N 1k
R1$2 R1_P R1_N 1k R1$3 R1_P R1_N 1k
R1$4 R1_P R1_N 1k R1$5 R1_P R1_N 1k

If the num element is empty - e.g. in above example if PARALLEL property were empty or missing - then no output will be made at all.

The example above can be used for any two terminal part. There must however be a PARALLEL property present on the symbol.

### PARAMSVALUE

<PARAMSVALUE>

Returns the instance's parameters. This is defined by the PARAMS property and will be prefixed with the parameter separator for subcircuit devices. This is params: for SIMetrix mode and vars: for SIMPLIS mode. This keyword will also include tolerance parameters defined by the properties LOT, TOL and MATCH if present.

### PINLIST

<PINLIST>
Replaced by the symbol's pin names.

### PINNAMES

<PINNAMES>

Equivalent to 'PINNAMES: <PINLIST>' except that no substitution takes place if the /nopinnames switch is specified for the Netlist command.

### PROBE

<PROBE[n]>

In SIMetrix mode, behaves identically to NODE. In SIMPLIS mode, will return the mapped node name if relevant. This will happen if the node has a name defined by a terminal symbol. Instead of the assigned node number this keyword will return the node name prefixed by a '#'. As the name implies, this is intended for use with probe symbols.

### REF

<REF>

Returns the part reference of the device using the same rules that are used when the Template property is not present. The rules are:

IF MODEL property is blank OR MODEL is a single character AND first letter of REF property equals MODEL property

<REF> = %REF%

otherwise

<REF> = %MODEL%<SEP>%REF%

### SERIES

<SERIES:num:<line>>

Creates a series combination of the device described in line. For example:

<series:%series%:<<ref> <nodelist> %VALUE%>>

Creates a series combination of parts. The number in series is determined by the property SERIES. Note that the REF keyword returns the part reference appropriately modified by the MODEL property and appended with the sequence number. If SERIES=5, REF=R1, VALUE=1k and MODEL=R and the device is connected to external nodes R1_P and R1_N, this is the end result.

R1$1 R1_P 1 1k R1$2 1 2 1k
R1$3 2 3 1k R1$4 3 4 1k
R1\$5 4 R1_N 1k

If the num element is empty - e.g. in above example if SERIES property were empty or missing - then no output will be made at all.

The example above can be used for any two terminal part. There must however be a SERIES property present on the symbol.

### STEP

<STEP>
Used with SERIES and PARALLEL keywords. Returns sequence number.

### T

<T:prop_name>
Does the same as %prop_name% except that the properties value is evaluated as if it were a template itself. With %prop_name% the literal value of the property is always used. Note that recursive properties will simply be substituted with nothing. E.g. <T:TEMPLATE> will return empty if used in a template property called TEMPLATE.

### VALUE

<VALUE>
Returns the VALUE property value unless the instance is a hierarchical block in which case it returns the name of the referenced subcircuit definition.

### Further Information

To put a new line in the netlist entry you can use a ';'. Literal new lines are also accepted.

To put a literal < >; {} or % character in the text, use two of them. So '<<' will become '<'.

## Template Scripts

It is also possible to write a script to compile the line generated by the netlist generator. Such scripts are called 'Template Scripts'. With this approach, you enjoy the full power of the scripting language and very complex devices can be created in this manner. For full details of this approach, please refer to the Script Reference Manual/Applications/Schematic Template Scripts.