This help section describes how to use the Network Control
Language (NCL) command line interface on HP DECnet-Plus for
Tru64 UNIX and OpenVMS nodes. You should be familiar with the
concepts and terminology of the entity model of network
management, as described in the DECnet-Plus Network Management
manual. This hierarchy of manageable entities is also
described in this help utility under HELP ENTITY_HIERARCHY.
1 – Invoking NCL
Methods of invoking NCL differ depending upon the operating system.
1.1 – Tru64 UNIX
There are several ways to invoke the interactive NCL utility:
1. Enter ncl at the shell prompt. The NCL prompt appears:
% ncl <Return>
ncl>
2. Enter an NCL command line.
% ncl any ncl command <Return>
After the command executes, you return to the shell.
3. Redirect a command script into NCL.
% ncl <scripta
where scripta is the name of a script that contains a sequence
of NCL commands.
4. Execute a shell script containing NCL commands. Your shell
script can use the exit status returned by NCL commands.
% ncl_filename
The following C shell script demonstrates this:
#!/bin/csh
ncl show routing circuit circuit-1 all attributes
if ( $status != 0 ) then
echo ""
echo "This ncl command failed."
echo ""
endif
This sample script uses the exit status from an NCL command
to determine whether or not to echo a message. If the command
fails, the shell script echoes the message.
Other NCL operations include:
o To abort an NCL operation, press <Ctrl/C> at the ncl> prompt.
o To continue a long command to the next line, use a hyphen as
the last character in the line. The _ncl> prompt is displayed
on continuation lines:
ncl> set node moosie routing manual network entity titles -
_ncl> { 49::00-0c:08-00-2b-12-34-56:00, -
_ncl> 49::00-0c:08-00-2b-12-34-57:00 }
o To include comments in NCL shell scripts or as part of a
command line in the interactive utility, use the exclamation
point (!) or pound sign (#) character. NCL ignores hyphens
within and at the end of a comment line.
o To exit from NCL, enter exit, quit, or press <Ctrl/D> at the ncl>
prompt.
1.2 – OpenVMS
There are several methods of invoking the interactive NCL
utility:
1. Type RUN SYS$SYSTEM:NCL at the DCL prompt $:
$ run sys$system:ncl <Return>
NCL>
2. Define a symbol at the DCL prompt (or insert the symbol
in your login file) and then type NCL at the DCL prompt as
follows:
$ ncl :== $ sys$system:ncl <Return>
$ ncl <Return>
NCL>
3. Enter an NCL command line.
$ ncl any ncl command <Return>
The system executes the command and returns you to the $
prompt.
NOTE
The third method works only if you define a symbol at the
DCL prompt or insert the symbol in your login file.
4. Enter MCR at the DCL prompt:
$ mcr ncl <Return>
NCL>
5. Enter an MCR command:
$ mcr ncl any ncl command <Return>
$
The NCL> prompt indicates that you are using the NCL utility.
When you receive this prompt, you can enter NCL commands.
Other NCL operations include:
o To abort an NCL operation, press <Ctrl/C> or <Ctrl/Y> at the
NCL> prompt.
o To continue a long command to the next line, use a hyphen as
the last character in the line. Place the continuation hyphen
between attributes in a list. The _NCL> prompt is displayed on
continuation lines:
NCL> show node 0 osi transport delay factor, delay weight,-
_NCL> maximum receive buffers, maximum network connections,-
_NCL> maximum remote nsaps
o To indicate comments that are not to be read by the system,
use an exclamation point (!) anywhere in a command line.
o To exit from NCL, type exit or press <Ctrl/Z> at the ncl>
prompt.
2 – Creating Logs
To keep a record of the commands entered during an NCL session,
use the NCL logging facility.
All information printed out in an NCL session is stored in the
log file after logging is enabled. This information includes
commands, output, and error messages. All information except
for the commands are preceded in the file by a comment symbol,
so this file can be used as an NCL script in another session.
Use the set ncl logfile and enable ncl logging commands to begin
NCL logging. For example:
ncl> set ncl logfile filename.ncl
ncl> enable ncl logging
ncl> show node 0 session control application fal all attributes
.
.
.
After saving the NCL commands to a log file, use the NCL log file
as an indirect command file to be invoked (during subsequent NCL
sessions) with the do control verb or the at sign (@) symbol.
For example:
ncl> enable node 0 session control
ncl> do setup_applications.ncl
.
.
.
To display the name of the log file, enter show ncl logfile. For
Tru64 UNIX, the utility returns the default log file name if one
was not previously set. For OpenVMS, the default file type 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 exit NCL.
Commands saved in an NCL log file can be executed 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 the utility.
3 – Common Commands
Refer to HELP <verb> for brief descriptions of the most
commonly used NCL commands. The commonly used verbs are:
add and remove
create and delete
disable and enable
set
show
These commands have the same effect on any entity to which
they are applied.
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 command
for the Device Unit entity.
4 – Abbreviation of Commands
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 misspeling 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:
ncl> show node finance routing circuit *
can be abbreviated to:
ncl> sh n finance r c *
Where finance identifies which node is being used, therefore it
cannot be abbreviated.
Values 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.
Notice that, the following command line is ambiguous:
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 of the DECnet-Plus Network Control
Language Reference 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 -
_ncl> global filter (( routing ), all)
On Tru64 UNIX, the period character (".") can be used as an
abbreviation meaning "the entity specified in the previous
command." For example:
ncl> create routing circuit circuit-1
ncl> enable .
5 – Syntax
An NCL command can contain the following elements, in the order
shown:
verb [entity name] [,argument/attribute] [,prepositional_phrase]
and as demonstrated in the following example:
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:
o Verb (or directive): show
o Entity name: node .mass.boston.welder routing circuit
ethernet-1, where:
- node is the global entity class
- .mass.boston.welder is the instance name for class node
- routing identifies the module to which this entity belongs
- circuit is the entity class
- ethernet-1 is the instance name for class circuit. The
entity name reflects the full naming hierarchy for the
entity.
o all status, an attribute specifier
o by (preceded by a comma), a prepositional phrase
o user=harry, password=truman, user name and password used for
access control on the remote node
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 -
_ncl> counters, with 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, this command would create the specified
entity on the local node:
ncl> create routing type endnode
5.1 – Data Types
5.1.1 – boolean
The boolean data type has two values, true and false, in an undefined order. On output, the strings appear as true and false. On input, the words true or false may be abbreviated to a single character and are not case-sensitive. The boolean data type does not support the use of wildcard symbols.
5.1.2 – counters
All counters for an entity are created together and a time of creation is associated with the block. The following counter types are defined: Type Modulus Counter16 2[16] Counter32 2[32] Counter64 2[64] If no modulus is specified, or if the type Counter is specified without reference to a modulus, the modulus 2[64] is assumed. The counter is displayed as an unsigned integer. It cannot be set to zero. In DECnet-Plus, when a counter reaches its maximum value, its next value is zero. Counters never latch (as they did in Phase IV). Consequently, there is never any need to reset or zero the counters. This is called "wrapping counters" because the values wrap around to zero (they are like true modulo 2**n integer values). NCL and other network management applications are able to cope with wrapping counters and can still compute counter differences, even if the second sampled value of the counter is less than the first because of counter wrap. The implicit assumption is that any counter with n (where n is a power of 2) distinct possible values cannot be changed more than n times between samples. Since all DECnet-Plus counters are 64-bit counters, the number of possible values is 2 raised to the 64th power, which is a 20-digit decimal number. Very few counters will ever exceed 32 bits, and it does not appear likely that a 64-bit counter will ever wrap once, let alone twice.
5.1.3 – DTE address
A DTE Address is an X.25-defined address of some data
terminal equipment (DTE). It is represented as a
latin1string whose length is 0 to 15 digits or wildcard
characters. Wildcard characters can be embedded: the
asterisk (*) matches any sequence of zero or more digits;
the question mark (?) and percent sign (%) match any single
digit.
The user-visible syntax of a DTE address is {digit-
wildcard}. For example, 5084865322 is a DTE address.
5.1.4 – entity_name
The entity name data type holds an arbitrary name of an entity. It is usually used as a pointer, so that an attribute (or argument) can refer to another entity. Entity names appear in two forms: as a full-entity-name, which includes both the global and the local portion of the entity's name, and as a local-entity-name, which includes only the local portion of the entity's name. A local-entity-name is always assumed to be subordinate to the node executing the directive. A local-entity-name is a convenient method of describing the configuration of the components that comprise a node. Entity names can be wildcarded. An entity class (the sequence of classes) is also a defined type, both as a full class name and as a local class name. For example, routing circuit csmacd-c2 is a local entity name. Neither the full or local class name has a defined order, but allow wildcarding in the same manner as an entity name. Refer to HELP ENTITY_HEIRARCHY for further information.
5.1.5 – EthernetProtocol
The EthernetProtocol data type consists of two octets, Octet #0 and #1. Octet #0 is transmitted first. The user-visible representation is a pair of octets (each a hex-digit) separated by a hyphen (-). For example 60-03 is a valid Ethernet data type.
5.1.6 – filespec
Wildcard symbols may be supported, as defined by the target implementation. A file specification appears in one of three forms, depending on the characters it contains. While most file specifications can be entered and displayed as simple names, the inclusion of certain punctuation characters or any control character makes the interpretation of the file specification ambiguous. The following three forms of a file specification may be entered or displayed: o Simple File Specification A file specification is a simple file specification if it consists solely of the following characters: alphanumeric Aa to Zz hyphen - and 1 to 9 dollar sign $ underscore _ period . brackets [ ] angle brackets <> backslash and slash \ / asterisk * percent sign % question mark ? colon : semicolon ; The file specification may be input directly as a quoted file specification or as a binary file specification. On output, it is displayed directly. o Quoted File Specification When the file specification consists of any of the latin1string character set, but is not a simple file specification, then the file is a quoted file specification. On input, a quoted file specification is displayed as a latin1string or as a binary file specification. On output it is displayed as a latin1string. o Binary File Specification If the file specification is not a simple or quoted file specification, it is a binary file specification. Binary file specifications are entered and displayed as an octet-string. For example, '01'H (a^A) The filespec data type for a file specification should be compatible with the transference of file specifications in the DECnet DAP protocol. Since file specifications are interpreted according to the file system at the target entity, there is no guarantee that a file specification for one operating system will be acceptable to another. The target implementation defines the ordering of filespec.
5.1.7 – fullname
The fullname data type represents globally distinct names and does not have a defined ordering. It does support wildcarding. The supported symbols include the asterisk (*), which matches any sequence of zero or more characters, and the question mark (?), which matches any single character. For example, phasev_nsp.usa.mass.admin.fred is a full name. For more information, refer to the DECdns Management Guide.
5.1.8 – hex_string
A hex-string represents a string of zero or more
hexadecimal digits (also called semi-octets or nibbles).
A hex-string differs from an octet-string only in that
it allows for an odd number of hexadecimal digits. Two
hex-strings are equal if they have the same length and
hexadecimal digits. Ordering is defined as with an octet-
string, except the comparison is by hexadecimal digit
rather than by octet. The hex-string data type does not
support wildcards.
Enter the hex-string as follows:
' {hex-digit} ' h | % x { hex-digit }
On output, the hex digits A to F are displayed in
uppercase. For example, 'AABBCC'h is a hex-string.
On OpenVMS, the %X format must be used to specify hex
strings in NCL foreign commands. Commands using the ''H
format for hex strings can only be issued at the NCL>
prompt.
5.1.9 – ID802
An ID (or System ID or LAN Address), is a 48-bit quantity, uniquely assigned over space and used as an Ethernet or IEEE 802.3 CSMA/CD address (and for other purposes). An ID consists of six octets (48-bits) numbered from zero to five. When transmitted on an 802.3 LAN, the least significant bit of Octet #0 is transmitted first and the most significant bit of Octet #5 is transmitted last. The user-visible representation of a system ID is six octets, each displayed as a pair of hexadecimal digits separated by hyphens (-) in the order 0,1,2,3,4,5. For example: 08-00-2B-02-B0-C0
5.1.10 – IEEE802SNAPPID
The IEEE802SNAPPID (IEEE 802 Sub-Network Access Protocol (SNAP), Protocol Identification) consists of five octets numbered from zero to four. When transmitted on an 802.3 LAN, the least significant bit of Octet #0 is transmitted first, and most significant bit of Octet #4 is transmitted last. The user-visible representation is five octets, each displayed as a pair of hex digits separated by hyphens (-) in the order 0,1,2,3,4. For example, 01-23-45-67-89.
5.1.11 – implementation
An implementation data type identifies the components that
make up an entity and their implementation versions. An
implementation is a set of components, where each component
is a record containing a registered component name and
a version. The version field may be of any base type,
although it is recommended that the common version or
version-with-edit data type be used. The data type used
for the version field is registered with the component
name.
Example:
ncl> show imp
Node 0
at 2003-04-10-11:08:20.290-04:00Iinf
Characteristics
Implementation =
{
[
Name = OpenVMS Alpha ,
Version = "V7.3-2 "
] ,
[
Name = HP DECnet-Plus for OpenVMS ,
Version = "V7.3-2 3-APR-2003 12:17:03.79"
]
}
5.1.12 – integer
The integer data type represents signed or unsigned integer
values. The signed integer values may range from -2[31]
to +2[31]-1, following the normal ordering. The unsigned
integer values may range from 0 to +2[32]-1, following the
normal ordering. Remember the following:
o Both signed and unsigned integers may be represented in
4 bytes.
o Accepted integer syntax should be followed when entering
the integer values.
o Wildcard symbols are not supported.
o Ordering is supported.
5.1.13 – latin1string
The latin1string type represents general, printable
strings. These strings can be of any length (including
zero). The characters in the Latin 1 set are described in
ISO DIS 8859/1 Latin Alphabet Nr 1.
Only printable characters appear in a Latin1String. ASCII
control characters (00 to 1F, 7F, and 80 to 9F (hex))
cannot appear.
On OpenVMS on input and output of attributes, the string
is embedded either quote characters (") or apostrophe
characters ('). Double the quote character to embed a
quote within a string delimited by the same type of
quote character.
On Tru64 UNIX, you are not required to embed the
string in quotes.
5.1.14 – Network Layer Addresses
Network layer addresses in DNA may be of four types:
o Complete Network Service Access Point (NSAP) address.
o Network Entity Title (NET)-NSAP address with the
selector set to 00.
o Area address-NSAP address minus the last seven octets.
o Address prefix-leading substring of an area address.
None of these data types have a defined ordering or
support wildcarding. Refer to the DECnet-Plus
Introduction and User's Guide for your operating system
for a description of the parts of a DECnet-Plus Network
layer address.
5.1.15 – node_name
The node-name is used to represent names of nodes using either a full-name or a Phase IV node name. The only difference between a node-name and a full-name is that a node-name also be a Phase IV synonym.
5.1.16 – null
The null data type is used when the set of possible values is empty. This is used only to indicate that an entity class has no instance identifier, and then (to make the CMIP protocol complete) a null value is sent. The null type cannot be assigned to an attribute or argument.
5.1.17 – object_identifier
The object-identifier data type represents registered values of the ISO object identifier. Ordering is undefined and wildcarding symbols are not supported. For example, 1.2.3.4.5.6 represents a registered value.
5.1.18 – octet_and_octet_string
The octet string data type is used to represent arbitrary
data (octets). It is displayed as a hexadecimal string
(that is, HI-n in old NICE form). The length of an octet
string is variable, without a maximum, and may be zero.
The octet data type represents a single byte (8-bits) of
data. While similar to an octet-string of length 1, it
has a slightly different user-visible representation. The
ordering of octet is defined by considering an octet as an
unsigned 8-bit quantity. Two octets are equal only if they
have the same length and the same octets.
On output, the hex digits A to F are uppercase.
The octet data types do not support the use of wildcard
symbols.
The user-visible representation of an octet-string appears
as follows:
' {octet} ' h | % x {octet}
For example, %x89ABCDEF or '89ABCDEF'h are valid
representations.
5.1.19 – Phase4Name
The Phase4Name data type is used for Phase IV-style node names. It is a Latin1String whose length is restricted from 1 to 6 characters from the set A to Z, or 0 to 9, at least one of which is a letter. The type is ordered as a normal character string. Node names can contain wildcard symbols: the asterisk (*) matches a sequence of zero or more characters; the percent sign (%) matches any single character. For example, LEAF97 is a Phase4Name.
5.1.20 – Phase4Address
The Phase4Address data type is used for Phase IV-style node addresses. It is an unsigned, 16-bit integer where the least significant ten bits (bits 0 to 9) encode the local address and the most significant six bits (bits 10 to 15) encode the area number. Local address is an integer from 1 to 1023 and area number is an integer from 1 to 63. The area number zero and the local address zero are reserved to represent all areas and all local addresses, respectively, and are represented by the asterisk (*) character when user-visible. Phase4Address data types are ordered by the value of the equivalent unsigned integer. For example, 4.83 is a Phase4Address.
5.1.21 – presentation_address
The presentation-address data type defines the format
that should be used for all presentation addresses in OSI
applications.
This data type is a Latin1string. Its values must conform
to the following syntax (shown in BNF). This syntax is an
extension of the Internet standard for representing OSI
presentation addresses.
<presentation-address> ::= [[[ <psel> "/" ] <ssel> "/" ]
<tsel> "/" ] <network-address-list>
<psel> ::= <selector>
<ssel> ::= <selector>
<tsel> ::= <selector>
<selector> ::= '"' <otherstring> '"' 1
| "#" <digitstring> 2
| "'" <hexstring> "'H"
| ""
<network-address-list> ::= <network-addr> [ "|" <network-addr> ]
| <network-addr>
<network-addr> ::= <network-address> ["," <network-type> ]
<network-type> ::= "CLNS" | "CONS" | "RFC1006" 3
<network-address> ::= "NS" "+" <dothexstring> 4
| <afi> "+" <idi> ["+" <dsp>]
| <idp> "+" <hexstring> 5
| RFC1006 "+" <ip> ["+" <port>] 6
<idp> ::= <digitstring>
<dsp> ::= "d" <digitstring> 7
| "x" <dothexstring> 8
| "l" <otherstring> 9
| "RFC1006" "+" <prefix> "+" <ip> ["+" <port>
["+" <tset>]]
| "X.25(80)" "+" <prefix> "+" <dte>
[ "+" <cudf-or-pid> "+" <hexstring> ]
| "ECMA-117-Binary"
"+" <hexstring> "+" <hexstring>
"+" <hexstring>
| "ECMA-117-Decimal"
"+" <digitstring> "+" <digitstring>
"+" <digitstring>
<id> ::= <digitstring>
<afi> ::= "X121" | "DCC" | "TELEX" | "PSTN"
| "ISDN" | "ICD" | "LOCAL"
<prefix> ::= <digit> <digit>
<ip> ::= <domainstring> 10
<port> ::= <digitstring> 11
<tset> ::= "TCP" | "IP" | <digitstring> 12
<dte> ::= <digitstring>
<cudf-or-pid> ::= "CUDF" | "PID"
<decimaloctet> ::= <digit> | <digit> <digit>
| <digit> <digit> <digit>
<digit> ::= [0-9]
<digitstring> ::= <digit> <digitstring>
| <digit>
<domainchar> ::= [0-9a-zA-Z-.]
<domainstring> ::= <domainchar> <otherstring>
| <domainchar>
<dotstring> ::= <decimaloctet> "." <dotstring>
| <decimaloctet> "." <decimaloctet>
<dothexstring> ::= <dotstring>
| <hexstring>
<hexdigit>:: ::= [0-9a-fA-F]
<hexoctet> ::= <hexdigit> <hexdigit>
<hexstring> ::= <hexoctet> <hexstring>
| <hexoctet>
<other> ::= [0-9a-zA-Z+-.]
<otherstring> ::= <other> <otherstring>
| <other>
1 Value restricted to printed characters
2 US GOSIP requirement
3 Network type identifier (the default is CLNS)
4 Concrete binary representation of network (NSAP) address
value
5 ISO 8348 compatibility
6 RFC1006 preferred format
7 Abstract decimal format for domain specific part (DSP)
8 Abstract binary for DSP
9 Printable character format for DSP (for local use only)
10 Dotted decimal notation (10.0.0.6) or domain name
(twg.com)
11 TCP port number (the default is 102)
12 Internet transport protocol identifier (1 = TCP and 2 =
UDP)
Keywords can be specified in either uppercase or lowercase.
However, selector values are case sensitive. Spaces are
significant.
Note that you can find more information about network
(NSAP) addresses in the Introduction, Planning, and Glossary
manual.
The following examples illustrate the use of this data
type:
1. "my_psel"/"my_ssel"/"my_tsel"
/LOCAL++x0001aa000400d90621 "my_psel"/"my_ssel"/"my_
tsel"/NS+490001aa000400d90621,CLNS
These examples both specify the same presentation
address. The first example uses the LOCAL authority
and format identifier (AFI), which does not have an
initial domain identifier (IDI). The two plus signs
(++) indicate that the IDI is missing. By default, the
network type is CLNS. The second example uses the value
of the LOCAL AFI, which is 49.
2. "256"/NS+a433bb93c1,CLNS|NS+aa3106,CONS
This is a presentation address which has a transport
selector, (no presentation or session selector), and
two network addresses. The first network address is
CLNS (for a connectionless network) and the second
is CONS (for a connection-oriented network). These
network addresses are specified in concrete binary form.
This form can be used only when the concrete binary
representation of the network address is known.
3. #63/#41/#12/X121+234219200300,CONS
This presentation address has presentation, session and
transport selectors, and a single network address which
consists of an AFI (X121) and an IDI (234219200300).
There is no domain-specific part.
4. '3a'H
/TELEX+00728722+X.25(80)+02+00002340555+CUDF+"892796"
This is a network address for X.25. Note that, because
CONS is not specified, the network type defaults to
CLNS.
5. RFC1006+10.0.0.6519,RFC1006
This is an RFC1006 address. The address is not an ISO
network address but the combination of an IP address and
a TCP port number, which is 519 in this example. The IP
address can be specified as either a DNS domain name or
an IP address. For an RFC1006 address, the network type
can be omitted.
5.1.22 – simple_name
This base data type allows most names to be represented as unquoted strings. The simple-name data type also allows some values to be expressed as quoted strings and other values as binary data. The simple-name data type does not have a defined ordering but it does support wildcarding. The supported symbols include the asterisk (*), which matches any sequence of zero or more characters, and the question mark (?), which matches any single character. For example, tweedle_dee, "tweedle dee", and %x4700050020AA0004005310 are simple names.
5.1.23 – time
Four time data types are available for use with NCL.
Each is a built-in data type for management, and does not
support wildcarding symbols. The four are:
o CharacterAbsoluteTime
o BinaryAbsoluteTime
o CharacterRelativeTime
o BinaryRelativeTime
For example, 1992-08-18-14:47:47-05:00I0.168 is a time data
type of the BinaryAbsoluteTime data type.
You can order time values. For example, the command
ncl> show node busy session control port * all, -
with creation time > 16:45
makes use of the ordering property of the time data types.
5.1.24 – TransportSelector (TSEL)
The TransportSelector (or TSEL) data type is used by OSI Transport to identify a particular OSI Transport port. A TransportSelector is an octet string, of 0 to 32 octets in length. The user-visible representation, ordering, and wildcarding is the same as for an octet-string.
5.1.25 – UID
The UID data type provides unique space and time identifiers and does not support wildcarding symbols. No two UIDs are ever the same. A UID is hexadecimal. For example, 7834E80-E519-1119-8D8D-08002B16A872 is a valid UID. The user-visible presentation of a UID consists of four fields, separated by spaces: UIDTime UIDVersion UIDClock UIDNodeID where o UIDTime is InstantaneousTime o UIDVersion is Integer o UIDClock is Integer o UIDNodeID is ID
5.1.26 – version
The version data type is used to encode a version number of a particular entity (usually a module or node entity) in a standard way. Wildcarding symbols are not supported. The version number contains the four subfields: status, major version, minor version, and an edit or revision number. The version status subfield indicates whether the version is Approved (V), Field Test (T), or Draft (X). The order of version numbers is defined by checking the fields in the order: 1. Major 2. Minor 3. Status (with V > T > X) 4. Revision Number Enter the version number as follows: version-status.major.minor.eco For example, T5.0.2 is a valid version number.
5.1.27 – version_with_edit
The version number with an edit number is commonly used and is represented as a separate type called version-with-edit. Enter the number as follows: version_number-edit_number For example: X5.0.13-967
5.1.28 – bit_set
The bit-set data type is an efficient means of describing
small quantities of a base type's sets of values.
The order of a bit-set is defined by A<=B if A is a subset
of B. A=B means normal set equality. No wildcard symbols
are defined for bit sets.
The user-visible representation of a set is to enclose
the set values in bracketing characters, with the values
separated by commas. Braces are used as bracketing
characters for both input and output. For example,
{0,2,3,5}.
5.1.29 – end_user_specification
An end-user-specification is defined by Session Control and used as an address of a particular end user. This is generally equivalent to Phase IV object name and number. The user-visible syntax is the standard syntax for a record. For example, Number=25 and Name=FAL are valid. Note that end-user-specification does not work as a filter attribute in a with clause.
5.1.30 – TowerSet
The TowerSet data type is used at the DNA Session Control
interface to specify addressing information. The idea
behind the tower set is that a given networking service
may be accessible through many different combinations of
protocols and addresses. The TowerSet data type is intended
to allow the end user to specify any arbitrary combination
of protocols and addresses to Session Control. Of course,
most end users do not want to do this, so normally the end
user would specify the name of the service, and DNA Session
Control would look up the TowerSet of the service (its
address) using the DNA Naming Service, and would try to
establish a connection using any one of the possible ways
of connecting to the remote service.
Table A-2 TowerSet Levels of Specification
TowerSet A set of ProtocolTower
ProtocolTower A sequence of Floor
Floor (Protocol ID, address) pair
Protocol ID Name or number of a network protocol
Address Address of this service with respect
to a protocol
A ProtocolTower specifies a layering of protocols that can
be used to access the network service. The top floor in a
ProtocolTower corresponds to the highest-level protocol and
the bottom floor to the lowest-level protocol. Usually the
Network layer (layer three in the OSI model) is the lowest
level of protocol needed.
A Floor is a particular (protocol, address) pair used
within a ProtocolTower to access a remote service. The
data type of the address is a function of the protocol.
For example, the DNA_OSInetwork protocol uses an NSAP as
the address, the DNA_IP protocol uses an IP address, and
DNA_SessionControlV3 uses an end user specification.
Some protocols do not require an address; for example,
the Application layer (top layer) does not require an
address.
A protocol ID is the name or number of a protocol.
An address value specifies the SAP (Service Access Point)
to be used by the application for this particular protocol.
For example, the node entity's address attribute is given
by NCL as:
Address =
{
(
[ DNA_CMIP-MICE ] ,
[ DNA_SessionControlV3 , number=19 ] ,
[ DNA_OSItransportV1 , 'DEC0'H ] ,
[ DNA_OSInetwork , 41:45418715:00-41:08-00-2B-16-A8-72:21 ]
) ,
(
[ DNA_CMIP-MICE ] ,
[ DNA_SessionControlV3 , number=19 ] ,
[ DNA_OSItransportV1 , 'DEC0'H ] ,
[ DNA_OSInetwork , 49::00-0C:AA-00-04-00-50-30:21 ]
) ,
(
[ DNA_CMIP-MICE ] ,
[ DNA_SessionControlV3 , number = 19 ] ,
[ DNA_OSItransportV1 , 'DEC0'H ] ,
[ DNA_IP , 161.114.94.62 ]
) ,
(
[ DNA_CMIP-MICE ] ,
[ DNA_SessionControlV3 , number=19 ]
[ DNA_NSP ] ,
[ DNA_OSInetwork , 41:45418715:00-41:08-00-2B-16-A8-72:20 ] ,
) ,
(
[ DNA_CMIP-MICE ] ,
[ DNA_SessionControlV3 , number=19 ] ,
[ DNA_NSP ] ,
[ DNA_OSInetwork , 49::00-0C:AA-00-04-00-50-30:20 ]
)
}
The above example shows all the possible methods of
connecting to the CML (CMIP Management Listener) on a
DECnet-Plus node. The first floor in each of the above
ProtocolTowers specifies the application as
DNA_CMIP-MICE.
The second floor in each of the example ProtocolTowers
specifies the session control version in use. This will
generally be Session Control Version 3
{ DNA_SessionControlV3 }. Nodes capable of SC V3
(Phase V nodes) are also capable of communicating using
SC V2 (the session protocol used by Phase IV nodes).
There are five ProtocolTower values in the example
TowerSet above. Four of these ProtocolTower values were
determined using two possible transport protocols:
{ DNA_OSItransportV1, DNA_NSP }
in combination with these two possible network addresses:
{ 49::00-0C:AA-00-04-00-50-30:00, 41:45418715:00-41:08-00-
2B-16-A8-72:00 }
Still another ProtocolTower was produced using
RFC1006 and/or RFC1859 transport over the IP address:
{ 161.114.94.62 }
RFC1006 (OSI over TCP/IP) specifies the use of OSI
transport Class 0 (TP0) on top of TCP. RFC1859 (DECnet
over TCP/IP) specifies the use of OSI transport
Class 2 (TP2) on top of TCP. This is why towers
containing an IP address will always specifiy
DNA_OSItransportV1 as the transport protocol id.
Usually, the node registers its TowerSet automatically
with the naming service; the end user would not enter it.
However, if the naming service is unreachable from the
network manager's node, it may be necessary to manually
enter a TowerSet. Enter a single ProtocolTower. It may be
possible to omit the upper floor since it is not yet used
by applications.
If the node entity identifier is formally defined to be a
TowerSet, NCL allows the end user to enter the identifier
by Phase IV address and by NSAP. In such cases, NCL infers
the TowerSet from a much more abbreviated form of address.
5.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.
5.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].
5.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.
5.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.
5.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.
5.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]
5.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.
5.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>.
5.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.
5.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.
5.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.
5.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.
5.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.
5.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.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.
5.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.
5.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.
5.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
5.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.
5.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 *
5.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.
5.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
5.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
5.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.
6 – Recalling Commands
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. Reenter 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.
For Tru64 UNIX, you can recall commands by string by starting the
line with a '^' or by ending a line by pressing the <Find> key,
for example:
ncl> ^ena <Return>
or
ncl> ena <Find>
Will recall the last command that started with "ena."
7 – Output
The output of NCL commands varies somewhat depending upon the
operating system.
7.1 – Tru64 UNIX
After you enter a command, the system responds with a display
that includes a summary of the command you entered, the UID
of the entity (if enabled) referred to in the command, and a
timestamp showing when the output was gathered or the command
executed. With some commands (for example, show), the output
also includes a display of certain values.
Some of the timestamps displayed during ncl show commands are
returned with a value of undefined for some entities. This
indicates that the condition that causes the attribute to be
timestamped has not occurred yet.
The following is an example of a typical show display:
ncl>show session control application fal all chara
Node 0 Session Control Application fal
AT 1994-02-21-14:54:01.609-05:00I0.137
Characteristics
Addresses
{ number=17 =
}
Incoming Proxy = True
Node Synonym = False
Image Name = /usr/etc/fal
User Name = guest
Incoming OSI TSEL =''H
Data Abstraction = Message
Accept Mode = Deferred
Programming Interface = Phase IV
Maximum Instances = 0
Allow DECnet Internet Gateway Access = True
Exception messages
If a command does not complete successfully, you can get one or
more exception or error messages. There are three categories of
error displays:
o Errors caused by incorrect command syntax. In these errors,
NCL issues the error message immediately and does not send the
command to the entity itself. For example:
# ncl show tree all
SYNTAX ERROR: No match was found for this string.
show tree all
____ ^
o Validation errors, in which NCL accepts the command syntax
as valid, but subsequently returns an error message when the
command violates a constraint or rule. For example:
# ncl set routing probe rate = 0
RANGE ERROR: The minimum value for this attribute is 1.
set routing probe range = 0
_________________________ ^
In this case, the value 0 was outside the allowable range of
values for this attribute. NCL detected this after it had parsed
the command, but before it had issued the command to the entity.
o Errors returned from the remote entity's agent. In these
errors, NCL was able to interpret the command, but was unable
to perform it for some reason. For example:
Node 0 CSMA-CD
AT 1994-10-06-15:35:14.069-04:00I0.301
FAILED IN DIRECTIVE: Create
DUE TO: Error specific to this entity's class
REASON: Already Exists
Description: Already Exists
A response returned from the remote agent will be displayed
with an AT time stamp. See Appendix A of the DECnet-Plus Network
Control Language Reference for more information on responses.
Adjusting the Display Format
Use the following local commands to adjust the display format.
To define how far over the values can be indented (default=34),
use the commands:
ncl> set ncl name display width = 50
ncl> show ncl name display width
To control whether or not dots are filled in between the attribute
name and its value (for example, state ..... = On), use the
commands:
ncl> enable ncl dots
ncl> disable ncl dots
To control whether counters are displayed left justified or right
justified, use the commands:
ncl> set ncl counter justification = left
ncl> set ncl counter justification = right
To determine if backtranslation will be done or not, use the
commands:
ncl> enable ncl backtranslation
ncl> disable ncl backtranslation
The page width is used to intelligently wrap error messages and to
decide if the snapshot display will require 1 line or 2 lines per
counter. Normally, NCL tracks the page width automatically. To
override the value if necessary, use the commands:
ncl> set ncl page width = 50
ncl> show ncl page width
When NCL is processing an NCL script, use the following commands
to determine if each command should be echoed before it is executed:
ncl> enable ncl command echo
ncl> disable ncl command echo
7.2 – OpenVMS
After you enter a command, the system responds with a display
that includes a summary of the command you entered, the UID
of the entity (if enabled) referred to in the command, and
a timestamp showing when the command was executed. On some
commands, (for example, show), the output also includes a display
of certain values.
The following is an example of a typical show command and the
resulting display:
NCL> show nsp all <Return>
Node 0 NSP
AT 1992-06-03-10:35:12.234-04:00I0.277
Status
UID = 9AF8477A-407E-11CB-...
State = On
Currently Active Connections = 14
Characteristics
Maximum Transport Connections = 200
Maximum Receive Buffers = 2000
Delay Weight = 3
Delay Factor = 2
Maximum Window = 8
DNA Version = T4.2.1
Acknowledgement Delay Time = 3
Maximum Remote NSAPS = 201
NSAP Selector = 32
Keepalive Time = 60
Retransmit Threshold = 5
Congestion Avoidance = False
A command that executes appropriately and completes its assigned
task produces a Success Response. Success Responses are not
documented in the command description sections of this manual
unless the Success Response contains arguments or the response
indicates that something other than the expected action has
occurred.
If a command does not complete successfully, you can get one or
more exception or error messages. There are three categories of
error returns for NCL commands:
o OpenVMS NCL error messages; that is, errors that occur at the
level where OpenVMS is processing NCL commands.
o Common NCL exception messages; that is, errors that occur
within NCL and which apply to more than one command.
o Command-specific exception messages, which are described with
the commands that can produce them.
Each command description in this manual includes at least one
example that shows a typical successful command with possible
resulting output.
7.3 – Displaying UIDs
Any entity that has counters or generates events is assigned a
unique identification (UID) value. A UID is a 16-byte entity
attribute that is unique throughout the network and for all time;
that is, because the creation time of the entity is included as a
portion of the UID, no two identical UIDs will ever be created.
A UID identifies a unique instance of an entity. For network
management, UIDs provide a guaranteed way to track the
characteristics and status of that precise entity instance. Each
entity having counter attributes also has a creation timestamp
identifying, simply, when the entity was created.
The UID is included in any response or event from an entity that
has a UID. Any entity that generates events or has counters must
have a UID, which is also visible as a status attribute.
Both the UID and the creation timestamp are included in any event
logging report that returns one or more counters in its argument
list.
By default on Tru64 UNIX, UID values are not displayed. The UID
value for an entity is not always needed and can clutter a show
display or an event-logging report. Use the enable ncl uid display
command if you wish to see this attribute. To turn UID displays
back off, type disable ncl uid display.
8 – Specifying Access Control
To set default access control information for a series of NCL
commands within a single NCL session (usually to be performed on a
remote system), use the SET NCL DEFAULT ACCESS command. Refer to
HELP NCL DEFAULT_CONTEXT for more information on the use of that
command.
To provide access control information to be used for the execution
of a single NCL command, you may use one of the following methods:
o Use the by prepositional phrase
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
o Specify an access control string
The access control string (ACS) consists of a user name and
password, for an account on the remote system.
For Tru64 UNIX, enter the ACS as part of the node-name
specification nodename/usr/password as follows:
ncl> show node .admin.artists/j_smith/DoNotUse session control -
_ncl> application graphics_exchange all counters
You do not need privileges to do a show operation. However,
to do a set operation, you need to have superuser access
to the system.
For OpenVMS:
NCL> show node .admin.artists"j_smith DoNotUse" session -
_NCL> control application graphics_exchange all counters
To do a show operation, you need NET$EXAMINE right on the
remote OpenVMS system. For read and write access (for example,
set, disable, enable etc.), you need NET$MANAGE right or
BYPASS priviledge on the remote system.
The use of proxy accounts is a more manageable method of
establishing access control schemes between two systems. See
the DECnet-Plus Network Management manual for more information
about controlling remote network access through the use of proxy
accounts, or refer to HELP NETWORK_MANAGEMENT ACCESS_CONTROL
PROXIES.
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.
9 – Default Context
When you wish to perform a series of commands on a particular entity
(either on your local node or a remote Phase V node), you may choose
to set your default NCL context. The SET NCL DEFAULT ENTITY command
allows you to specify an entity to be used for further NCL commands.
Similarly, the SET NCL DEFAULT ACCESS command allows you to specify
access control information.
9.1 – OpenVMS
The NET$EXAMINE right is required to issue SET NCL DEFAULT ENTITY
and SET NCL DEFAULT ACCESS commands. Refer to HELP
NETWORK_MANAGEMENT ACCESS_CONTROL RIGHTS_IDENTIFIERS for
information on rights identifiers.
Once established, default entity and access control information
will remain in effect for the duration of an NCL session until
it is modified by subsequent SET NCL DEFAULT commands. When
supplying access information, both the username and password
should be provided in a single command. Here are a few
acceptable forms of the SET NCL DEFAULT command:
NCL>SET NCL DEFAULT ENTITY -
_NCL>NODE nodename"username password" [subentity|subentities]
NCL>SET NCL DEFAULT ENTITY NODE nodename [subentity|subentities],-
_NCL>ACCESS BY USER=username, PASSWORD=password
NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password,-
_NCL>ENTITY NODE nodename [subentity|subentities]
When a SET NCL DEFAULT command contains new access information but
lacks a default node entity, as in:
NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password
NCL>SET NCL DEFAULT ENTITY [subentity|subentities],-
_NCL>ACCESS BY USER=username, PASSWORD=password
NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password,-
_NCL>ENTITY [subentity|subentities]
then the new access information is stored, but it will not be
used until some subsequent SET NCL DEFAULT ENTITY NODE command
is issued. In the following example, new access control
information is stored:
NCL>SHOW NCL DEFAULT
No NCL Default Access has been set
NCL Default Entity ()
NCL>SET NCL DEFAULT ACCESS BY USER=user1, PASSWORD=goodpassword
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity ()
but that access control information remains unused until the
default node entity is modified. The following SET command
would then result in the establishment of a connection to node
remnod using the user1 account:
NCL>SET NCL DEFAULT ENTITY NODE remnod
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity Node remnod
Once you have set a default node entity, all subsequent SET NCL
DEFAULT ENTITY [subentity | subentities] commands apply to that
node until the user attempts to modify the default node entity.
For example, now that the default node entity is remod, in order
to set the default entity to Session Control on node remnod, you
can do so without re-specifying the node entity, as in:
NCL>SET NCL DEFAULT ENTITY Session Control
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity Node remnod Session Control
To change to another subentity on the remote node, you must
include (or re-specify) any subentities beneath the node entity.
Even though the current default entity in this example is Node
remnod Session Control, you must re-specify the Session Control
subentity if you want to set default to a lower subentity on
that node. In other words, NCL would not parse the following
command because the Session Control entity needs to be
re-specified. Since the command could not be parsed, the NCL
defaults remained unchanged:
NCL>SET NCL DEFAULT ENTITY Application fal
%NCL-E-INVALIDCOMMAND, unrecognized command
SET NCL DEFAULT ENTITY \Application\ fal
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity Node remnod Session Control
Instead, this command would be necessary to change the default
to a lower subentity on node remnod:
NCL>SET NCL DEFAULT ENTITY Session Control Application fal
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity Node remnod Session Control Application fal
Note that in the example above the "fal" instance identifier
specified a particular instance of a Session Control Application.
But it is also acceptable to use wildcards to specify the default
entity. In the example below, the wildcard "*" is used as an
instance identifier to refer to all session control applications
on the default node.
NCL>SET NCL DEFAULT ENTITY Session Control Application *
NCL>SHOW NCL DEFAULT
NCL Default Access by User user1, Password xxx
NCL Default Entity Node remnod Session Control Application *
If default access control information and the default entity
were then modified, but no node entity was specified, as in:
NCL>SET NCL DEFAULT ACCESS BY USER=user2, PASSWORD=badpassword,
_NCL>ENTITY Session Control
NCL>SHOW NCL DEFAULT
NCL Default Access by User user2, Password xxx
NCL Default Entity Node remnod Session Control Application *
The new default access information would be stored, but contrary
to the default access information displayed by SHOW NCL DEFAULT,
the connection to node remnod through the user1 account will
remain in use until the default node entity is changed.
This next command would request a new connection to node remnod
using the latest default access information (through the user2
account), but the connection would fail because the password
information provided earlier for the user2 account was incorrect:
NCL>SET NCL DEFAULT ENTITY NODE remnod
%NCL-E-REQUESTFAILED, command failed due to:
-CML-E-SESSPROB, error returned from session control
-IPC-E-BADUSER, access control rejection
-NET-F-REMOTEDISCONN, connection disconnected by remote user
%NCL-E-NOCONNECTION, cannot establish CMIP connection to remote node
set ncl default entity node remnod
Whenever a connection to a default entity node fails, the default
entity will be reset to the local node entity. Default subentity
information is cleared as well because subentities are node-
specific. The default access information will be left as is, but
it will remain unused until the default node entity is reset. For
example, after the above failure to modify the default node entity,
the NCL defaults would look like this:
NCL>SHOW NCL DEFAULT
NCL Default Access by User user2, Password xxx
NCL Default Entity ()
9.2 – Tru64 UNIX
When you are using NCL commands to manage one particular
entity, either set up a default for the entity, access control
information for the entity, or both. For example:
ncl> set ncl default entity node .mfg.cadcam session control
ncl> show ncl default entity
ncl default entity = node .mfg.cadcam session control
The set ncl default access command sets up default access
control independently of the default entity. Once established,
the default access control is applied to any command where
an explicit by prepositional phrase is omitted and no user
information is given with the node name.
ncl> ! on node .admin.finance
ncl> set ncl default access by user=j_smith, password=DoNotUse
ncl> show ncl default access
ncl Default access = user name=j_smith
account=
proxy=false
ncl> show node .admin.artists session control application -
_ncl> graphics_exchange all counters
The set ncl default access overrides an embedded access control
value in the entity.
10 – Using Snapshot
The following sections describe how to use snapshot on both
Tru64 UNIX and OpenVMS.
10.1 – Tru64 UNIX
Snapshot saves all of the counter attributes available
from the specified entity at that time. You can snapshot only
counters, and the results are displayed using a subsequent
show command. For example, do either of the following:
ncl> snapshot node 0 all counters
or
ncl> snapshot node 0 all counters, to file_name
If you omit the attribute list entirely from the snapshot
command, NCL defaults to all counters.
If you do not choose a file name, NCL retains the binary data
in memory. If you enter the show command for which the remote
entity returns any counters, NCL tries to find snapshot data
in the snapshot file you specified (or within its memory, if
you did not specify a file name).
If your show command does not contain the from preposition, NCL
tries to find a corresponding snapshot in memory. If you
have not performed a snapshot command in this NCL session, NCL
displays just the raw counters.
If the show command does contain the from preposition, NCL tries
to read the specified file. If NCL cannot open the file, it
returns the appropriate error message and displays the data
returned from the entity. If a snapshot file exists, but does
not contain data from the current entity, NCL displays just the
raw counters.
If NCL succeeds in finding a saved snapshot of the entity's
counters, then it displays the counters returned by the agent.
The following example shows a typical snapshot file, in this
instance called x.tmp:
ncl> snapshot 12.80 csm sta * oct se, oct r, to x.tmp
To recall the snapshot file x.tmp, you would use the following
command:
show n 12.80 csm sta *, from x.tmp
Node 12.80 CSMA-CD Station csmacd-1
AT 1994-09-08-11:12:01.497-04:00I0.165
Snapshot Elapsed Time = +0-02:01:47.536I0.428
Current Snapshot Difference
------- -------- -----------
Counters
Octets Sent 64354851 45070297 19284554
Octets Received 34030180 27575906 6454274
To list all the snapshots that NCL is holding "in memory,"
use the command:
ncl> show ncl snapshots
To eliminate the snapshot corresponding to a value, thus
allowing counters to be displayed in the normal name=value
format, use the command:
ncl> clear ncl snapshot 50
without this, the only way to get back to a normal display
is to exit NCL and reinvoke it.
To periodically poll the value of a counter and display it
(using the snapshot format) until ^C'ed, use the command:
ncl> cmonitor entity counter
this is similar to netstat and iostat which allow you to
monitor a value by specifying an interval.
To control what the interval between polls should be, use
the commands:
ncl> set ncl cmonitor time = 5
ncl> show ncl cmonitor time
10.2 – OpenVMS
The snapshot function saves the counters' values and displays
those values. After the snapshot command is issued, the show
command can be used to display a comparison of the current
values and the registered values at later times.
The following command activates snapshot for the entity and
produces the snapshot output:
NCL> snap nsp port nsp$port_0000200f all counters
Snapshot node 0 NSP Port NSP$PORT_0000200F
at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425
Counters
Creation Time = 1991-09-18-18:55:25.59899 - 04:00 I 52.08425
User Octets Received = 932
User Octets Sent = 246
User PDUs Received = 22
User PDUs Sent = 10
.
.
.
The following show command displays the snapshot for the
entity for which snapshot was activated:
NCL> show nsp port nsp$port_0000200f all counters
Show node 0 NSP Port NSP$PORT_0000200F
at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425
Counters
Creation Time = 1994-09-18-18:55:25.59899 - 04:00 I 52.08425
Snapshot created at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425
Actual Value Snapshot Value Difference
------------- --------------- ---------
User Octets Received 2414 932 1482
User Octets Sent 262 246 16
User PDUs Received 25 22 3
User PDUs Sent 11 10 1
. . . .
. . . .
. . . .
Snapshot information is only retained for the duration of an NCL
session. Therefore, the snapshot command and subsequent show
commands must be issued at the NCL> prompt rather than at the
DCL prompt. To gather snapshot information from a remote node,
you can either set the ncl default to the remote node entity or
include the nodename in each ncl command, as long as the
commands are issued within the same NCL session.
11 – Customizing NCL
You can customize your NCL environment using optional
initialization files. In addition, on OpenVMS you have the
option of using a keypad definition file. Tru64 UNIX
allows you to define symbols for use with NCL.
Setting a default NCL context is another way of customizing
your NCL environment. This allows you to specify a particular
entity or default access control information to be used for
the remainder of an NCL session. For information on setting a
default NCL context, refer to HELP NCL DEFAULT_CONTEXT.
11.1 – Initialization File
The initialization file contains NCL commands that are executed
when you start NCL; that is, before you receive the NCL prompt.
Alternatively, the initialization file is executed prior to
executing an NCL script file that is specified as part of a DCL
command line. In the following example, the initialization file
will be executed before the ROUTING.NCL script:
$ ncl @routing.ncl
11.1.1 – OpenVMS
NCL uses the default file name SYS$LOGIN:NCL$INIT.COM unless
you have defined an alternative file use the NCL$INIT logical.
To use NCL$NODEA_INIT.COM as an initialization file, use the
following DCL define command:
$ define ncl$init ncl$nodea_init.com
When NCL starts up, it will check for the file
NCL$NODEA_INIT.COM, and if it exists, will execute the ncl
commands within it.
11.1.2 – Tru64 UNIX
For Tru64 UNIX, if the file .nclrc exists in the user's
top level directory, the command within it will be executed
automatically when NCL is started.
11.2 – Key Definition File (OpenVMS)
The key definition file associates commonly used NCL commands
with keys on the keypad. Use the define/key command to create
the definition.
NCL uses the default file name SYS$LOGIN:NCL$KEYDEF.INIT unless
you have defined an alternative file use the NCL$KEYDEF logical.
The SYS$EXAMPLES:SETUP_NCL_KEYPAD.COM command file creates files
that allow you to execute commonly used NCL commands using one or
two keystrokes on the keypad. This command file should be executed
from the system account. It works in a cluster environment, but
only for those roots on a single system disk and only for those
nodes booted into the cluster at the time you execute the command
file.
$ @sys$examples:setup_ncl_keypad
This command file creates Keypad definitions files for NCL
to be used with the HP DECnet-Plus for OpenVMS products. It
creates files in SYS$MANAGER: and SYS$HELP:. All files begin with
NCL$KEYDEF. A copy of this file will be made in SYS$UPDATE:
In a cluster environment, NCL scripts are created in SYS$SPECIFIC:
directories for each node on this system disk.
This file may be copied to any system running HP DECnet-Plus
for OpenVMS.
Note: Please add
"$ DEFINE/SYSTEM NCL$KEYDEF SYS$MANAGER:NCL$KEYDEF.INIT"
to your OpenVMS startup procedure.
Continue? [Y/N Def: Y]:
Creating NCL Key Definition Init File...
Creating NCL Key Definition Help Text Files...
Installing in a cluster environment. Scripts created for each
member...
%SYSMAN-I-ENV, current command environment:
Clusterwide on local cluster
Username SYSTEM will be used on nonlocal nodes
%SYSMAN-I-OUTPUT, command execution on node NODEA
NSP Show Nodes Complete...
OSI Show Nodes Complete...
Show Routing Adjacencies Complete...
%SYSMAN-I-OUTPUT, command execution on node NODEB
NSP Show Nodes Complete...
OSI Show Nodes Complete...
Show Routing Adjacencies Complete...
%SYSMAN-I-OUTPUT, command execution on node NODEA
%SYSMAN-I-OUTPUT, command execution on node NODEB
$
Once in NCL, keypad <EMPHASIS>(PF4) displays an introduction
and keypad PF2 provides help on the keypad layout.
11.3 – Defining Symbols (Tru64 UNIX)
You can define symbols to represent commonly used
class/instance pairs of NCL commands. Symbol definitions are
provided to cut down on the amount of repetitive typing you must
perform. Use the define and read control verbs to create and
verify symbol definitions. For example:
define ncl symbol NAME = "VALUE"
undefine ncl symbol [ NAME | * ]
show ncl symbol [ NAME | * ]
list ncl symbol [ NAME | * ]
ncl> define ncl sym rc1 = "routing circuit circuit-1"
ncl> show rc1
Node 0 Routing Circuit circuit-1
AT 1994-07-14-15:10:10.976-04:00I0.226
Identifiers
Name = circuit-1
The first parameter to the define command is the symbol and
all remaining text is the equivalence string (the translation
of the symbol). The symbol can be from 1 to 500 characters in
length and contain any ISO latin-1 characters (?). At definition
time, the equivalence string is not parsed. NCL will parse the
full NCL command and any symbols that form part of the command.
To delete symbols, use the undefine verb. For example:
ncl> undefine Ether,Remote_Node ! To delete specific symbols
.
.
.
ncl> undefine * ! To delete all remaining symbols
.
.
.
You can use "." to mean "the entity used in the last command."