|
|
There are five different Script Language commands, one for each type of object being accessed:
1. Session management commands to create and manage sessions:
AVtm Command Arguments
2. Transaction management commands to start, schedule, apply, and manage Transactions:
AVcr Command Arguments
3. Service object commands to list, view, and update Service objects (these commands may also be used to list and view Service profiles):
java com.syndesis.CPC.CPC SOClass Command Arguments
4. NNI resiliency commands to re-thread circuits on link failure and recovery:
java com.syndesis.resiliency.ServiceUtility Command Arguments
5. Configuration object commands to list, view, update and upload configuration objects (these commands may also be used to list and view Transactions, Modified Objects and Sites associated with Transactions, Upload Requests, and Services):
nps Command Arguments Results
Arguments are normally passed by value, but with some nps commands arguments are passed by name.
Result arguments from nps commands are always passed by name: the command is passed the name of a shell variable into which it will place the result. Input arguments are usually passed by value.
To pass an argument by name, put the name of the variable in the command line. For example:
NDID (the name of the shell variable NDID)
To pass an argument by value, put an expression in the command line. Examples of expressions are:
1 (the value 1) XXNDNode (the text string "XXNDNode") $NDID (the value of the shell variable NDID)
This chapter shows first how to work with configuration objects and then how to work with Service objects.
The following simple example illustrates some of the key features of using Script Language configuration object commands. As mentioned earlier, these commands may be used to list and view other objects besides configuration objects, such as Transaction objects. The Transaction object is used in the following examples because it is simple and common among all CPCs.
#!/bin/ksh 1 # Display the name of the user who applied this Transaction # Syntax: whoapp <Transaction#> # where <Transaction#> is the number of the Transaction . $CCP_BIN/npsinit 2 nps selectone CR number=$1 TRID 3 nps read $TRID TRATTS 4 nps retrieve TRATTS sheduledby USER 5 echo " This Transaction was applied by $USER" nps stop 6
1. The usual command to ensure that the script is running in a Korn Shell. This appears at the beginning of all example shell scripts in this manual.
2. Runs npsinit to initialize the configuration object interpreter, and define the ksh command nps. Must be the first Script Language configuration object command executed in any such script application. Note that this command must start with ". "(a period followed by a space). $CCP_BIN is the location of the configuration object interpreter executable file. This environment variable is defined when the user logs on.
3. The nps selectone command returns the object id of the Transaction whose number is provided in the script input parameter ("$1"). An object id is the unique internal identifier for each object in the CPC database. The command returns the Transaction's object id in the ksh variable "TRID". nps selectone is like the Get List command of the interactive user interface: given an object class (in this case, "CR" or Transaction) and a set of search criteria ("number=$1") it returns the one object of that class that meets the criteria.
4. The nps read command reads from the CPC database into the array TRATTS the attributes of the object identified uniquely by the object id TRID.
5. The nps retrieve command extracts a specific attribute from the TRATTS attribute array, namely the "scheduledby" attribute. The result is returned in variable "USER".
6. This command causes the configuration object interpreter to exit. This does not have to be the last command in the script, merely the last nps command.
Running this script with an example database produces the following result:
whoapp 1001 This Transaction was applied by rappaport
This illustrates a type of script that retrieves attributes from objects, in this case, a Transaction. Such scripts usually execute the following steps:
As we will see, there are several variations on these steps, and different ways of accomplishing each step. In the next example, we explore some of these.
In the previous example, we used the nps selectone command to obtain the object id for one Transaction. The search criteria passed to nps selectone must select exactly one object: if multiple objects satisfy the criteria, nps selectone returns an error. In the previous example, we provided the Transaction number as search criterion, so we were sure that only one Transaction would match.
In many cases, you want to deal with several objects of the same class or base class. In such cases, you would use the nps selectmany command, as in the following example.
#!/bin/ksh # Display all Transactions and the names of the users who # applied them # Syntax: whoappall . $CCP_BIN/npsinit nps selectmany CR number=* TRLIST NUMTRS 1 ITEM=1 while [ $ITEM -le $NUMTRS ] do nps readitem $TRLIST $ITEM TRID TRATTS 2 nps read $TRID TRATTS 3 nps retrieve TRATTS number TRNUM 4 nps retrieve TRATTS scheduledby USER 5 echo " Transaction $TRNUM was applied by $USER" ((ITEM=ITEM+1)) done nps stop
1. nps selectmany returns a list of the objects that match the search criteria. In this case, we provide a wild-carded search criterion ("number=*"), requesting all Transactions whose "number" attribute matches any text string. This ensures that all existing Transactions are included in the list. The first returned variable, "TRLIST", is the id of the list of Transactions. You cannot manipulate this value directly: you must use the nps readitem command to extract specific items from the list. The second returned variable, "NUMTRS", is the number of items returned in "TRLIST" (which is the number of Transactions that match the criteria).
2. nps readitem returns the object id and some attributes of one of the items of the list "TRLIST". The variable "ITEM" identifies which list item to return. (List items are numbered starting at 1.) Unlike the nps read command, nps readitem does not return all of the object's attributes. nps readitem only returns those attributes that are selectors. Refer to the section titled, "OAF Attribute Definitions" later in this chapter for an explanation of how to identify these.) The Transaction "scheduledby" attribute is not a selector, so we need to do an nps read to get this attribute.
3. Reads the attributes of the object identified uniquely by "TRID"" into the array "TRATTS". By using the same attribute array variable, TRATTS, as in the previous line, we are destroying the attributes stored there by nps readitem, but this new array includes all attributes of the object, so no information is lost. Note that this is the same command used in the previous example to get the attribute array.
4. Extracts the attribute "number" (the Transaction number) from the "TRATTS" attribute array. The result is returned in variable "TRNUM".
5. Extracts the "scheduledby" attribute from the TRATTS attribute array. The result is returned in variable "USER". This is the same command used in the previous example.
Running this script with an example database produces the following result:
whoappall Transaction 1001 was applied by rappaport Transaction 1002 was applied by elliott Transaction 1003 was applied by daley Transaction 1004 was applied by taggart Transaction 1005 was applied by chauhan Transaction 1006 was applied by sacco Transaction 1007 was applied by hedges Transaction 1008 was applied by emsley Transaction 1009 was applied by hirabavashi
This example also illustrates the use of ksh commands such as while to control the execution of flow-through applications.
The previous examples dealt only with displaying object attributes, specifically Transactions. The flow-through applications that you write will be interacting with Service objects and configuration objects. Interacting with Service objects is discussed later.
To retrieve and update configuration objects, it is necessary to understand the data model for the managed network. The flow-through application programmer determines the names, attributes and relationships of the objects using textual Object Attribute Files (OAFs) that are supplied with CPC and its Equipment Modules.
In this tutorial we use a simple, hypothetical data model to provide specific objects and attributes for the example flow-through applications. Figure 3-1 illustrates the data model. The gray arrows represent containment (or ownership) relationships: for example, the Node object contains Physical Port objects. The black arrows represent "use" relationships: for example, an FR-FR PVC uses a FR-FR PVC Profile Cardinality is shown by the symbols at each end of the arrows: for example, a FR-FR PVC can associate to 1 FR-FR PVC Profile; each FR-FR PVC is contained in exactly two Logical Ports.
In the section "Displaying Attributes for Multiple Objects" we provided an example of a flow-through application that reported on existing Transactions and printed some of their attributes. Using the object class definitions in the OAFs in Appendix A, we can now perform a similar function for configuration objects. First we introduce a few new concepts.
Script Language provides a syntax for specifying attributes by name. This syntax, called an attribute value assertion, has the following format:
AttName=AttValue
where:
AttName is the name of the attribute, taken from the "Attribute" column in the OAF.
AttValue is the name of the desired value, the current or desired label, or the current or desired mode of the name attribute. The actual meaning of AttValue depends on the Script Language command in which it occurs.
The following example displays all of the attributes for a particular node. Each line of output is an attribute value assertion.
#!/bin/ksh
# Display attributes of a node
# Syntax: ndatts <node name>
. $CCP BIN/npsinit
nps selectone XXNDNode srname=$1 NDID 1
nps read $NDID ATTR VALUES 2
ATTR=0
NUMATTRS=${#ATTR VALUES[*]}
while [ $ATTR lt $NUMATTRS]
do echo " ${ATTR VALUES [$ATTR]}" 3
((ATTR=ATTR+1))
done
nps stop
1. Returns in "NDID" the object id of the node that has the name supplied as the script parameter.
2. Reads the node's attributes into the array "ATTR VALUES".
3. Displays an attribute from the array.
Running this script with an example database produces the following result:
$ndatts Seattle srnetwork.srname=XX Network domain= vpn= sy_version=0 srmgmtaddress=000.000.000.000 srcost=100 srtype=XX1 srclass=XXND srnetwork=XXNTNetwork:1001 sy_pendoperation=1 sy_modifieddate=1998-JAN-24 10:54:35 sy_committeddate=1998-JAN-24 10:54:35 pending_status=CURRENTNOPENDING sy_changeorderid=SYuplUploadRequest:3334 sy_createddate=1998-JAN-23 11:32:50
 |
Note The order of presentation of attributes in the array is not necessarily related to the order in the OAF. |
This script shows that you can examine attributes by array index ("ATTR_VALUES[*]"). You can also examine attributes by name. Once the script has executed an nps read command, you can use the nps retrieve command to determine the value of a particular attribute if you know its name. For example, the command:
retrieve ATTR VALUES srname VAL
inserted after the nps read command in the script above returns in "VAL" the value of the attribute "srname".
The script "ndatts" in the previous section produces a somewhat unfriendly output in that each attribute is identified by its internal name. Users familiar with the CPC GUI tend to identify attributes by their labels: for example, "Management Address" rather than "srmgtaddress".
The Script Language lets you retrieve the label for a particular attribute using the nps getlabels command. nps getlabels returns an attribute array (AttName = AttValue) in which each AttValue is the label for the corresponding AttName.
As an example, consider the following variant of the previous example.
#!/bin/ksh
# Display attribute labels and values for a node
# Syntax: nodeatts <node_name>
. $CCP_BIN/npsinit
nps selectone XXNDNode srname=$1 NDID
nps read $NDID ATTR_VALUES 1
nps getlabels $NDID ATTR_LABELS 2
ATTR=0
NUMATTRS=${#ATTR_VALUES[*]}
while [ $ATTR -lt $NUMATTRS ]
do nps split "${ATTR_VALUES[$ATTR]}" NAME VALUE 3
nps retrieve ATTR_LABELS $NAME LABEL 4
if [ "$LABEL" != "" ] 5
then echo " $LABEL = $VALUE"
else echo " $NAME = $VALUE"
fi
((ATTR=ATTR+1))
done
nps stop
1. As in the previous example, reads the attributes of the specified node into the array "ATTR_VALUES".
2. Reads the attribute labels of the specified node into the array "ATTR_LABELS".
3. Extracts one attribute from the attribute array and splits it into the attribute's name (into variable "NAME") and value (into variable "VALUE".).
4. Extracts from "ATTR_LABELS" the label that corresponds to the attribute "$NAME".
5. This if statement handles the case of attributes (for example, relationship attributes) that have no labels. For these attributes we simply print "name=value".
Running this script against the example node Seattle gives the following result:
$nodeatts Seattle Containing Network =XX Network Domain = Name = Seattle Customer = Version = 0 Management Address = 000.000.000.000 Transit Cost = 100 Node Type = XX1 Class = XXND srnetwork = XXNTNetwork:1001 sv pendoperation = 1 symodifieddate = 1998-JAN-24 10:54:35 sycommitteddate = 1998-JAN-24 10:54:35 pending status = CURRENTNOPENDING sv changeorderid = SYuplUploadRequest:3334 sv createddate = 1998-JAN-23 11:32:50
To see whether an attribute field mode is READONLY or READWRITE, the Script Language lets you read the attribute field modes with the nps readmodes command. nps readmodes returns an attribute array (AttName = AttValue) in which each AttValue is the mode for the corresponding AttName.
As an example, consider the following variant of the previous example.
#!/bin/ksh
# Display attribute labels and values for a node
# Syntax: nodeatts <node_name>
. $CCP_BIN/npsinit
nps selectone XXNDNode srname=$1 NDID
nps read $NDID ATTR_VALUES
nps getlables $NDID ATTR LABELS
nps readmodes $NDID ATTR MODES 1
ATTR=0
NUMATTRS=${#ATTR_VALUES[*]}
while [ $ATTR -lt $NUMATTRS ]
do nps split "${ATTR_VALUES[$ATTR]}" NAME VALUE
nps retrieve ATTR_LABELS $NAME LABEL
nps retrieve ATTR_MODES $NAME MODE 2
if [ "$LABEL" != "" ]
then echo " $LABEL = $VALUE, $MODE"
else echo " $NAME = $VALUE $MODE"
fi
((ATTR=ATTR+1))
done
nps stop
1. Reads the attribute modes of the specified node into the array "ATTR_MODES".
2. Extracts from "ATTR_MODES" the mode that corresponds to the attribute "$NAME".
Running this script against the example node Seattle gives the following result:
$nodeatts Seattle Containing Network = XX Network, READONLY Domain =, READWRITE Name = Seattle, READWRITE Customer =, READWRITE Version = 0, READONLY Management Address = 000.000.000.000, READWRITE Transit Cost = 100, READWRITE Node Type = XX1, READWRITE Class = XXND, READWRITE srnetwork = XXNTNetwork:1001, READONLY sy_pendoperation = 1, READONLY sy_modifieddate = 1998-JAN-24 10:54:35, READONLY sy_committeddate = 1998-JAN-24 10:54:35, READONLY pending_status = CURRENTNOPENDING, READONLY sy_changeorderid = SYuplUploadRequest:3334, READONLY sy_createddate = 1998-JAN-23 11:32:50, READONLY
In an CPC data model, there is one Network object which is the highest object within the object containment tree structure. As there is only one such object, it has a pre-defined object id. This Network object can be obtained directly using the nps read command and supplying its object Id, which is provided in the environment variable NPSNETOBJID. For example:
nps read $NPSNETOBJID ATTR_VALUES
The Script Language commands nps selectone and nps selectmany allow you to specify search criteria in the form AttName = AttValue to identify a particular object or objects, much like search criteria in the list windows of the GUI. Previous examples have shown simple search criteria specifications for these commands. Using wildcards and multiple criteria, you have a great deal of control over the objects that these commands return.
Not all object attributes can be searched for--only attributes that appear as columns in the object's GUI list viewer plus object identifiers can be specified in the search criteria. These are listed in the object class's OAF as selectors.
The values that can be entered for a search criterion depend on the Syntax of the selector. (See the Syntax column of the OAF.) The general rules are:
All attributes with Syntax OId are selectors, so searching on these attributes is permitted.
To specify multiple search criteria, separate each AttName = AttValue specifier with the character "/". If more than one search criterion is supplied, the command returns the objects that match all of the supplied criteria.
If you omit a reference to a specific selector attribute, the specifier AttName = * is assumed for that attribute.
The simplest search criteria specification consists of "/", which specifies that attribute_name = * is to be assumed for all selector attributes of the object class.
|
Note The same attribute can be supplied more than once with different values. This must be done with care, however, because mutually exclusive criteria always returns no objects: for example, "port.card.slot=1/port.card.slot=2" always returns no objects, because no objects can have the attribute "port.card.slot" with a value of both 1 and 2. |
If the data you are selecting for contains the "/" character, you must include the following after the select command:
-criteria arrayName
where arrayName is the name of an array. The elements of this array are specified in the form <name>=<criteria>. An array that is left empty means that no criteria has been specified. Subsequent queries will select all the data.
The following table lists the Logical Ports in an example database along with their selectors. We use these objects in the example commands in this section.
| srname | srclass | srnode.srname | ... |
|---|---|---|---|
seat.0 | XXLP | Seattle |
|
seat.1 | XXLP | Seattle |
|
seat.8 | XXLP | Seattle |
|
seat.9 | XXLP | Seattle |
|
seat.24 | XXLP | Seattle |
|
seat.48 | XXLP | Seattle |
|
la.0 | CCLP | Los Angeles |
|
la.1 | CCLP | Los Angeles |
|
la.8 | CCLP | Los Angeles |
|
la.9 | CCLP | Los Angeles |
|
la.24 | CCLP | Los Angeles |
|
ny.0 | YYLP | New York |
|
ny.1 | YYLP | New York |
|
ny.8 | YYLP | New York |
|
ny.9 | YYLP | New York |
|
ny.24 | YYLP | New York |
|
atla.0 | XXLP | Atlanta |
|
atla.1 | XXLP | Atlanta |
|
atla.8 | XXLP | Atlanta |
|
atla.9 | XXLP | Atlanta |
|
atla.24 | XXLP | Atlanta |
|
chic.24 | YYLP | Chicago |
|
chic.25 | YYLP | Chicago |
|
chic.26 | YYLP | Chicago |
|
chic.27 | YYLP | Chicago |
|
The selector attributes of the Logical Port, as they appear in the OAF in Appendix A are described in Table 3-2.
The following examples illustrate different ways of using search criteria in a statement of the form:
nps selectmany SR1pLogicalPort Criteria LPLIST NUMLPS
| Search Criteria | Resulting LPLIST Entries | Comment |
|---|---|---|
srnode.srname=Chicago | chic.24, chic.25, chic.26, chich.27 | All Logical Ports on node "Chicago" match. |
srname=*la* | la.0, la.1, la.8, la.9, la.24, atla.0, atla.1, atla.8, atla.9, atla.24 | "la" and "atla" Logical Ports both match, since they contain "la". |
srname=la.? | la.0, la.1, la.8, la.9 | "la.24" does not match, since "?" matches exactly one character. |
srname=*.0/srnode.srname=Seattle | seat.0 | Returns the Logical Port on Node "Seattle",Port 0. |
The search criteria described above is specified using the character "/" to separate each AttName=AttValue criterion. If AttValue contains the character "/" itself, then the search criteria must be specified as an attribute array where each element in the array is of the form AttName=AttValue. An empty array means no criteria is specified and AttName=* is assumed for all selector attributes of the object class. The attribute array is passed by name to the nps command.
All nps commands return a termination code in the standard shell return variable "$?". A value of "0" means that the command was successful. Other values mean that the command was unsuccessful (except for the warning termination code used by some nps commands). You can test the return variable to detect errors and redirect script execution if necessary.
With nps commands, however, an nps error command is available to check for errors from the previous nps command. This command checks the value of $? and if there is an error it sends an error message to stderr and terminates the shell process.
The error message contains:
These items are also returned in environment variables which can be interrogated by your script.
There are three common ways to handle error conditions in your flow-through applications. You may need to use more than one of the following ways depending on any alternate actions you need to take.
1. For any Script Language command, by explicitly checking the termination code after the command. Example for an nps command:
if [[$? -eq 1 ]]; then echo "no items found"; else nps error; fi
2. For an nps command, by calling nps error after the command.
nps error
3. For an nps command, by setting a ksh trap condition to handle nps commands. We use this command in all subsequent examples with nps commands.
trap "nps error" ERR
CPC provides a trace facility to help follow script execution. The trace information can be written to the UNIX standard output device, stdout, or written to a UNIX file which can be interrogated using standard UNIX facilities (more, grep, etc.).
The configuration object interpreter provides the UNIX environment variable NPSMODE to control tracing. Setting this variable to the value "Trace" switches on tracing. Any other value switches it off. Tracing can be enabled and disabled for an entire script or a section of a script that is of interest.
Each nps command that is traced produces two lines of output. The first line:
Time ProcessID FileName: Command Parameter ...
is output when the command is interpreted but before it is executed. The second line:
Time ProcessID FileName: Command returns [TermCode] ReturnValues
is produced after the command is executed. In these trace lines:
You can also write text strings to the trace output using the nps trace command. This command has no effect if tracing is not enabled.
The example script from the section titled "Displaying Attributes for Multiple Objects" is duplicated below with tracing enabled around the nps read command.
#!/bin/ksh # Display all Transactions and the names of the users who # applied them. # Syntax: whoappall . $CCP_BIN/npsinit trap "nps error" ERR nps selectmany CR number=* TRLIST NUMTRS ITEM=1 while [ $ITEM -le $NUMTRS ] do nps readitem $TRLIST $ITEM TRID TRATTS export NPSMODE=Trace 1 nps trace ">>>Reading attributes of CR $CR_NUMBER" 2 nps read $TRID TRATTS export NPSMODE=Notrace 3 nps retrieve TRATTS number TRNUM nps retrieve CRATTS submittedby USER echo " Transaction $TRUM was applied by $USER" ((ITEM=ITEM+1)) done nps stop
1. Turns tracing on, with output to stdout.
2. Writes an informational text message to the trace output (stdout).
3. Turns tracing off.
Executing this script would produce the following output:
$ whoappall >>>Reading attributes of Transaction 1001 15:49:02 23067 whoappall: read SYcadChangeOrder:1001 TRATTS 15:49:04 23067 whoappall: read returns [0] TRATTS:= [domain=western briefdescription=Request to populate configs/switch220/cfg.dat scheduledate= vpn=mybank submissiondate= 1995-DEC-05 19:32:43 scheduledby= rappaport submittedby=rappaport opendate=1995-DEC-05 19:32:51 state=Succeeded approvaldate= 1995-DEC-05 19:32:48 approvedby=rappaport openedby=rappaport number=1001] Transaction 1001 was applied by rappaport >>>Reading attributes of Transaction 1002 15:49:05 23067 whoappall: read SYcadChangeOrder:1002 TRATTS 15:49:05 23067 whoappall: read returns [0] TRATTS:= [domain=western briefdescription=Request to populate configs/switch221/cfg.dat scheduledate= vpn=mybank submissiondate= 1995-DEC-05 20:10:58 scheduledby=elliot submittedby=elliot opendate= 1995-DEC-05 20:11:05 state=Succeeded approvaldate= 1995-DEC-05 20:11:03 approvedby=elliot openedby=elliot number=1002] Transaction 1002 was applied by elliot
... and so on.
In this example, trace output is sent to stdout (interspersed with the script's echoed output). This is the default operation.
To direct trace output to a file, set the environment variable NPSLOG to the name of the trace log file. If this file does not exist, it is created automatically. If the file already exists, the trace output is appended to the data already in the file each time tracing is enabled.
For example, inserting the command
export NPSLOG=tracefile.data
into the previous example script before the while loop directs trace output to a file named tracefile.data. The regular script output with the echo command continues to be sent to stdout.
You can also combine nps tracing with the standard Korn Shell debug facility (using set -x) for even more information about a running script.
As we have seen in earlier examples, Transactions are referenced by their numbers. Hence, Transactions can be found either using nps selectone or nps selectmany, or an application can access a Transaction directly using nps read if you know the Transaction object id.
Sites and Modified Objects are also objects associated with a Transaction. These objects can be accessed using the same nps commands. Their behaviors have some unique aspects as compared to that of configuration objects:
1. The object id of the owning Transaction must be supplied as one of the selection criteria in an nps selectone or nps selectmany command.
2. The object id returned by nps readitem on a Site list is not usable in subsequent commands-- that is, nps read, nps create, nps modify, nps delete, readmodes, nps modifymodes can not be applied to Sites.
3. The object id returned by nps readitem on an item in an Modified Objects list is the object id of the configuration object itself. An nps readreturns the attributes of the configuration object whereas an nps readitem returns the columns from the Modified Objects list.
The following script lists the Modified Objects for a specified Transaction.
#!/bin/ksh # Display the updated objects for this Transaction # Syntax: updates <Transaction#> # <Transaction#> = number of the Transaction . $CCP_BIN/npsinit trap "nps error" ERR nps selectone CR number=$1 TRID 1 nps selectmany Modified CR=$TRID UPDLIST NUMITEMS 2 echo "The following objects were updated by Transaction $1:" ITEM=1 while [ $ITEM -le $NUMITEMS ] do nps readitem $UPDLIST $ITEM UPDID ATTRIBUTES 3 nps retrieve ATTRIBUTES name NAME nps retrieve ATTRIBUTES description TYPE nps retrieve ATTRIBUTES domain MD nps retrieve ATTRIBUTES vpn VPN nps retrieve ATTRIBUTES pendingoperation ACTION echo " $TYPE ($NAME) Customer=$VPN Domain=$MD was $ACTION" (ITEM=ITEM+1)) done nps stop
1. The nps selectone is necessary to obtain the object id of the Transaction.
2. This command returns the elements of the Modified Objects list into the list object "UPDLIST". Note that the only search criterion supplied is the Transaction object id.
3. The nps readitem command extracts the selector attributes of each Modified Objects list item. The subsequent nps retrieve commands extract each desired attribute value.
Running this script produces a result similar to the one below:
$ updates 2003 The following objects were updated by Transaction 2003: Xyz FR-FR PVC Profile (Gold) Customer= Domain= was Created Xyz FR-FR PVC Profile (Silver) Customer= Domain= was Created Xyz FR-FR PVC Profile (Bronze) Customer= Domain= was Created
Consistent with using an interactive session, a flow-through application updates configuration objects within the context of a Transaction. The general approach is to use the procedure outlined in the table below:
| Step | Operation | Using Script Language Command(s) |
|---|---|---|
1 | Create and open a Transaction. | AVcr start |
2 | Create, modify, or delete appropriate configuration objects. | nps create, nps modify, nps delete, ... |
3 | Close the Transaction of Step 1. | AVcr close TransactionNum |
4 | Schedule or Apply the Transaction of Step 1. | AVcr apply TransactionNum applytime=<yyyy-mm-dd hh:mm> or AVcr apply TransactionNum |
Through the Script Language, you may perform the following updates:
Objects and their attributes which are uploaded or provisioned through Service objects should not be updated using a flow-through application (with a few exceptions as noted above). This holds similarly true when using an interactive session. Note that when creating a test database, of course all configuration objects can be updated.
Each Script Language command that updates the database saves the object before it returns control to the flow-through application. (Unlike the GUI, Save is not a separate user operation).
It is possible for a flow-through application to make a number of changes to the database and then fail before all required changes are made. In this case the database, while not corrupt, is nonetheless inconsistent. You may use abandon to remove any database updates defined for that Transaction.
CPC manipulates configuration objects within the context of a Transaction. Configuration objects can only be changed when a Transaction is open, and pending versions of the configuration objects are created which contain the changes.
CPC has commands to manage Transactions using the AVcr command (for example, commands to create, schedule, apply, abort, abandon and delete Transactions.) With the exceptions of schedule and abort, the AVcr command waits for the operation to complete. If the command is successful, a termination code of zero is used; otherwise, a non-zero code is returned. Most changes that move a Transaction to a new state are only valid when the Transaction is in a specific initial state. The table below lists the state-change commands, the required initial state, and the resulting state. All of these commands pass a Transaction number as input.
| Command | Initial Transaction State | Resulting Transaction State |
|---|---|---|
AVcr create | Not applicable | Ready |
AVcr start | Not applicable | Current |
AVcr schedule | Ready | Scheduled |
AVcr abort | Scheduled | Busy then Ready |
AVcr apply | Ready | Scheduled then Busy then Applied, Busy then Applied, or Busy then Alert then Busy then Abandoned |
AVcr open | Ready | Current |
AVcr close | Current | Ready |
AVcr delete | Applied or Abandoned or Ready | Not applicable |
AVcr abandon | Ready or Current | Busy then Abandoned |
AVcr commit | Ready | Busy then Abandoned or Applied (Does not apply to GUI) |
The nps create command is used to create the pending new version of a configuration object. To create a new configuration object, supply the class of the object, all mandatory attributes and any other read-write attributes as desired. The mandatory attributes include required relationships (for example, the immediate parent) and any attributes that are needed to uniquely identify the object, such as its name. These attribute values are provided to nps create using an attribute array. The array can be built either by name or by index. The order of items in the array you provide is not important, since attributes are referred to by their names. Attribute value assertions of the form "name=" set the target attribute to a null value.
If the nps create command specifies the object's profile as well as other attributes, then the profile is always applied first no matter where it appears in the attribute array. This ensures that any specified attributes are not overridden.
If an nps create command attempts to set any read-only attributes, the command will succeed but the read-only attributes will not be set (only the read-write attributes will be set). The values of the read-only attributes will instead be taken from the object's default profile. The command will return the termination code 17028 as a warning that some attributes were not set as requested. This feature allows you to copy an object by simply issuing a nps read against an existing object and then using the resulting attribute array in a subsequent nps create.
When you create a profile object, all of the object's attribute modes are set according to the default profile.
The following example creates new FR-FR PVC Profiles.
#!/bin/ksh # Create FR-FR PVC Profiles # Syntax: newfrpvcprof . $CCP_BIN/npsinit trap "nps error" ERR # Create and open a Transaction TRID=$(AVcr start "descr=Create new FR-FR PVC Profiles - Gold,\ Silver, Bronze" 2>/dev/null) 1 # Define the Gold profile set -A ATTS sy_profname="Gold" az_cir=768 az_bc=768 az_be=768 \ za_cir=768 za_bc=768 za_be=768 xxfwdpriority="High" \ xxrevpriority="High" srpriority=100 nps create XXPVPVCProf ATTS PROFID 2 echo "FR-FR PVC Profile: Gold created." # Define the Silver profile # done similarly # Define the Bronze profile # done similarly # Close and apply the Transaction for processing AVcr close $TRID 2>/dev/null 3 AVcr apply $TRID 2>/dev/null 4 echo "Transaction $TRID has been applied for processing." nps stop
1. The AVcr start command creates and opens a new Transaction. This command returns the Transaction number in variable "TRID".
2. With the open Transaction, configuration objects (including profiles) can be updated.
3. The AVcr close command closes the Transaction.
4. The AVcr apply command applies the Transaction so that the profiles are available for other session. The AVcr schedule command can also be used after closing the Transaction to schedule if for a later time and date.
The following example demonstrates the use of the AVcr schedule command.
# Close and schedule the Transaction for processing AVcr close $TRID 2>/dev/null 1 AVcr schedule $TRID scheduletime="1999/12/01 10:00 2 echo "Transaction $TRID has been scheduled for processing." nps stop
1. The AVcr close command closes the Transaction.
2. The AVcr schedule command applies the Transaction at the time scheduled by "scheduletime".
|
Note Scheduletime is mandatory and it must be entered in the precise YYYY/MM/DD HH:MM format. |
An nps modify command is used to modify a configuration object. This command creates a pending modify version of the configuration object unless the object was previously created in the same Transaction, in which case the modifications are applied to the already existing pending add version.
Modified attribute values are supplied to nps modify in an attribute array. Attributes which are not included in the array are left unchanged in the target object. You can build attribute arrays for nps modify operations either by name or by index. The order of array items is not important. Only read-write attributes may appear in the array. Attribute value assertions of the form "name=" set the target attribute to a null value.
If the nps modify command specifies the object's profile as well as other attributes, then the profile is always applied first no matter where it appears in the attribute array. This ensures that any specified attributes are not overridden.
If an nps modify command attempts to set any read-only attributes, the command will succeed but the read-only attributes will not be set (only the read-write attributes will be set). The command will return the termination code 17028 as a warning that some attributes were not set as requested.
To modify a profile's attribute modes use the nps modifymodes command.
The following example modifies an attribute value and an attribute mode of the specified FR-FR PVC Profile(s). It assumes that the user already has a Transaction in the Current state.
#!/bin/ksh # Modify an attribute of one or more FR-FR PVC Profiles # Syntax: modfrpvcprof <criteria> <attr value assertion> # <attr value assertion> # where # <criteria> select the profile(s) to be modified # <attr value assertion> is the attribute and its new value # <attr value assertion> is the attribute and its new mode . $CCP_BIN/npsinit trap "nps error" ERR # Get the list of objects that fit the search criteria nps selectmany XXPVPVCProf $1 PROFLIST NUMPROFS ITEM=1 while [ $ITEM -le $NUMPROFS ] do nps readitem $PROFLIST $ITEM PROFID ATTS nps retrieve ATTS sy_profname PROFNAME set A ATTR $2 nps modify $ATTR set -A MODE $3 nps modifymodes $PROFID MODE echo "Modified FR-FR PVC Profile $PROFNAME" ((ITEM=ITEM+1)) done nps stop
The nps delete command creates a delete pending version of the specified configuration object.
Just as CPC supports upload on certain configuration objects through an interactive session, it also supports upload through a flow-through application. When an upload function is specified on an object, the object and its contained objects are uploaded from the network into the CPC database.
CPC provides an nps upload command which identifies the object or list of objects to upload, and supplies the upload values in an attribute array. These upload attributes correspond to those entered through the upload dialog viewer when the upload is requested from the GUI.
When the upload is complete, the nps upload command returns. If the upload is successful, then the Upload Request object identifier is returned. If the upload is unsuccessful, then an Upload Request of "" is returned.
The list of objects that can be uploaded, the corresponding upload attributes and the upload procedures and commands used vary depending on the Equipment Module. Please refer to your specific CPC guides for more information.
Remember that an upload does not require the context of a Transaction.
The following script uploads a new node object and its contained objects for a specific Equipment Module. The Equipment Module's Event Logger can be written to invoke this flow-through application when an event is received that a new node has been added in the network.
#!/bin/ksh # Uploads a new node and its contained objects - first and # and then service elements # Syntax: uploadnewnode <network_name> <node_name> export NPSNEWSESSION=1 1 . $CCP_BIN/npsinit trap "nps error" ERR echo "Uploading fabric and service for Node $2 in Network $1" # Upload new node (without a Transaction) - fabric first set -A ATTS "UploadType=UPLOAD FABRIC" "srnetwork.srname=$1"\ "srname=$2" "srnetwork.xxupnode=hektor" "srnetwork.xxupuser==sa"\ "Password=XXX" nps upload XXNDNodeList:0 ATTS URID 2 echo "Fabric upload request is: $URID" # Upload new node (without a Transaction) - service elements # next set -A ATTS "UploadType=UPLOAD SERVICE" "srnetwork.srname=$1"\ "srname=$2" "srnetwork.xxupnode=hektor" "srnetwork.xxupuser=sa"\ "Password=XXX" nps upload XXNDNodeList:0 ATTS URID 3 echo "Service upload request is: $URID" nps stop
1. Each upload should be performed in its own session.
2. For this example Equipment Module, a new node is uploaded by using the nps upload command on the list id class "XXNDNodeList:0". The node is identified by "srname" within the network "srnetwork.srname". Both upload commands use this node information to create the node and upload the fabric, and then to identify the node to upload the service elements.
In all of the commands discussed previously, the versions of the configuration objects retrieved or modified by a Script Language command are dependent on the current Transaction. The Script Language command nps selectallversions, however, permits you to retrieve all existing versions of a configuration object.
nps selectallversions creates a list of versions of a configuration object with a specified object id. Both pending and current versions of the object are returned when they exist. Like nps selectmany, the nps selectallversions command returns the number of items in the list and a list id that you can use in a subsequent nps readitem. The flow-through application can determine the version of a particular list item from the object's "sy_version" attribute.
NNI resiliency is supported through a flow-through application just as it is supported through an interactive session. For information on NNI resiliency concepts, refer to the Cisco Provisioning Center User Guide.
CPC provides java ServiceUtility commands which identify the failed link object and instruct it to re-thread, recover, or re-balance the link or group of links.
The java ServiceUtility command set includes:
Where linkfail invokes the resiliency policy for the failed link identified by OId, linkrecover invokes the resiliency policy for the recovered link identified by OId, and linkrebalance invokes the resiliency policy to allow manual adjustment of the load across links in the same group as the link identified by OId.
The NNI resiliency functions operate on a link identified by its object id. Use the nps selectone or nps selectmany commands to determine the object id of the desired link.
Each NNI resiliency command automatically creates its own Transaction and session context. The flow-through application must ensure that no other Transaction is open before invoking an NNI resiliency command.
The following script re-threads failed links.
#!/bin/ksh # Re-thread failed links # Syntax: rethread <criteria> # where # <criteria> select the link(s) to be re-threaded . $CCP_BIN/npsinit trap "nps error" ERR alias -x rethreadlink=\ "java com.syndesis.resiliency.ServiceUtility linkfail" nps selectmany SRlnLink $1 LINKLIST NUMLINKS ITEM=1 while [ $ITEM -le $NUMLINKS ] do nps readitem $LINKLIST $ITEM LINKID ATTS rethreadlink $LINKID 2>/dev/null ((ITEM=ITEM+1)) done nps stop
Executing this script with an example database produces the following result:
$ rethread sra_tp.srnode.srname=Floyd/sra_tp.srname=3.2/srz_tp.srnode.srname=Node5/srz_tp.srname=OC3IR-S1-C4-D1 linkfail completed successfully
Customers can augment the threader algorithm by adding their own callout Java code. The custom callout is a customized algorithm, which can be used to adjust the priorities of a path before the Threader implements one. CPC takes the custom callout into account when determining an optimum path for a Service. The priorities set for a custom callout will influence the Threader path. The custom callout can include attributes selected from the endpoint and intermediate Logical Ports, from Links and from Service Objects.
For more information on the Custom Threader, refer to the the Cicso Provisioning Center User Guide.
These are the attributes the custom callout can use:
domain | vpn | srprofile.sy_profname |
srseprofile | servicelabel | policy |
rful | rfu2 |
|
srname | srnode.srname | srnode.srnetwork.srname |
domain | srnode.srcost | srnode.srnetwork.srcost |
vpn | srnode.srarea | srnode.srnetwork.sropaque |
srprotocol | srnode.srgeoloc | srusage.sraz_bandwidth_a |
sradminstatus | srnode.srgeoloc | srusage.sraz_bandwidth_a |
|
| srusage.srconnections_a |
srcost | srpolicy1 | srusage.sraz_bandwidth_a [*] |
sradminstatus[*] | srpolicy2 | srusage.srza_bandwidth_a [*] |
|
| srusage.srconnections_a [*] |
[*] only for virtual links
A custom callout would contain the following Java commands:
import comp.syndesis.frrm.FRCustom;
public class myCusteromCallout implements FRCustom{
public void setWeights (Attributes service, Vecotr paths, int weight [ ]) throws
Exception {
//custom code goes here
}
}
Now that configuration objects have been completely covered, let's start talking about Service objects.
Service objects can be retrieved using the java SOClass list command or by using the java SOClass view command if you know the Service object id.
With the java SOClass list command, it is possible to specify criteria to list specific Services matching the criteria (as defined in section 3.7, except white space is used as the delimited between criterion instead of "/". It is also possible to specify the first Service object (using the argument SOFirst) and the maximum number of Service objects to be returned (using the argument SOMax). The default list size is 100 Service objects. (Unlike the GUI, the Script Language provides a mechanism to specify the SOFirst to the SOFirst + SOMax - 1 objects to retrieve from the list.)
Transactions and service element components are objects associated with a Service. These objects can be accessed using flow-through applications. The command java SOClass view is used to return the attributes of the Service object (including the Transactions used to create and last modify the Service) and java SOClass details is used to list the components of a Service object.
The following flow-through application lists the Transactions and displays the service element components associated with a specified Service:
#!/bin/ksh # List Transactions and service element components associated with # a specific Service object # Syntax: inspectSO <SOClass> <ServiceOId> # where <SOClass> is the SO's Java class, # e.g., com.syndesis.frrm.RFsvServiceObject # <ServiceOId> is the SO's sy_objectid # e.g., RFsvServiceObject:1124 alias soview="java com.syndesis.activator.Activator $1 view" alias sodetails="java com.syndesis.activator.Activator $1 details" soview AVsession=VM AVcr=none sy_objectid=$2 sodetails AVsession=VM AVcr=none sy_objectid=$2
Running this application produces a result similar to the one below:
1 NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17135) - port(38365) [srcreatecoid=SYcadChangeOrder:3202 srcreatetime=1998-NOV-17 13:23:08 sy_changeorderid=SYcadChangeOrder:3202 recoveryprio=5 sy_objectid=RFsvServiceObject:1124 rfu5= rfu4= sy_modifieddate=1998-NOV-17 13:24:47 rfu3= rfu2= rfu1= za_be=5 vpn=Acme za_bc=5 srcurrenttime=1998-NOV-17 13:23:08 z_dlci=16 srprofile=RFsvServiceObjectProf:1000 sy_committeddate=1998-NOV-17 13:24:47 component=SRnbNetworkConnection:1141 sy_createddate=1998-NOV-17 13:23:11 name=fr-eh-1 za_cir=5 priority=Low srseprofile=Gold a_tp=L9001/FT1-3-1-1 srcurrentoid=SYcadChangeOrder:3202 az_be=5 servicelabel= az_bc=5 domain= az_cir=5 z_tp=Floyd.Otis/6.1.1 a_dlci=16] 2 NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17140) - port(38372) [sra_tp.srnode.srname=L9001 sy_objectid=XXPVPVC:1091 srnetwork=XXNTNetwork:1004 srz_tp.srnode=XXNDNode:1004 srz_tp.srnode.srname=L9001 sra_tp.srnode=XXNDNode:1004 sra_tp=XXFLLport:1013 srz_tp=XXFLLport:1015 srz_tp.srname=FT1-3-3-1 sra_tp.srname=FT1-3-1-1 srnetwork.srname=Xyz_Network_2] [sy_objectid=SRlnLink:1022] [sra_tp.srnode.srname=L9002 sy_objectid=XXPVPVC:1092 srnetwork=XXNTNetwork:1003 srz_tp.srnode=XXNDNode:1003 srz_tp.srnode.srname=L9002 sra_tp.srnode=XXNDNode:1003 sra_tp=XXFLLport:1010 srz_tp=XXFLLport:1012 srz_tp.srname=FT1-3-4-1 sra_tp.srname=FT1-3-2-1 srnetwork.srname=Xyz_Network_1] [sy_objectid=SRlnLink:1024] [sra_tp.srnode.srname=Floyd.Otis sy_objectid=YYFCFRPvc:1027 srnetwork=YYNTNetwork:1006 srz_tp.srnode=YYNDNode:1008 srz_tp.srnode.srname=Floyd.Otis sra_tp.srnode=YYNDNode:1008 sra_tp=YYFLFRLport:1007 srz_tp=YYFLFRLport:1009 srz_tp.srname=6.1.1 sra_tp.srname=6.3.1 srnetwork.srname=YY_NETWORK1]
1. These are the attributes of the Service object produced by java SOClass view. The Transaction that created the Service object is identified by attribute srcreatecoid with a Transaction number of 3202. The Transaction that last modified the Service object is identified by attribute srcurrentoid with the same Transaction number 3202. This Service object has been created by Transaction 3202 but has never been further modified. The dates and times when these Transactions were opened can be retrieved from attributes srcreatetime and srcurrenttime.
2. These are the components of the Service object produced by java SOClass details. This Service object is composed of 3 Network Connections with Link Connections between.
Along with displaying the attributes of a Service object, the Script Language provides the capability to display attribute modes of the Service object.
#!/bin/ksh # List Transactions and service element components associated # with a specific Service object - including attribute modes # Syntax: inspectSO <SOClass> <ServiceOId> # where <SOClass> is the SO's Java class # e.g., com.syndesis.frrm.RFsvServiceObject # <ServiceOId> is the SO's sy_objectid # e.g., RFsvServiceObject:1124 alias soview="java com.syndesis.activator.Activator $1\ viewWithModes" soview AVsession=VM AVcr=none sy_objectid=$2
Running this application produces a result as below:
1 NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17135) - port(38365) [~srcreatecoid=r srcreatecoid=SYcadChangeOrder:3202 ~srcreatetime=r srcreatetime=1998-NOV-17 13:23:08 ~za_bc=rw ~domain=r ~az_cir=rw ~servicelabel=rw ~sy_createddate=r sy_changeorderid=SYcadChangeOrder:3202 ~recoveryprio=rw recoveryprio=5 ~sy_objectid=r sy_objectid=RFsvServiceObject:1124 ~rfu5=rw ~rfu4=rw rfu5= rfu4= ~sy_committeddate=r ~az_be=rw sy_modifieddate=1998-NOV-17 13:24:47 ~rfu3=rw ~rfu2=rw ~rfu1=rw rfu3= rfu2= rfu1= ~az_bc=rw za_be=5 vpn=Acme za_bc=5 ~srcurrenttime=r srcurrenttime=1998-NOV-17 13:23:08 ~z_dlci=rw z_dlci=16 ~srprofile=rw srprofile=RFsvServiceObjectProf:1000 sy_committeddate=1998-NOV-17 13:24:47 ~component=rw component=SRnbNetworkConnection:1141 ~sy_changeorderid=r ~vpn=r sy_createddate=1998-NOV-17 13:23:11 ~name=rw name=fr-eh-1 za_cir=5 priority=Low ~sy_modifieddate=r ~srseprofile=rw srseprofile=Gold ~a_tp=rw a_tp=L9001/FT1-3-1-1 ~srcurrentoid=r srcurrentoid=SYcadChangeOrder:3202 az_be=5 servicelabel= az_bc=5 ~za_cir=rw domain= az_cir=5 ~priority=rw ~za_be=rw ~z_tp=rw z_tp=Floyd.Otis/6.1.1 ~z_dlci=rw a_dlci=16]
1. Modes are displayed as "r" for read-only and "rw" for read-write. These modes correspond to the attribute field modes displayed on the Service object's window. Note that attribute modes are defined with a prefix of "~" before the attribute name.
The argument AVformatter is used to specify the formatter option. Not specifying any AVformatter argument on the java SOClass command line is equivalent to specifying AVformatter=com.syndesis.activator.DefaultFormatter.
Check with your specific Service Application guide for information on any other formatter classes.
Using AVformatter=com.syndesis.activator.SimpleFormatter in the above example from the section titled "Querying Service Objects" produces the result below (comparing this to the default formatter, all values are now in quotes):
1 NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17160) - port(38412) [srcreatecoid="SYcadChangeOrder:3202" srcreatetime="1998-NOV-17 13:23:08" sy_changeorderid="SYcadChangeOrder:3202" recoveryprio="5" sy_objectid="RFsvServiceObject:1124" rfu5="" rfu4="" sy_modifieddate="1998-NOV-17 13:24:47" rfu3="" rfu2="" rfu1="" za_be="5" vpn="Acme" za_bc="5" srcurrenttime="1998-NOV-17 13:23:08" z_dlci="16" srprofile="RFsvServiceObjectProf:1000" sy_committeddate="1998-NOV-17 13:24:47" component="SRnbNetworkConnection:1141" sy_createddate="1998-NOV-17 13:23:11" name="fr-eh-1" za_cir="5" priority="Low" srseprofile="Gold" a_tp="L9001/FT1-3-1-1" srcurrentoid="SYcadChangeOrder:3202" az_be="5" servicelabel="" az_bc="5" domain="" az_cir="5" z_tp="Floyd.Otis/6.1.1" a_dlci="16"] NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17165) - port(38418) [sra_tp.srnode.srname="L9001" sy_objectid="XXPVPVC:1091" srnetwork="XXNTNetwork:1004" srz_tp.srnode="XXNDNode:1004" srz_tp.srnode.srname="L9001" sra_tp.srnode="XXNDNode:1004" sra_tp="XXFLLport:1013" srz_tp="XXFLLport:1015" srz_tp.srname="FT1-3-3-1" sra_tp.srname="FT1-3-1-1" srnetwork.srname="Xyz_Network_2"] [sy_objectid="SRlnLink:1022"] [sra_tp.srnode.srname="L9002" sy_objectid="XXPVPVC:1092" srnetwork="XXNTNetwork:1003" srz_tp.srnode="XXNDNode:1003" srz_tp.srnode.srname="L9002" sra_tp.srnode="XXNDNode:1003" sra_tp="XXFLLport:1010" srz_tp="XXFLLport:1012" srz_tp.srname="FT1-3-4-1" sra_tp.srname="FT1-3-2-1" srnetwork.srname="Xyz_Network_1"] [sy_objectid="SRlnLink:1024"] [sra_tp.srnode.srname="Floyd.Otis" sy_objectid="YYFCFRPvc:1027" srnetwork="YYNTNetwork:1006" srz_tp.srnode="YYNDNode:1008" srz_tp.srnode.srname="Floyd.Otis" sra_tp.srnode="YYNDNode:1008" sra_tp="YYFLFRLport:1007" srz_tp="YYFLFRLport:1009" srz_tp.srname="6.1.1" sra_tp.srname="6.3.1" srnetwork.srname="YY_NETWORK1"] Using AVformatter=com.syndesis.activator.TNDetailsFormatter in the above example of section 3.15 produces the result below (comparing this to the simple formatter, only the output from the java SOClass details is different: attributes of each component are ordered, object ids are not in quotes, and attribute names have been removed): NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17176) - port(38461) [srcreatecoid="SYcadChangeOrder:3202" srcreatetime="1998-NOV-17 13:23:08" sy_changeorderid="SYcadChangeOrder:3202" recoveryprio="5" sy_objectid="RFsvServiceObject:1124" rfu5="" rfu4="" sy_modifieddate="1998-NOV-17 13:24:47" rfu3="" rfu2="" rfu1="" za_be="5" vpn="Acme" za_bc="5" srcurrenttime="1998-NOV-17 13:23:08" z_dlci="16" srprofile="RFsvServiceObjectProf:1000" sy_committeddate="1998-NOV-17 13:24:47" component="SRnbNetworkConnection:1141" sy_createddate="1998-NOV-17 13:23:11" name="fr-eh-1" za_cir="5" priority="Low" srseprofile="Gold" a_tp="L9001/FT1-3-1-1" srcurrentoid="SYcadChangeOrder:3202" az_be="5" az_bc="5" servicelabel="" domain="" az_cir="5" z_tp="Floyd.Otis/6.1.1" a_dlci="16"] NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17181) - port(38468) [XXPVPVC:1091 "Xyz_Network_2" XXNTNetwork:1004 "L9001" XXNDNode:1004 "FT1-3-1-1" XXFLLport:1013 "L9001" XXNDNode:1004 "FT1-3-3-1" XXFLLport:1015] [SRlnLink:1022] [XXPVPVC:1092 "Xyz_Network_1" XXNTNetwork:1003 "L9002" XXNDNode:1003 "FT1-3-2-1" XXFLLport:1010 "L9002" XXNDNode:1003 "FT1-3-4-1" XXFLLport:1012] [SRlnLink:1024] [YYFCFRPvc:1027 "YY_NETWORK1" YYNTNetwork:1006 "Floyd.Otis" YYNDNode:1008 "6.3.1" YYFLFRLport:1007 "Floyd.Otis" YYNDNode:1008 "6.1.1" YYFLFRLport:1009]
A flow-through provisioning application (like the GUI) must maintain the Transaction context. The java SOClass commands support two modes of operation. CPC has the ability to automatically create Transactions itself for each unit of work, or to batch multiple units of work together in a single Transaction. In automatic mode the flow-through application need not worry about the Transaction because CPC manages the Transaction for each java SOClass command: CPC creates and opens a new Transaction before the operation dictated by the command is executed and then closes and applies the Transaction after the operation completes successfully (or abandons the Transaction if the operation fails). In batch or manual mode, however, the flow-through application manages the Transaction--it must create a Transaction, perform its java SOClass command updates, and then finally apply or abandon the Transaction.
With the automatic mode, a Service object can be created, modified and deleted using the general approach.
Step 2 Create, modify, or delete appropriate Service objects using atomic mode (or auto mode) in the session indicated by Step 1.
java SOClass create AVcr=atomic
AVsession=SessId|VM AVdescription=Descr AVmd=MD AVvpn=VPN, java SOClass modify AVcr=atomic
AVsession=SessId| VM AVdescription=Descr AVmd=MD AVvpn=VPN, java SOClass delete AVcr=atomic
AVsession=SessId|VM AVdescription=Descr AVmd=MD AVvpn=VPN
Step 3 Delete the session created in Step1. Exit application.
By using AVcr=atomic, the Service object creates and opens a new Transaction and throws an error if a Transaction is already open in the session. By using AVcr=auto, the Service object uses the Transaction open in the current session if there is one and if not automatically creates and opens a new Transaction.
With the manual mode, a Service object can be created, modified and deleted using the following approach:
Step 2 Create and open a Transaction in the session indicated by Step 1. Use Script Language Command Vcr start [SessId|Display|VM].
Step 3 Create, modify or delete appropriate Service objects using manual mode (for example, AVcr=current) in the session indicated by Step 1.
java SOClass create AVcr=current
AVsession=SessId|VM java SOClass modify AVcr=current
AVsession=SessId|VM java SOClass delete AVcr=current
AVsession=SessId|VM
Step 4 Close the Transaction of step 2 in the session indicated by step 1. Use Script Language Command AVcr close TransactionNum [SessId|Display|VM].
Step 5 Apply the Transaction of Step 2 in the session indicated by step 1.Use Script Language Command AVcr apply TransactionNum [SessId|Display|VM]. Or, Schedule the Transaction of step 2 in the session indicated by step 1.Use Script Language Command AVcr schedule Transaction Num scheduletime=<yyy-mm-dd hh:mm [SessId|Display|VM].
Step 6 Delete the session created in step 1.exit application.
By using AVcr=current, the Service object uses the Transaction open in the current session if there is one, or none at all.
|
Note The commands java SOClass createWithmodes and java SOClass modifyWithmodes may be used instead to create and modify a Service object, respectively. The difference with these commands and the above mentioned java SOClass create and java SOClass modify is that the former also returns the Service object's attribute modes, as seen in the example of the section titled "Querying Service Objects." |
As you saw in the previous section, a Service object is updated within the context of a Transaction and session, using the AVcr and the AVsession attributes, respectively. These attributes are passed to the Service object when it is invoked. The Service object assumes that the session exists, and opens the Transaction if required.
A Service object can manage Transactions on behalf of the service. It can use a currently open Transaction, open an existing one or create and open a new one. Commands which do not modify anything (for example, java SOClass list java SOClass listProfile, view, java SOClass view, java SOClass viewProfile, java SOClass viewWithModes, java SOClass details) can run without an open Transaction.
When running with a Transaction, the Service object ensures that the state of the Transaction before the Service object is invoked is left unchanged by the operation of the Service object. If the Service object creates a Transaction then it will apply it at the end of processing. If the Service object opens a Transaction then it will close it at the end of processing. If the specified Transaction cannot be opened, then the Service object aborts the operation and returns an error. If the Transaction was already open it will normally be left open. If an error occurs during processing then the Service object will automatically close and abandon the Transaction regardless of who created or opened it.
When creating a new Service, all mandatory attributes for that Service must be specified. The mandatory attributes include at least the addressing information (the endpoint identifiers) in which the service is provisioned. For any other attributes the values must be either specified or take on the defaults assigned by the Service profile. Once the Service is created, the attributes of the new Service are returned along with the attribute sy_objectid. This attribute is the object id for the Service and is used in subsequent Script Language commands to identify the Service object.
When modifying an existing Service, the sy_objectid or the name (if the Service object has the name attribute) must be specified in the attribute array as mentioned above to identify which Service object to modify. Along with the sy_objectid or name, other attributes that require changing must also be specified.
When deleting an existing Service, the sy_objectid or the name (if the Service object has the name attribute) must again be specified in the attribute array.
As you can see, all attributes of a Service can be set and read through the Script Language. All attribute modes of a Service can be read through the Script Language but not set since the Service profile defines the attribute modes. All associations to the Service's components and Transactions are set automatically by the Service object, and can be read using the Script Language. Once all database updates are complete, the Script Language command returns control to the caller. If the command is successful, a termination code of 0 is returned; otherwise, a non-zero termination code is returned.
Additional commands may exist for a specific Service object. Also for information on the mandatory attributes and attributes that may be modified, please refer to the Cisco Provisioning Center User Guide.
The following flow-through application creates a Service object in automatic mode. This application can be enhanced so that it is called with the attributes of the new Service.
#!/bin/ksh # Creates a Frame Relay Service object in automatic mode # Syntax: createfrso # Start session and get its id AVtm wait |& 1 PROCESSID=S! echo "pid is $PROCESSID" read -p SESSID echo "Session id is $SESSID" # create aliases for SO commands alias frcreate="java com.syndesis.activator.Activator \ com.syndesis.frrm.RFsvServiceObject create" # create Frame Relay Service object with Service profile "Gold" and # service element profile "Gold" if frcreate AVsession=$SESSNUM AVcr=auto \ 2 AVdescription="Create FR SO L9002/FT1-3-1-1:L9001/FT1-3-1-1" name=L9002/FT1-3-1-1:L9001/FT1-3-1-1 \ a_tp=L9002/FT1-3-1-1 z_tp=L9001/FT1-3-1-1 \ priority=Low; then echo "Create FR Service Object successful." else echo "Create FR Service Object failed." fi # end session kill $PROCESSID 3
1. The AVtm command provides an interface to create and manage sessions. The AVtm wait command creates a new session to be used in later Script Language commands, as seen in. The session is specified by a decimal number and is saved in variable "SESSID". The AVtm command creates a session process and does not terminate until 3.
2. The java SOCLass commands take the session argument AVsession and the Transaction argument AVcr which specifies the context in which they do their work. When a Service profile is specified, the profile is always applied first no matter where it appears on the command line: this ensures that any specified arguments are not overridden. A Service profile can be specified using attribute srprofile.sy profname with the name of the profile, using an alias attribute profilename with the name of the profile, or by using attribute srprofile with the profile's object id.
3. On exit, the process is deleted. "kill $PROCESSID" sends a SIGTERM which explicitly kills the process specified by "$PROCESSID".
Output from the above flow-through application is:
NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(28314) - port(41181) [srcreatecoid=SYcadChangeOrder:3241 srcreatetime=1998-NOV-19 10:16:13 sy_changeorderid=SYcadChangeOrder:3241 recoveryprio=5 sy_objectid=RFsvServiceObject:1127 rfu5= rfu4= sy_modifieddate=1998-NOV-19 10:16:50 rfu3= rfu2= rfu1= za_be=10 vpn= za_bc=10 srcurrenttime=1998-NOV-19 10:16:13 z_dlci=17 srprofile=RFsvServiceObjectProf:1001 sy_committeddate= component=SRnbNetworkConnection:1144 sy_createddate=1998-NOV-19 10:16:14 name=L9002/FT1-3-1-1:L9001/FT1-3-1-1 za_cir=10 priority=Low srprofile=Gold a_tp=L9002/FT1-3-1-1 srcurrentoid=SYcadChangeOrder:3241 az_be=10 servicelabel= az_bc=10 domain= az_cir=10 z_tp=L9001/FT1-3-1-1 a_dlci=18] Create FR Service Object successful.
The above flow-through application creates a new session using the AVtm command. If you need to initialize, run, and terminate in separate scripts you could create the session and write it out (along with its process id) to a temporary file:
AVtm wait > /tmp/AVSID 2>/dev/null & echo " $!" >> /tmp/AVSID
and then when you need to access the session or process id use:
read </tmp/AVSID SESSID PROCESSID
CPC can also create Service Objects at a specified time and date. The Transaction argument AVscheduletime can be used to either schedule the Transaction containing the new Service Object at a later time or immediately. Without using the argument AVscheduletime, the Transaction will apply in the foreground and will block other Transaction activity in the time that it is committing. Using AVscheduletime="now" will apply the Transaction in the background, and no Transaction activities will be blocked.
The following examples demonstrate the use of AVscheduletime.
if frcreate AVsession=$SESSID AVcr=auto AVscheduletime="now" AVdescription="Create FR SO L9002/FT1-3-1-1:L9001/FT1-3-1-1" \ name=L9002/FT1-3-1-1:L9001/FT1-3-1-1 \ a_tp=L9002/FT1-3-1-1 z_tp=L9001/FT1-3-1-1 \ priority=Low; then echo "Create FR Service Object successful." else echo "Create FR Service Object successful." fi # end session kill 0 2
1. The Transaction Argument AVscheduletime is used along with AVcr to create a new Transaction. In this example the scheduletime value is "now," which will call AVcr to schedule the Transaction with the current time. This Transaction will process in the Background. During the time between the Ready state and the Scheduled state when the transaction is committing, other Transaction activity will not be blocked from processing. If AVscheduletime is specified with a time and date, AVcr will be called to schedule the Transaction at the specified date and time. This Transaction will also process in the Background.
2. On exist, the session is deleted, "kill 0" sends a SIGTERM which explicitly kills the session
if frcreate Avsession=$SESSID AVcr=auto \ AVscheduletime="1999/11/01 10:00" \ 1 AVdescription="Create FR SO L9002/FT1-3-1-1:L9001/FT1-3-1-1" \ name=L9002/FT1-3-1-1:L9001/FT1-3-1-1 \ a_tp=L9002/FT1-3-1-1 z_tp=L9001/FT1-3-1-1 \ priority=Low; then echo "Create FR Service Object failed." else echo "Create FR Service Object failed." fi # end session kill 0 2
1. The Transaction Argument AVscheduletime is used along with AVcr to create a new Transaction. In this example the scheduletime value is a date strong, which will call AVcr to schedule the Transaction with the time and date specified.
2. On exit, the session is deleted. "kill 0" sends a SIGTERM which explicitly kills the session.
To query and update Service object profiles, the same nps commands that apply to configuration objects and their profiles are used. See specifically the section titled "Getting Objects and their Attributes" and "Updating Configuration Objects" in Chapter 2."
The Script Language provides java SOClass commands on top of these nps commands to view and list Service profiles.
The Script Language provides the java SOClass viewProfile command to view Service object profiles. This command is similar to the java SOClass viewWithModes command, except that it is used to display a Service profile instead of a Service object. To identify the Service profile to the java SOClass viewProfile command, use the attribute sy_objectid with the object id of the Service profile, srprofile.sy_profname with the name of the Service profile or the alias attribute profilename with the name of the Service profile.
The following flow-through application displays a Service profile's attributes and modes:
#!/bin/ksh # Display the Service profile's attributes and modes # Syntax: inspectSOProfile <SOClass> <ServiceProfileOId> # where <SOClass> is the SO's Java class # e.g., com.syndesis.frrm.RFsvServiceObject # <ServiceProfileOId> is the SO's sy_objectid # e.g., RFsvServiceObjectProf:1000 alias profview="java com.syndesis.activator.Activator $1 viewProfile " profview AVcr=none sy objectid=$2
Running this application produces a result as below:
1 NPS Performer process starting Copyright 1994-1998 Syndesis Limited, Canada - pid(17135) - port(38365) [~za_bc=rw srcreatecoid=SYcadChangeOrder:3202 ~sy_profname=r ~domain=r ~az_cir=rw srcreatetime=1998-NOV-17 13:23:08 ~servicelabel=rw ~sy_createddate=r sy_changeorderid=SYcadChangeOrder:3202 ~recoveryprio=rw recoveryprio=5 sy_objectid=RFsvServiceObject:1124 ~sy_objectid=r ~sy_committeddate=r rfu5= ~az_be=rw sy_modifieddate=1998-NOV-17 13:24:47 rfu4= rfu3=~az_bc=rw rfu2= fru1= za_be=5 vpn=Acme za_bc=5 srcurrenttime=1998-NOV-17 13:23:08 =RFsvServiceObjectProf:1000 z_dlci=16 sy committeddate=1998-NOV-17 13:23:11 name=fr-eh-1 priority=Low za cir=5 srprofile.sy profname=Default ~sy_modifieddate=r ~srseprofile=Gold ~srseprofile=rw a tp=L9001/FT1-3-1-1 srcurrentoid=SYcadChangeOrder:3202 az_be=5 z_tp=Floyd.Otis/6.1.1 a d1ci=16~priority=rw ~za_be=rw]
1. Modes are displayed as "r" for read-only and "rw" for read-write. These modes correspond to the attribute field modes displayed on the Service object's window which uses this profile. Note that attribute modes are defined with a prefix of "~" before the attribute name.
The Script Language also provides the java SOClass listProfile command, to list Service profiles matching a specified criteria. With this command, it is possible to specify the first Service profile (using the argument SOFirst) and the maximum number of Service profiles to be returned (using the argument SOMax). The default list size is 100 Service profiles. (Unlike the GUI, The Script Language provides a mechanism to specify the SOFirst to the SOFirst + SOMax - 1 objects to retrieve from the list).
CPC records significant system events in a number of time-stamped logs that you can query from a flow-through application using standard UNIX file commands. These logs are:
Locations and file names of the log files are provided in the section titled "Log File Names and Locations" in Chapter 4.
Other logs may also be available. For more information refer to the Cisco Provisioning Center User Guide.
If the flow-through application is running in the same session as the GUI, the flow-through application can display object viewers or list viewers.
Once a viewer has been displayed in this manner, the GUI and the flow-through application operate independently. The user may invoke any valid user interface functions from the displayed viewers while the flow-through application continues to execute.
It is more efficient for scripts to run in the same process.
For script A to call script B such that it runs in the same process, script A executes script B as a ksh dot script using a command of the form:
For script A to call script B such that it runs in a separate process, script A executes a command of the form:
By default, each Korn Shell process that executes npsinit forks a new configuration object interpreter process. If one ksh script calls another and if each script runs in a separate process, then each script must execute npsinit to create a new configuration object interpreter. Otherwise, the npsinit ignores subsequent invocations of itself from within the same process.
Sessions should be created sparingly. Every time a session is created, a new set of log output files are created.
When working with configuration object commands, objects may not need to be retrieved into memory. After creating a list of objects (through an nps selectmany, nps selectallversions, or nps reselectmany), a specific object does not need to be retrieved (using nps read) if the attributes are available in the list (using nps readitem). To determine the available attributes, either:
Posted: Thu Aug 3 16:18:30 PDT 2000
Copyright 1989-2000©Cisco Systems Inc.