2

---

AEL Functions

---

The following topics are discussed in this chapter:

• AEL Utility Functions
• AEL Environment Functions

AEL Utility Functions

A set of AEL utility functions (with ael prefixes) provides assessment and verification processes that can be used through Cadence^® SKILL language programs. You can access these functions at any time within a SKILL application and are not limited to use within the AEL environment.

The following section describes the available functions for accessing AEL from the Cadence^® SKILL language.

aelCheckRange

aelCheckRange(
g_b1 
g_val 
g_b2
) 
=> f_violation

Description

Determines if a number falls within a particular range of numbers.

If the argument val falls within the inclusive unordered range from b1 to b2, the function returns 0. If the function returns a value less than zero, val violates the boundary at b1. If the return value is greater than zero, val violates the boundary at b2. The absolute value of the return value is equal to the absolute value of the difference between val and the violated boundary. Each SKILL argument can be a fixnum, flonum, or strnum. If text that is not a strnum (for example, an expression) is passed to this function, it returns NaN. For this function, a strnum that is a complex number is an invalid argument.

The following are some examples:

If	Return value
min(b1, b2) <= val <= max(b1, b2)	0
(b1 < b2) && (val < b1)	-(b1 - val)
(b1 < b2) && (val > b2)	(val - b2)
(b1 > b2) && (val < b2)	(b2 - val)
(b1 > b2) && (val > b1)	-(val - b1)

You might want to add or subtract small values from theoretical boundaries to allow for (possibly different) tolerances, as in the last example in the following table.

Function	Result
aelCheckRange(1, 2, 3)	0
aelCheckRange(3, 2, 1)	0
aelCheckRange(4, 1, 7)	-3
aelCheckRange(7, 1, 5)	4
aelCheckRange(low-epsilon, testVal, hi+hiTol)	tolerantRangeCheck

See also

aelSignum

aelEngNotation

aelEngNotation(
g_value 
x_prec
)
 => t_strRep

Description

Reformats a given number into engineering notation.

This function takes a fixnum, a flonum, or a strnum and returns an engineering notation strnum. If the first argument is text that is not a strnum (for example, an expression), the function returns NaN. If g_value is a complex number, the return value is a string representation where the real part and the imaginary part are each in engineering notation. If the first argument is not a fixnum, flonum, or text, the function returns nil.

The x_prec argument is optional. If this argument is omitted, the function uses the currently set number of significant digits. Using this argument is the same as preceding the call to this function with the call

aelPushSignifDigits(x_prec) 

and following it with

aelPopSignifDigits( )

To find out the number of significant digits in use, call the aelGetSignifDigits function.

The aelEngNotation function is called by many other functions, some of which are also part of AEL.

See also	aelGetSignifDigits
	aelPopSignifDigits
	aelPushSignifDigits
	aelStrDblNotation
	aelSuffixNotation
	aelSuffixWithUnits

aelGetSignifDigits

aelGetSignifDigits( 
)
=> x_sigDigs

Description

Returns the current number of significant digits used by the aelEngNotation function.

See also	aelEngNotation
	aelPopSignifDigits
	aelPushSignifDigits

aelNumber

aelNumber(
g_value
)
=> f_result

Description

Takes an integer, a double, a complex, or a strnum (including complex strnums) and returns an integer, double, a complex, or a strnum.

If the argument is not a fixnum, flonum, or text, it returns nil. You can use this function to test if a SKILL variable contains a number, which is one of the following:

• An integer
• A complex
• A floating-point value
• A strnum, including complex strnums

Example

tt = aelNumber( "123" )
123.0
floatp( tt )
t
AND
tt = aelNumber( 123 )
123
floatp( tt )
nil

aelPopSignifDigits

aelPopSignifDigits(
 )

Description

Discards (pops) the top value of the stack built by the aelPushSignifDigits function and returns a new top value.

This value is the new number of significant digits. If this function tries to discard the last value of the stack, the stack is left unchanged and the function returns 0.

See also	aelGetSignifDigits
	aelPushSignifDigits

aelPushSignifDigits

aelPushSignifDigits(
x_digs
) 
=> x_digs

Description

Places (pushes) a given value onto the stack of values for the number of significant digits the aelEngNotation function uses to create engineering notation strnums.

Many functions call the aelEngNotation function indirectly and can request different numbers of significant digits.

Use the following guidelines:

• Call the aelPushSignifDigits function before the aelEngNotation function.
• Call the aelPopSignifDigits function when you are finished using the aelEngNotation function.

If you try to set fewer than 3 or more than 15 significant digits, the stack is left unchanged and the function returns 0.

The SKILL versions of the aelEngNotation, aelStrDblNotation, aelSuffixNotation, and aelSuffixWithUnits function each take an optional argument, x_prec. This argument has the effect of preceding the main action of the called function with aelPushSignifDigits(x_prec) and following it with aelPopSignifDigits.

See also	aelEngNotation
	aelPopSignifDigits
	aelStrDblNotation
	aelSuffixNotation
	aelSuffixWithUnits

Related Environment Variable

The useSignifDigitsForSimpleNotation variable can be used to control the number of significant digits when the notation is set to simple.

auCore.misc useSignifDigitsForSimpleNotation boolean nil

When this variable is set to true and gLabelsNumNotation is set to simple, the label uses number of significant digits specified in the aelPushSignifDigits() function. By default, the useSignifDigitsForSimpleNotation variable is set to nil.

Example

The table below shows the outputs generated for different values when the useSignifDigitsForSimpleNotation variable is set to t and the number of significant digits specified in the aelPushSignifDigits() function is 5.

Values	Outputs
12345678	12346000
"12345678"	1.2346e+07
12.345678	12.346
123456.78	123460.0
12345.0	12345
"12345"	12345.0
1234567890987654321	1.2346e+18
1.210000585038126e-12	1.21e-12

aelSignum

aelSignum(
g_val
) 
=> -1 / 0 / 1

Description

Analyzes an integer, a double, or a strnum (not including complex strnums) and returns -1 if the value is negative, 0 if it is zero, or 1 if it is positive.

If text that is not a strnum (for example, an expression) is passed to this function, it returns NaN. If the function receives an argument that is not a fixnum, flonum, or text, it returns nil.

aelStrDblNotation

aelStrDblNotation(
g_value
x_prec
) 
=> t_strRep

Description

Calls the aelEngNotation function and, if the result is an integer, appends a decimal point and zero (.0).

This satisfies those situations that require a decimal point to identify a number as a double rather than an integer.

See also

aelEngNotation

aelSuffixNotation

aelSuffixNotation(
g_value 
x_prec
) 
=> t_strRep

Description

Calls the aelEngNotation function and replaces the e and exponent (if any) with the appropriate AEL suffix character. If the value is too small or too large for the AEL set of suffixes, the e and exponent are unchanged.

See also

aelEngNotation

aelSuffixWithUnits

aelSuffixWithUnits(
g_value 
t_units 
x_prec
)
=> t_strRep

Description

Used to display values on forms.

This function is equivalent to

strcat (strcat(aelSuffixNotation(val) " ") units)

This function works like the aelSuffixNotation function with the following exceptions:

• Complex numbers are not supported.
• A space and the given units are appended to the end of the returned text.

AEL Environment Functions

The AEL environment functions (with aelEnv prefixes) for SKILL provide access to the expression evaluation capabilities of AEL. You can use these functions from a SKILL program to perform full or partial evaluation of an expression. See the following chapters for the AEL environment functions for SKILL.

The expression evaluation routine consists of the following steps:

1. Use aelEnvCreate to create the processing environment to allocate a distinct name space and to specify full or partial evaluation.
2. Define variables within this environment and create the expressions to be evaluated.
3. Compile and execute the expressions with aelEnvCompile and aelEnvExecute or interpret the expressions with aelEnvInterpret.
4. Use the fully or partially evaluated expressions.
5. Deallocate the AEL environment that you created.

The following code accesses AEL environment functions with SKILL. The sample creates an AEL environment, sets global variables within the environment, and interprets two mathematical expressions with the variables.

env = aelEnvCreate( 'f )
aelEnvSetGlobals( env "a" 10 "b" 20 )
aelEnvInterpret( env "a+b" )
==> "30.0"
aelEnvInterpret( env "sqrt(a+b)" )
==> "5.4885"

The following section describes the available functions for accessing the AEL environment from SKILL.

aelEnvCompile

aelEnvCompile(
g_env 
t_expr
) 
=> x_compExpr

Description

Compiles a given expression according to the evaluation mode set with aelEnvCreate and the state of globals for the given environment. Compiled expressions are references to dynamically allocated memory. There is no facility for extending their lifetime or visibility beyond the process in which they are created. Do not attempt to store them in a design database. Compiled expressions are invalidated and yield undefined results if you apply the aelEnvFreeCompExpr function to them, or if you destroy their associated environment with the env = nil expression.

Each global appearing in an expression being compiled is created as a deferred global in the given environment if it does not already exist there. Deferred globals have neither type nor value. AEL assumes they are of the correct type.

Call the aelEnvListDeferredGlobals and aelEnvListDeferredFuncs functions after compiling expressions. This lets you see if a typographical error created a deferred global or function when you intended to reference a defined one.

Text substitution in an AEL expression means replacing an AEL global with its text value before compiling the expression. This is similar to a parameterless macro capability. For example, if a is an AEL global with the text value of pi/2, text substitution replaces the global with its text value as shown in the following example.

3*a 
3*(pi/2) 

The first detected error terminates compilation and an error code is set.

Usually, using the compile and execute model produces better performance than the interpreter model.

See also	aelEnvCreate
	aelEnvExecute
	aelEnvInterpret
	aelEnvListDeferredGlobals

aelEnvCreate

aelEnvCreate(
t_evalMode 
g_distinguishIntsFromDbls 
g_keepWhitespace
)
=> x_env

Description

Creates and initializes an AEL environment.

The value returned is used to identify this environment in subsequent calls to various other functions with names beginning with aelEnv.

If the distinguishIntsFromDbls option is nil, all numeric values other than complex numbers are represented as double precision floating-point numerics. There are no integers.

If the keepWhitespace option is nil or omitted, all white space is removed. Otherwise, minimum white space is used regardless of the amount of white space found on input.

Evaluation Mode	Definition
c	All function calls (implies evaluation mode ip)
C	All function calls except the CDF parameter calls
f	Full evaluation, except for deferred globals and functions and their side effects (This does not override evaluation mode C, allowing for all but CDF parameters.)
g	Globals, except those deferred
i	Instance CDF parameters on the same cell (the iPar( ) function)
l	Literal: no evaluation
o	All operators
p	CDF parameters inherited from the parent cell (the pPar( ) function)
r	All related CDF parameters (same as evaluation mode i p )
s	Suffixes
t	Text substitution before compiling

The evaluation mode can be one mode or any combination of modes, except l or f. (The evaluation modes l and f are mutually exclusive.) Explicit and implicit redundancy is benign. For example, isri is a legal evaluation mode in which i occurs twice explicitly and is also implicit in r.

Text substitution in an AEL expression means replacing an AEL global with its text value before compiling the expression. This is similar to a parameterless macro capability. For example, if a is an AEL global with the text value of pi/2, text substitution replaces the global with its text value as shown in the following example.

3*a 
3*(pi/2) 

Text substitution is a mode you can select, like suffixes, globals, and so forth. The flag character is t. For example, to select text substitution and globals, you use gt or tg as the evaluation mode selection. As with other selections, it is illegal to use the evaluation mode t with l (literal), and l is implied in the evaluation mode f (full). The evaluation mode t is meaningless if the mode does not call for evaluation of globals, or if you have no globals with text values.

aelEnvExecute

aelEnvExecute(
x_compExpr
) 
=> t_result

Description

Executes the previously compiled AEL expression with the current global values of the environment in which it was compiled.

The evaluation mode set with aelEnvCreate is in effect. The values of globals in that environment can be changed by the aelEnvSetGlobals function any number of times between a single compile and any number of executions.

It is invalid to call this function once you apply the aelEnvFreeCompExpr function to the compiled expression or destroy the associated environment by the following expression:

env = nil

If there is an error, the return value is nil. Otherwise, it is a string.

See also	aelEnvCompile
	aelEnvInterpret
	aelEnvSetGlobals
	aelNumber

aelEnvFreeCompExpr

aelEnvFreeCompExpr(
x_compExpr
) 
=> t

Description

Frees the dynamically allocated memory used to store the compiled AEL expression.

It is invalid to refer to a compiled expression after you apply this function to it.

aelEnvGetErrStr

aelEnvGetErrStr(
 ) 
=> t_errMsg

Description

Converts the error code currently stored in the all-AEL-wide error flag into an appropriate message.

This call resets the flag to no error. If no error has been detected, the function returns the string no error.

aelEnvGetGlobal

aelEnvGetGlobal(
x_env
t_name
) 
=> g_value

Description

Returns the current value of the named global, previously defined or deferred, in the given environment.

This function does not work if you have used the following expression to destroy the given environment:

env = nil

The second argument can be text or a symbol. The return value is of the appropriate type.

If the global is neither defined nor deferred in the given environment, the function returns nil. If the global is deferred, the return value is the text string deferred.

aelEnvInterpret

aelEnvInterpret(
x_env 
t_expr 
t_mode
) 
=> g_value

Description

Compiles and executes the specified expression in a single step.

This function is similar to calling the aelEnvCompile function, followed by the aelEnvExecute function, followed by the aelEnvFreeCompExpr function. The aelEnvCompile function uses the evaluation mode set when the environment was created. The aelEnvInterpret function uses whatever evaluation mode you specify in the t_mode. You can default to the evaluation mode set during the creation of the environment by passing nil for the evaluation mode in this call, or by omitting this argument.

Usually, using the compile and execute model produces better performance than the interpreter model.

See also	aelEnvCompile
	aelEnvCreate
	aelEnvExecute
	aelEnvFreeCompExpr

aelEnvListDeferredFuncs

aelEnvListDeferredFuncs(
x_env
) 
=> l_names

Description

Returns a list of all functions found in the compiled or interpreted expressions in the given environment that are undefined in AEL.

See also	aelEnvListExprFuncs
	aelEnvListFuncs

aelEnvListDeferredGlobals

aelEnvListDeferredGlobals(
x_env
) 
=> l_names

Description

Returns a list of all globals found in the compiled or interpreted expressions in the given environment that have not been defined in a call to the aelEnvSetGlobals function.

See also	aelEnvListExprGlobals
	aelEnvListGlobals

aelEnvListExprFuncs

aelEnvListExprFuncs(
t_expr
) 
=> l_funcs

Description

Returns a list of all the functions found in the given expression.

aelEnvListExprGlobals

aelEnvListExprGlobals(
t_expr
) 
=> l_globals

Description

Returns a list of all the globals found in a given expression.

aelEnvListFuncs

aelEnvListFuncs( 
) 
=> l_names

Description

Returns a list of all the functions defined for all AEL environments.

See also	aelEnvListDeferredFuncs
	aelEnvListExprFuncs

aelEnvListGlobals

aelEnvListGlobals(
x_env
) 
=> l_names

Description

Returns a list of all the globals in a given AEL environment. The list does not include AEL predefined constant globals or deferred globals.

See also

aelEnvListDeferredGlobals

aelEnvListGlobalsValues

aelEnvListGlobalsValues(
x_env
) 
=> l_names

Description

Returns a list of all global names and their values in a given AEL environment. The list does not include AEL predefined constant globals or deferred globals.

aelEnvName

aelEnvName(
t_name
) 
=> t/nil

Description

Accepts text or a symbol and returns a legal AEL name stripped of any leading or trailing white space that might have been in the argument.

The input is subject to lexical validation only. If the name is not a legal AEL name, nil is returned. No test is performed to determine if this global is defined or deferred in any AEL environment.

Legal global or function names match the regular expression

[a-zA-Z][a-zA-Z_$0-9]*

aelEnvSetGlobals

aelEnvSetGlobals(
x_env 
t_name 
g_val
) 
=> x_count

Description

Sets the values of the named globals in a given environment, creating them if necessary.

Legal global names match the regular expression

[a-zA-Z][a-zA-Z_$0-9]*

The second argument can be text or a symbol. The third argument can be an integer, a double, or a text string. If it is a symbol, it is treated as a text string. If it is a text string or a symbol, it does not have to be a strnum but can be any text. The second and third arguments can be followed by any number of name-value pairs.

It is an error if any value passed is of an unsupported type, or if a global with the given name already exists in the given environment and is of a different type. It is also an error to call this function once you use the following expression to destroy the given environment:

env = nil      

where

env = aelEnvCreate(...)

You cannot set a global once it is deferred. You cannot defer a global once it has been set.

You can apply the aelEnvSetGlobals function any number of times before or after you apply aelEnvCompile, aelEnvExecute, or aelEnvInterpret expressions.

If the return value is 0, it means an error prevented definition of any globals. If it is negative, it means an error occurred with some globals defined, and others not. The absolute value of the return value is the first global that did not get defined. No subsequent globals are tried. For example, if you try to define three globals and the return value is -2, the first global was set successfully, the second caused an error, and the third was not attempted.

A positive return value is the number of globals set. It should equal the number of globals submitted.

See also	aelEnvCompile
	aelEnvExecute
	aelEnvGetErr
	aelEnvGetErrStr
	aelEnvInterpret
	aelEnvSetGlobalList
	aelSetLineage

aelEnvSetGlobalList

aelEnvSetGlobalList(
x_env 
l_dpl
) 
=> x_count

Description

Using a disembodied property list as input sets the values of the named globals in a given environment.

This function is similar to aelEnvSetGlobals. If the name-value pairs are already collected into a disembodied property list, use aelEnvSetGlobalList to pass the list as the second (and last) argument.

See also

aelEnvSetGlobals

aelSetLineage

aelSetLineage(
x_env 
g_lineage
) 
=> o_lineage

Description

The aelSetLineage function sets reference to a lineage for hierarchical expression evaluation. The lineage can either be a list or an aelLineage (SKILL user-defined) object. In either case, an aelLineage object is returned. The list is an ordered list of cell views whose car is the current instance, whose cadr is its parent, and so on. The last element of this list should be the top cell view.

Example

mxEnv = aelEnvCreate("f" t t)
top_cv=dbOpenCellView("sample" "mytop" "schematic")
mid_cv=dbOpenCellView("sample" "mymid" "schematic")
bot_cv=dbOpenCellView("sample" "mybot" "schematic")
foreach(inst top_cv~>instances
     if(inst~>cellName == "mymid" then
          mid_inst = inst
     )
)
foreach(inst mid_cv~>instances
     if(inst~>cellName == "mybot" then
          bot_inst = inst
     )
)
midDBList = list(mid_inst top_cv)
botDBList = list(bot_inst mid_inst top_cv)
foreach(inst mid_cv~>instances
     if(inst~>cellName == "res" then
          if(car(inst~>prop~>name) == "r" &&
               index(car(inst~>prop~>value) "pPar") then
               tmpList = cons(inst midDBList)
               aelSetLineage(mxEnv tmpList)
               value = aelEnvInterpret(mxEnv car(inst~>prop~>value))
               printf("Mid: %L=%L -- %L\n" inst~>name value inst~>prop~>value)
          )
     )
)
foreach(inst bot_cv~>instances
     if(inst~>cellName == "res" then
          if(car(inst~>prop~>name) == "r" &&
               index(car(inst~>prop~>value) "pPar") then
               tmpList = cons(inst botDBList)
               aelSetLineage(mxEnv tmpList)
               value = aelEnvInterpret(mxEnv car(inst~>prop~>value))
               printf("Bot: %L=%L -- %L\n" inst~>name value inst~>prop~>value) ;
          )

     )
)

Return to top