To display the name of the log file, enter show ncl logfile. For Digital UNIX, the utility returns the default log file name if one was not previously set. For OpenVMS, the default file extension for an NCL log file is .ncl. The utility returns an error message if a log file does not exist.
Use the disable ncl logging command at any time to turn off NCL logging or to exit NCL.
You can execute commands saved in an NCL log file during subsequent NCL utility sessions. However, you must ensure that the proper context for the commands in the log file has been established. Check the contents of an NCL log file before running it in later utility sessions.
Under normal conditions, you can identify the remote node by name in the NCL command. However, if the name service is interrupted or unavailable, you can still reach remote nodes to perform management functions. You can use either the remote node's Phase IV address (if the remote node is configured to have one), or the remote node's network services access point (NSAP). Refer to the "Understanding and Creating NSAP Addresses" chapter in the DECnet-Plus Planning Guide for Digital UNIX or OpenVMS NSAP format to use.
For example, the following commands all perform the same function:
ncl> show node 12.5 routing circuit syn-0-0
For a Digital UNIX system:
ncl> show node 49::00-0C:AA-00-04-00-05-30:20 routing circuit syn-0-0 ncl> show node %X49000CAA000400053020 routing circuit syn-0-0
For an OpenVMS system:
ncl> show node net$49000CAA000400053020 routing circuit syn-0-0
The following sections briefly describe a set of NCL commands supported by most network management entities:
These commands have the same effect on any entity to which they are applied; they are described here to prevent unnecessary repetition throughout the book.
In addition to these NCL commands, there are a number of commands that apply only to specific entities; for example, the rename command for the Node entity, or the dump and load commands for the Device Unit entity.
Some characteristic attributes have a value that consists of a set of values. Use the add command to add one or more new values to a set value:
ncl> add node 0 osi transport cons filters {filter_2,filter_3}
This command line adds two new values, filter_2 and filter_3, to the set of values represented by the cons filters characteristic of the OSI Transport entity. The values are enclosed in { }, and if more than one value is to be added in the same command, each value is separated from the previous value by a comma.
To specify the empty set (that is, a set with no values), specify { } as the value.
Similarly, use the remove command to remove one or more values from a set value:
ncl> remove node 0 osi transport cons filters {filter_3}
This command line removes the value filter_3 from the set.
Use the add and remove commands only on characteristics with set values (as indicated in the description of the characteristic).
You can also use the set command to change the values of a set-valued characteristic. However, the set command replaces the current contents of the set with the values you specified.
Use the create command to create a new instance of an entity. Most entities support the create command; however, some entities are created automatically by software, and so do not support the create command. For example, entities that correspond to communications links are usually created dynamically as these links are opened.
Use the delete command to delete an instance of an entity. As with create, most entities support the delete command; however, some entities are deleted automatically by software, and so do not support the delete command. For example, entities that correspond to communications links are usually deleted dynamically as these links are closed. You cannot delete an entity if it has child entities; you must delete all child entities before you can delete the parent entity. It is usually, though not always, the case that you must disable an entity before you can delete it.
Many entities have a status attribute called state, whose value reflects the current operational state of the entity. The value of state is usually either:
off | The entity is disabled. In this state, the entity exists and can be manipulated in various ways (for example, by having its characteristics modified), but will not perform its primary functions. |
on | The entity is enabled. In this state, the entity is fully operational. |
Use the disable command to place the entity in its disabled (off) state. Many entities do not permit you to modify their characteristics while they are enabled, so you must use the disable command before using the add, remove, or set commands. Also, it is often the case that you cannot delete an entity while it is enabled, so you must use the disable command before using the delete command:
ncl> disable modem connect line line-1
This command line disables the entity to suspend its operation temporarily and suspends operation of the corresponding physical line.
Use the enable command to place the entity in its enabled (on) state. Most entities do not become operational immediately when you create them; you must use the enable command after the create command. If you disable an entity to modify its characteristics or to suspend its operation for a time, you must use the enable command to make the entity operational again.
Use the set command to modify one or more attributes of an entity:
ncl> set node 0 osi transport delay factor=6,delay weight=10
This command line modifies two characteristics of the OSI Transport entity. If you specify more than one characteristic in a set command, use a comma to separate each characteristic and its value.
If you specify a characteristic name, but no value, the characteristic is set to its default value. The following example sets delay factor to its default value, 4:
ncl> set node 0 osi transport delay factor
Use set to give a value to a characteristic whose value is a set, for example:
ncl> set node 0 osi transport cons filters={filter_2,filter_3}
However, note the difference between this command and the following command:
ncl> add node 0 osi transport cons filters={filter_2,filter_3}
The set command gives the cons filters characteristic a set value with two components: filter_2 and filter_3; if the set previously had other values, these are lost. The add command, on the other hand, adds the values filter_2 and filter_3 to whatever values the characteristic already has; any other current values are retained.
To specify the empty set (that is, a set with no values), specify { } as the value.
You can change the set of attributes called characteristics only by direct management commands and not by the system or indirect commands. For example, you can change characteristics by the set command, but not by the create or enable commands. However, some characteristics are read-only and never change. Each entity section gives complete information about the entity's characteristics, if any, and explains if and how they are modified.
Sequences, sets, and similar constructed data types must be explicitly stated in a set command.
There are certain restrictions on the use of set to modify characteristics:
You use the show command to display the value of one or more attributes of an entity. The general form of a show command is:
ncl> show entity-name attribute-specifier,...
An attribute-specifier can be the name of a particular attribute; for example:
ncl> show node 0 ddcmp link link-5 protocol,transmit underruns,state
This command line displays the following attributes of the entity ddcmp link link-5:
An attribute-specifier can also specify an entire class of attributes, as follows:
The following example displays all counters and status attributes of the entity ddcmp link link-5:
ncl> show node 0 ddcmp link link-5 all counters,all status
You can combine individual attribute names and attribute class names; for example:
ncl> show node 0 ddcmp link link-5 protocol,all counters
This example displays the value of the characteristic protocol and the value of all counters.
There are a few attributes whose value cannot be displayed. These are usually attributes that represent secure information, such as passwords.
An NCL command can contain the following elements, in the order shown:
verb[entity name] [,argument/attribute] [,prep-phrase]
The following example demonstrates this:
ncl> show node .mass.boston.welder routing circuit ethernet-1 - _ncl> all status,by user=harry, password=truman
This command shows the current values for all status attributes for routing circuit Ethernet-1 on node .mass.boston.welder with access control information supplied. The components of this command are:
A comma must separate more than one attribute or argument and must always precede a preposition. For example:
ncl> show node moosie session control port * all status, all counters, with - _ncl> direction = outgoing
If the command is directed to the local system, it is not necessary to include the node entity's class/instance in the command. For example, the following command creates the specified entity on the local node:
ncl> create routing type csma-cd
NCL commands form three broad categories:
ncl> disable routing circuit circuit-1
Entities are specified by their full name in the entity hierarchy and consist of one or more class/instance pairs. For example, the routing circuit reachable address entity is one of the subentities that comprises the Routing module. The reachable address entity is subordinate to the routing circuit entity, which is subordinate to the top-level routing entity in the Routing module. An example of the entity's full name is:
node 0 routing circuit ether-1 reachable address foo
Node 0 is a class/instance pair for the global Node entity. Node 0 is a designation for the local system and is the default value for NCL commands. The "node node-name" element in an NCL command is thus not required when the operation to be performed is for an entity on the local system.
Certain NCL commands, such as show, can include one or more attribute specifiers. The following sections describe the five basic attribute specifiers.
You can specify one or several attribute groups, separated by commas, in a show command. If you specify all, this is equivalent to specifying all the attribute groups that are legal for a command.
NCL and the CMIP Management Listener (CML) do not support entity-specific attribute groups. The common attribute group names are:
See the individual show command descriptions to see which attribute groups are legal for each command.
Characteristics describe the operating parameters of an entity as they are currently defined. You can modify the value of some characteristics by using the set, add, or remove command. Some characteristics have read-only values; their values are set by software and cannot be altered.
Each entity section gives complete information about that entity's characteristics, if any, and explains if and how they can be modified.
Counters record the number of times the entity performed a particular operation or the number of times a certain condition or event has occurred since the entity was created. In some cases, a counter counts the number of times a similarly named event has occurred. Counter values are maintained dynamically by the system and cannot be reset by the system manager.
In most cases, an entity has one identifier: the simple name that is assigned to it when it is created. This identifier is a unique instance name within the entity class and cannot be modified except by deleting the current entity and recreating it with a new name. See specific entity description sections for more information on entities that have multiple identifiers.
Status attributes record current conditions of the entity, such as its state. Usually status attributes are set dynamically by the system to reflect current conditions set up by different operations. You can display current status values, but you cannot directly modify them. However, certain network management actions (such as enabling or disabling an entity) may alter the values of status attributes.
Certain NCL commands have required or optional arguments. Arguments can indicate values to be set, data to be operated on, or instructions for performing a specified task.
You can specify one or both prepositional phrases in any NCL command that accepts them. Separate the prepositional phrases by a comma. See individual command descriptions to determine which commands support the use of prepositional phrases.
Use the with prepositional phrase to qualify an NCL command to limit the scope of its operation. Also called filtering, this process is useful in displaying or acting upon only certain information. The expression supplied as part of the with clause must be an attribute of the entity (or entities) specified in the command.
ncl> show node 0 session control application *, with maximum instances>0
For every session control application entity on node 0 (the local system), NCL finds the entities with maximum instances greater than zero, and returns the identifying information about those session control application entities.
The with prepositional phrase is a Boolean expression that can use the relational operators shown in Table 1-1.
Symbol | Meaning |
---|---|
= | Equals |
<> | Not equals |
< | Less than |
<= | Less than or equal to |
> | Greater than |
>= | Greater than or equal to |
It is possible (but improbable) for the value of an attribute to change between the time the attribute value is tested against the with clause value and the time the directive is actually issued to the entity. This limitation can lead to cases such as the following:
ncl> show 0 session control port *, with send queue > 0 Node 0 Session Control Port %XCC354000 AT 1991-11-13-16:32:03.249-05:00I0.269 Status Send Queue = 0
In this case, the attribute briefly goes non-zero, then immediately returns to zero again. Unfortunately, the attribute changed value between the time it was sampled by the entity filtering software in the CML and the time that the Show directive was issued to that entity instance. This is generally not a problem. Most attributes are stable so this rarely happens.
All NCL commands are made up of the same components: keywords, values, and punctuation. Keywords and punctuation are the parts of the NCL syntax that remain the same for every network; values are the parts that change depending on the particular configuration of a network. Values include entity instance identifiers and attribute/argument values. In general, you cannot abbreviate values, but you can abbreviate keywords as long as the abbreviation is unique. A misspelling may cause NCL to treat an entity name as if it were an attribute name. However, if spelled correctly, it recognizes multiword keywords.
For example, the following command lines are equivalent:
For a Digital UNIX system:
ncl> show node finance routing circuit * ncl> sh n finance r c *
For an OpenVMS system:
ncl> show node finance routing circuit * ncl> sho no finance ro ci *
The node identifier, in this case, finance, cannot be abbreviated. In fact, identifiers anywhere in a command cannot be abbreviated. For example, the following two commands are not equivalent:
ncl> show node finance name ncl> show node f name
The latter command tries to communicate with node f, not node finance.
The following example shows an ambiguous command line:
ncl> s n finance r c * probe rate
The command is ambiguous because the abbreviation s could stand for either the set or show command.
However, if the value itself consists of keywords, then it can be abbreviated. For example, the data type EntityClass, by definition, contains keywords representing the various entity class names. These keywords can be abbreviated in the same way as normal keywords, as long as the abbreviations are unique (unambiguous). See Appendix B for more information on data types and keywords.
As another example, note that the following two commands are equivalent. Both pass all events received by the event dispatcher from the routing entity.
ncl> pass ev d out s local_stream gl f ((r), all) ncl> pass event dispatcher outbound stream local_stream global filter - _ncl> (( routing ), all)
In Digital UNIX, the period character (".") can be used as an abbreviation meaning "the entity specified on the previous command." For example:
ncl> create routing circuit circuit-1 ncl> enable .
You can substitute an unqualified name for a full name in an NCL command only when the remote node specified in the command and the local node use the same primary naming service and their full names are identical except for the unqualified names themselves.
Consider the following cases:
LOCAL NODE REMOTE NODE Full name: ns:.lkg.localnode ns:.lkg.remotenode Unqualified name: localnode remotenode Synonym: locnod remnod Full name: local:.localnode local:.remotenode Unqualified name: localnode remotenode Synonym: locnod remnod
In these cases, you can substitute the unqualified name for the full name in the NCL command:
ncl> set event dispatcher outbound stream ost_1 sink node remotenode
This next example, however, is different:
LOCAL NODE REMOTE NODE Full name: ns:.uct.localnode ns:.lkg.remotenode Unqualified name: localnode remotenode Synonym: locnod remnod Full name: ns:.localnode local:.remotenode Unqualified name: localnode remotenode Synonym: locnod remnod Full name: local:.uct.localnode local:.remotenode Unqualified name: localnode remotenode Synonym: locnod remnod
In this example, you must specify the full name for the remote node in the NCL command:
ncl> set event dispatcher outbound stream ost_1 - _ncl> sink node ns:.lkg.remotenode
On a Digital UNIX system, you must specify the following:
ncl> set session control proxy dth source end user = - _ncl> { [ node=local:.remotenode , end user=uic=[0,0]dan ] }
You cannot substitute the node synonym for a full name in the NCL command. However, in most cases, because the unqualified name and the node synonym are usually identical, it may appear that the synonym substitution was successful.
On OpenVMS, you must use the %X format to specify hex strings in NCL foreign commands. You can issue commands using the ''H format for hex strings only at the NCL> prompt.
Using an asterisk (*) as a wildcard character in an NCL command is
helpful when the target of a command, particularly a show
command, is not easily identifiable. The asterisk wildcard represents
one or more characters. You can also use a question mark (?) as a
wildcard. This represents a single character, and can only be used in
certain data types, such as simplename.
In Digital UNIX, if you use either the asterisk wildcard or the question mark wildcard in a complete NCL command line entered at the shell prompt, remember to insert the escape character (\) before the wildcard so the asterisk or question mark will not be interpreted by the shell.<>.
The rules for using wildcard characters are as follows:
ncl> show node 0 routing circuit * all status ncl> show node 0 session control application tp?_appl ncl> show node 0 session control application ma* all attributes
ncl> show node .admin.artists * <>
To recall previously entered NCL commands, press the up-arrow key.
After recalling an NCL command, modify it by using Ctrl/A to switch
between insert and overstrike modes of editing. You can also use the
Delete key to edit a command line. Re-enter the command by pressing the
Return key. Press the down-arrow key to recall the next (most recent)
command in the NCL command recall buffer.
NCL_PROFILE_001.HTML OSSG Documentation 2-DEC-1996 12:47:33.35
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.