|
|
Table Of Contents
What Are ANA Macro Language Scripts?
Properties Available from the IMO Context
Specifying and Using Parameters
Multiple Formats for IP Subnet Parameters
ANA Macro Language
This appendix describes the ANA Macro Language, its syntax, parameter usage, and pragmas. It includes a detailed example for writing ANA Macro Language scripts. This information is intended for use by programmers who want to write command scripts that are run using Command Builder.
This appendix includes the following sections:
•
What Are ANA Macro Language Scripts?
•
•
•
What Are ANA Macro Language Scripts?
ANA Macro Language scripts consist of a simple sequence of Telnet commands, runtime-replaced input arguments, and inline execution directives that are executed sequentially as Telnet configuration commands on a networking device. ANA Macro Language script lines are evaluated during runtime for argument replacements that result in generation of a Telnet device configuration command which can be sent to the device. The reply to the execution of each command line is validated according to the inline directives that can abort and roll back the script, or continue executing the next script line.
An ANA Macro Language script is usually made of a command script and a rollback script. The programmer can specify that if a command script is detected to have failed, a rollback script is called.
When defining ANA Macro Language scripts the programmer can:
•
•
•
Properties Available from the IMO Context
The script IMO context makes the ANA Information Model Objects (IMOs) available to the script as built-in arguments. A script IMO context can be any object representable by the ANA IMO, ranging from a managed element to port connector to a routing entry.
Example IMO contexts can include:
•
–
–
•
–
–
For more information about ANA Macro Language built-in parameters, see Built-In Parameters.
Specifying and Using Parameters
ANA Macro Language supports two types of script parameters:
user-defined parameters and built-in parameter. Both are replaced at runtime.
In the Command Builder GUI all parameters (both built-in and user-defined) are available during command creation via a selection list.
Note
ANA Macro Language represents both types of parameters in script lines within dollar signs; for example, $...$. In a VRF configuration command, the input variable vrfName can be defined as ip vrf $vrfName$.
User-Defined Parameters
User-defined input parameters must be defined when you create a command. A parameter specification includes parameter name, type, and an optional default value.
The following is a complete list of the user-defined parameters:
Multiple Formats for IP Subnet Parameters
ANA Macro Language scripts support multiple formats for IP subnet parameters, as described in the table below, using the example 198.168.2.10 255.255.255.0:
For example, routeadd$SB:IP$mask$SB:mask$. The same argument extracts the IP address and then the subnet.
Built-In Parameters
Built-in parameters are the built-in properties available in IMO arguments of the IMO context (for example, portalias, status and so on.), which are automatically set to their runtime value during execution. The built-in properties include IMO attributes, OID attributes, and instrumentation data.
Note
Supported Pragmas
The programmer can insert inline directives or pragmas in the script lines for finer-granularity control. Pragmas are enclosed within square brackets: [...]. The ANA Macro Language-supported pragmas are listed in the following table:
Wherever the carriage return character is required in the middle of a command line, you should use the escape sequence &cr.
You can use multiple pragmas in a single line, in which case all the pragmas are analyzed. If the same type of pragma is repeated, only the last one is used.
Success
Description
A success pragma is validated against the script line reply. The success pragma verifies that a required substring exists in the reply. If the substring is not found, the script fails.
Syntax
[success=<string>]Where
<string>represents the expected return value from the device, the<string>can be simple text or can contain arguments that will be replaced in runtime.Directives
The pragma will be successful and the script will continue only if the
<string>is found in the device reply. It fails if the<string>does not exist in the reply.The
<string>can be a regular expression; it does not necessarily have to be an exact string to match.Examples
The following example verifies that the specified VRF $newVrf$ does not already exist:
show ip vrf $newVrf$ [success=% No VRF $newVrf$]Using
Trialas thenewVRF, this pragma yields success if the device reply contains% No VRF Trial.Fail
Description
A fail pragma is validated against the script line reply. The fail pragma verifies that a required substring does not exist in the reply.
Syntax
[fail=<string>]Where
<string>represents the value that should not be included in the device reply, the<string>can be simple text or can contain arguments that will be replaced in runtime.Directives
The script fails if
<string>is found in the device reply. The script will continue if the<string>does not exist in the reply.The
<string>can be a regular expression; it does not necessarily have to be an exact string to match.Example
The following example sets a route distinguisher:
rd $newRD$ [fail=% Cannot set RD $newRD$]Using
60:60as thenewRD, this pragma yields failure only if the device reply would contain =% Cannot set RD 60:60.Prompt
Description
A prompt pragma is validated against the next Telnet command prompt. The prompt pragma verifies that the suffix of the prompt equals the given string. If the suffix differs from the string, the script fails.
Syntax
[prompt=<prompt>]Where
<prompt>represents the new expected prompt, the<prompt>can be simple text or can contain arguments that will be replaced in runtime before being sent to the device.Directives
The pragma will be successful and script execution will continue only if the
<prompt>is used as the suffix of the device prompt. The pragma fails if the<prompt>is not used as the suffix of the device prompt.Example
The following example changes the Telnet prompt and validates the change in the newly returned Telnet prompt:
configure terminal [prompt=(config)]This pragma yields success only if the next device prompt ends with (config)#.
Full Prompt
Description
A full prompt pragma is validated against the next Telnet command prompt. The full prompt pragma verifies that the prompt equals the given string. If the prompt differs from the string, the script fails.
Syntax
[prompt=^<prompt>]Where
<prompt>represents the expected full prompt, the<prompt>can be simple text or can contain arguments that will be replaced in runtime before sending to the device.Directives
The pragma will be successful and script execution will continue only if the next full prompt equals
<prompt>. The pragma fails if the next prompt does not equal<prompt>.Example
The following example changes the Telnet prompt and validates the change in the newly returned Telnet prompt:
configure terminal [prompt=^router(config)#]This pragma yields success only if the next device prompt matches router(config)# exactly.
Rollback
Description
A Rollback pragma determines that rollback will be executed only upon failures from this point onward.
Note
Directives
If the script fails after the [rollback] marker, then rollback is executed.
Note
Activity
Description
Set the text that, if the script fails, will appear in the script's result as the name of the activity that failed. The failed activity name (label) appears in the returned result and also in the provisioning event that is generated.
Syntax
[activity=<activity>]Where
<activity>represents an inline comment, the<activity>can be simple text or can contain arguments that will be replaced in runtime before sending to the device.Directives
When a failure occurs later in the script, the user is notified of the error by activity name.
Example
[activity=now adding the vrf]Enum
Description
Defines the values that are used when substituting parameter names into a Telnet string.
Directives
The pragma will be successful only if the user inputs one of the values in the list. The pragma fails if the user does not input one of the values in the list.
Example
The enum pragma appears at the top of the script:
[enum RouteTargetTypeEnum 0=export;1=import]Later in the script, the parameter RouteTargetTypeEnum is used:
no route-target $RouteTargetTypeEnum$ $RouteTarget$The value that is substituted into the Telnet command for $RouteTargetTypeEnum$ is export or import instead of 0 or 1.
Example
The following command script and rollback script perform an Add VRF configuration. The scripts use user-defined arguments to represent the VRF name, route target, and route distinguisher; several types of pragmas to validate the device reply; and remarks in the command script and rollback script.
Command Script
[enum rd 1=60:60;2=80:80]show ip vrf $vrfName$ [success=% No VRF named $vrfName$][activity=prepare for VRF creation]config terminal [success=Enter configuration commands, one per line. End with CNTL/Z.] [prompt=(config)]ip vrf $vrfName$ [prompt=(config-vrf)][rollback][activity=create VRF]rd $rd$ [fail=% Cannot set RD, check if it's unique]route-target both $rt$endRollback Script
config terminalno ip vrf $vrfName$endThe following table lists the user-defined argument definitions used in the script:
The following table provides an explanation of the command script line by line:
The following table provides an explanation of the rollback script line by line:
config terminal
Set the device to terminal mode.
no ip vrf $vrfName$
Delete the VRF from the device.
end
Change mode command. Return to normal (enable) mode.
Running the Script
The script is executed with the following input arguments:
vrfName=Trialrd=2rt=60:60The Telnet commands as sent to the device (preview):
show ip vrf Trialconfig terminalip vrf Trialrd 80:80route-target both 60:60end------Rollback------config terminalno ip vrf TrialendFull session:
vrfName=Trialrd=2rt=60:60PE-North#show ip vrf Trial% No VRF named TrialPE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#ip vrf TrialPE-North(config-vrf)#rd 80:80PE-North(config-vrf)#route-target both 60:60PE-North(config-vrf)#endRerunning the script with the same input values (VRF already exists, the command stops after VRF name verification):
PE-North#show ip vrf TrialName Default RD InterfacesTrial 80:80PE-North#^ Failed to find the text '% No VRF named Trial' in the device reply!, script terminated.Running the script with a different VRF name (same RT & RD) (VRF creation begins and then is rolled back due to RD already in use):
vrfName=Trial2rd=2rt=50:50PE-North#show ip vrf Trial2% No VRF named Trial2PE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#ip vrf Trial2PE-North(config-vrf)#rd 80:80% Cannot set RD, check if it's uniquePE-North(config-vrf)#^ Error in activity 'create VRF'.^ Found the text '% Cannot set RD, check if it's unique' in the device reply!, script terminated.-----Invoking Rollback-----PE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#no ip vrf Trial2% IP addresses from all interfaces in VRF Trial2 have been removedPE-North(config)#end
Posted: Mon Sep 24 07:17:34 PDT 2007
All contents are Copyright © 1992--2007 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.
