1.31 – enumeration
The enumeration data type represents a collection of defined, named values, (for example, Sunday, Monday...Saturday). A keyword, which may be one or more words, names each value. An integral number code represents each value in the protocol and in the interfaces. The architect constructing this type assigns the codes and keywords. Codes and keywords as defined here also identify entity classes, attributes, directives, responses, exceptions, event reports, and arguments. On output, the keyword is presented as defined. The case used in the definition is preserved. On input, any legal abbreviation of the keyword is allowed. Legal abbreviation is determined by the director architecture, allowing for some flexibility depending on the parser.
1.32 – range
The range type constructor defines a new type whose value is a set of values selected from a base type. The set is defined by specifying an upper and lower boundary of the set. The base type must have a well-defined ordering of values. Ranges can be defined for integers, enumerated types, latin1strings, and so forth. The order of a range type is undefined. range values may not contain wildcards. For example, if a value type is defined as a range of integers, an example might be: [10...100].
1.33 – record
A record is a data type containing one or more fields, each with its own pre-defined data type. Recursive definitions are not allowed. The fields can be either a fixed collection, that is, all the fields always appear and always in the defined order, or a variant record. A record type's order is defined by the order of the fields defined in the records. The fields within a record may contain wildcard symbols, as allowed by their type. For example, [node=usa:.boston.admin, EndUser=michael] The brackets are optional.
1.34 – sequence_of_a_type
A-type can be replaced by any one type, such as a LIST
OF type. Sequence is used where the number of elements
in a list varies, the order of the elements in the list
has meaning, and the elements of a list are repeated. The
syntax for declaring a sequence is:
SEQUENCE OF element-type
The order of two sequences is undefined. Wildcard symbols
are allowed within the elements of the list, as allowed by
the base type.
On output, braces are used to bracket the elements. For
example, here is a sequence of simple-names:
{ Diane, Patty, Mark, Cyndi, Carly }
Note that sequences do not work as filter attributes in a
with clause.
1.35 – set_of_a_type
Set is used where the number of elements in the set varies, the order of the elements in the set has no meaning, two copies of an element value are equivalent to a single copy of the element, and the element type has more possible values than can be efficiently represented using a bit-set. Set A <= set B if A is a subset of B. A<B is not defined on Sets. A=B means normal set equality. Wildcard symbols are not allowed within the set. On output, braces bracket the elements. Note that sets do not work as filter attributes in a with clause.
1.36 – subranges_of_a_base
New types can be constructed by limiting the values of an existing type to a subset in the new type. The mechanism used to specify the subset depends upon the base type. The user-visible representation is identical to the base type. The order of a subrange type is inherited from the base type. For integers and enumeration, the subrange is defined by the low and high values in the base type. The user-visible representation is that of the base type. For example: TYPE CircuitCost = Integer [1...32]; The following integer subranges are already defined: o Integer 8, [-2[7]...2[7]-1] o Integer 16, [-2[15]...2[15]-1] o Integer 32, [-2[31]...2[31]-1] o Unsigned, [0...2[32]-1] o Unsigned 8, [0...2[8]-1] o Unsigned 16, [0...2[16]-1] o Unsigned 32, [0...2[32]-1]
1.37 – variant_records
Variant records extend the record type constructor by allowing the structure of a record to vary, depending upon the value of one of the nonvarying fields. The user-visible representation is the same as that for a record.
2 – Verbs
NCL commands form three broad categories:
o Control commands (such as set ncl default, exit, help) enable
the user to perform certain tasks within the NCL utility
environment. These commands perform no network management
functions.
o Database commands (such as, show, set, add, remove) modify
or display characteristics for existing entities, but may not
immediately affect the network configuration or operation.
o Action commands (such as create, delete, enable, disable)
have an immediate impact on the operation of the network,
often causing a state change to an entity. There are many
entity-specific action commands (see the individual entity
description sections for details). Any command that is not a
control command or a database command is an action command.
For descriptions of these verbs, refer to HELP <verb>.
3 – Entity Names
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 the 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.
For a diagram of the entity heirarchy, refer to HELP
ENTITY_HIERARCHY. For more information on specifying the global
Node entity in an NCL command, refer to HELP NCL SYNTAX
NODE_IDENTIFIER.
4 – Attributes
Certain NCL commands, such as show, can include one or more
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. The common attribute group names are:
o all [attributes]
o all characteristics
o all counters
o all identifiers (the default if no attribute group
is specified)
o all status
See the individual show command descriptions to see which
attribute groups are legal for each command.
4.1 – Characteristics
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.
4.2 – Counters
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 dynamically maintained by
the system and cannot be reset by the system manager.
4.3 – Identifiers
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 re-creating it with
a new name. See specific entity description sections for more
information on entities that have multiple identifiers.
4.4 – Status
Status attributes record current conditions of the entity, such
as its state. Usually status attributes are dynamically set 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.
5 – Arguments
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.
6 – Prepositional Phrases
Most NCL commands accept two types of prepositional phrases:
o Use "by" phrase to specify an access control string for remote
system management.
o Use "with" phrase to limit the action of an NCL command to
those entities that match the qualifying condition.
You can specify one or both prepositional phrases in any NCL
command that accepts them. Separate the prepositional phrases by
a comma.
6.1 – By Preposition
The "by" prepositional phrase authenticates that an account or
proxy account for a particular user has been set up with the
proper access control information. Use of the by preposition
is portable to other DECnet-Plus systems. Use the following
format to append access control information using the by
preposition.
by user=username, password=password, account=account, -
proxy={TRUE/FALSE}
For Tru64 UNIX, NCL ignores any use of the by proxy clause
so that the modifier "by proxy=true" (i.e., proxy access
allowed) is always in effect.
If user j_smith has privileges to access the session control
application graphics_exchange on the remote node, he can use
the by preposition as follows:
ncl> ! On node .admin.finance
ncl> show node .admin.artists session control application -
_ncl> graphics_exchange all counters, by user=j_smith, -
_ncl> password=DoNotUse
.
.
.
For Tru64 UNIX, access control does not have any effect when the
NCL command is directed to the local node. This happens because
NCL uses interprocess communication instead of DECnet-Plus to
communicate with node 0, the local node, and therefore the user's
privileges are determined by the user id that NCL is running under.
6.2 – With Preposition
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 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 as follows:
Symbol Meaning
<> Not equals
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
6.2.1 – Restrictions of With Clause
It is possible (but not improbable) for the value of an
attribute to change between the time that the attribute
value is tested against the with clause value and the time
that 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 1994-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 that it was
sampled by the entity filtering software in the CML (CMIP
Management Listener) and the time that the Show directive
was issued to that entity instance. This is generally
not a problem. Most attributes are stable enough that this
rarely happens.
7 – Using Wildcards
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.
For Tru64 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 that the asterisk or question mark will
not be interpreted by the shell.
The rules for using wildcard characters are as follows:
o Use wildcards only within an entity name (the class name
or the instance name) in an NCL command. Do not use
wildcards within NCL verbs, attributes, or prepositional
phrases. In addition, do not use wildcards in attribute
values unless the use of wildcards is explicitly called
out in the attribute description.
o In all cases, wildcard characters can appear only in the last
class name or last instance value. You cannot use a wildcard
for the global entity node name. All NCL commands that affect
entities include at least two class/instance pairs (the first
being "node node-name" even if it is not specified). For
example:
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
The first command requests a list of all status information
about all defined circuits. The second command requests a
listing of all applications that begin with tp and end with
_appl and have only one character between tp and _appl. The
third command asks for information about all applications that
start with ma and end with any combination of characters.
o Do not use wildcard characters with NCL control commands.
o If you use wildcard characters with an entity instance name, a
display of all the instances of a class appears.
o NCL supports wildcarding for any directive except create.
o For Tru64 UNIX, using a wildcard to show all subentities when
there are no subentities to be displayed may cause NCL to hang.
To return to the ncl> prompt if this occurs, press <Ctrl/C>.
o For Tru64 UNIX, using a wildcard in the entity class name
results in an operation on the enumerated entities of the
next layer down. For example, the "show node 0 *" command shows
the identities of all module entities on the local system.
o If you use a wildcard in an entity instance name, an operation
occurs on all the instances of a class. For example, show node
0 session control application * shows the identities of all
Session Control Applications.
For Tru64 UNIX, you can wildcard all the local entities on the
local system or a remote system. For example:
ncl> show node .admin.artists *
8 – Node Identifiers
In the absence of a default node entity, if no node is specified
in an NCL command, then the default node-id is 0, which represents
the local node.
You can specify a node-id in an NCL command in various ways, using
either a node name or address. Under certain conditions, the
unqualified node name (often identical to the node synonym) may be
used in an NCL command as the node-id.
8.1 – Addresses
If the name service is interrupted or unavailable, you can
still reach remote nodes to perform management functions. You can
use the remote node's Phase IV address (if the remote node is
configured to have one), or the remote node's NSAP. Refer to the
"Understanding and Creating NSAP Addresses" chapter in the
DECnet-Plus Planning Guide for the Tru64 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 Tru64 UNIX system:
ncl> show node 49::00-0C:AA-00-04-00-05-30:20 routing -
_ncl> circuit syn-0-0
For an OpenVMS system:
ncl> show node net$49000CAA000400053020 routing circuit syn-0-0
If both the local and remote nodes are configured to run
DECnet over TCP/IP (RFC 1859), you may refer to the remote node
using the IP address as in:
ncl> show node 16.78.232.13 all
8.2 – Names
Node names can be specified in different ways depending upon
the directory service(s) you are using.
If the local node is configured to use the DECdns name service
and the remote node is correctly registered in the DECdns
namespace, you may refer to the node using a DECdns fullname,
as in:
ncl> show node NS:.lkg.remotenode all
If the local node is configured to use the LOCAL name service
and the remote node is correctly registered in the LOCAL
namespace, you may choose to use the LOCAL fullname, as in:
ncl> show node LOCAL:.remotenode all
If both the local and remote nodes are running DECnet over
TCP/IP (RFC 1859) and the remote host name is somehow
translatable (perhaps using the Hosts Database or DNS/BIND),
you may refer to the remote node using the DOMAIN fullname,
as in:
ncl> show node DOMAIN:remotenode.lkg.dec.com all
8.3 – Unqualified Names and Node Synonyms
A node synonym is a Phase IV-style node name, between 1 and 6
characters long, that is unique within the namespace. This
node synonym is required for Phase IV applications that can
handle only a maximum of 6-character node names.
An unqualified name is the final simplename -- that portion
of the DECdns or LOCAL full name following the last "."
Although this unqualified name is usually identical to the
node synonym, it is not required to be identical to the node
synonym.
An unqualified name may be substituted 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.
For example, in 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
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
However, for the following examples:
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
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
Or, on a Tru64 UNIX system:
ncl> set session control proxy dth source end user = -
_ncl> { [ node=local:.remotenode , end user=uic=[0,0]dan ] }
The node synonym cannot be substituted for a full name in
the NCL command. However, in most cases since the unqualified
name and the node synonym are usually identical, it may
appear that the synonym substitution was successful.