![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
You can recall commands by string by starting the line with a '^' or by ending a line by pressing Find, for example:
ncl> ^ena Return
or
ncl> ena Find
Either of these command lines will recall the last command that started with "ena." <>
The following sections describe NCL command output for both Digital UNIX and 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 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 1991-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
ncl>
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:
# ncl show tree all SYNTAX ERROR: No match was found for this string show tree all ---- ^
# ncl set routing probe rate = 0 RANGE ERROR: The minimum value for this attribute is 1 set routing probe range = 0 ------------------------- ^
Node 0 CSMA-CD AT 1992-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
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 one line or two 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
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. With 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-800B-AA000400784D
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
Acknowledgment Delay Time = 3
Maximum Remote NSAPS = 201
NSAP Selector = 32
Keepalive Time = 60
Retransmit Threshold = 5
Congestion Avoidance = False
ncl>
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 book 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:
Each command description in this manual includes at least one example that shows a typical successful command with possible resulting output.
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 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.
The UID value for an entity is not always needed and can clutter a show display or an event-logging report. By default, UID values are not displayed. 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.
When using NCL commands to manage entities on remote systems in the network, use the appropriate method of supplying access control information as follows:
by user=username, password=password, account=account, proxy={TRUE/FALSE}
ncl> ! On node .admin.finance ncl> show node .admin.artists session control application - _ncl> graphics_exchange all counters, by user=j_smith, password=DoNotUse . . .
ncl> show node .admin.artists/j_smith/DoNotUse session control application - _ncl> graphics_exchange all counters
ncl> show node .admin.artists"j_smith DoNotUse" session control application - _ncl> graphics_exchange all counters
The use of proxy accounts is a more manageable method of establishing
access control schemes between two systems. The DECnet-Plus for
OpenVMS Network Management guide contains more information about
controlling remote network access through the use of proxy accounts.
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.<>
When you are using NCL commands to manage one particular entity, set up a default for the entity, set up access control information for the entity, or both. (For OpenVMS only, refer to Section 1.1 for further information on the rights identifiers required to access a remote or local node.) 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.
The following sections describe snapshot, a method of capturing and storing information about counters, on both Digital UNIX and OpenVMS operating systems.
Snapshot saves all of the counter attributes available from the specified entity at that time. You can use 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 contains 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 1992-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 command, the only way to get back to a normal display is to exit NCL, then reinvoke it.
To periodically poll the value of a counter and display it (using the snapshot format) until ^C is issued, use the following 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
The snapshot function saves the counters' values and displays those values. After you issue the snapshot command, you can use the show command 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 1995-09-18-19:49:11.76078 - 04:00 I 52.08425 Counters Creation Time = 1995-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 1995-09-18-19:49:11.76078 - 04:00 I 52.08425
Counters
Creation Time = 1995-09-18-18:55:25.59899 - 04:00 I 52.08425
Snapshot created at 1995-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
. . . .
. . . .
. . . .
With DECnet-Plus for OpenVMS, you can customize your NCL environment by using either the optional initialization file or optional key definition file.
$ ncl @routing.ncl
NCL uses the default file names listed below, unless you have defined alternative files using the logical names listed:
| File Type | Default | Logical Name |
|---|---|---|
| Initialization | SYS$LOGIN:NCL$INIT.COM | NCL$INIT |
| Key definition | SYS$LOGIN:NCL$KEYDEF.INIT | NCL$KEYDEF |
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 checks for the file NCL$NODEA_INIT.COM, and if
it exists, executes the NCL commands within the file.<>
For Digital UNIX, if the file .nclrc exists in the user's top level directory, the command within the file is executed automatically when NCL is started.<>
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. You should execute this command file 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 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 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 PF4 displays an introduction and keypad PF2 provides help on the keypad layout.
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."
The decnet_register tool is an executable image located in SYS$SYSTEM:. It centralizes and simplifies namespace management tasks by replacing functionality previously provided by both the decnet_dns_register and decnet_loc_register command procedures located in SYS$MANAGER:.
The decnet_register tool manages information in both the DECdns distributed name service and the Local namespace. The decnet_register Manage command assists with setup tasks for the DECdns name service. For example, it creates namespace directories and access groups, and enables autoregistration.
The decnet_register tool has both command line and forms interfaces. Online help information is provided with the tool.
See the network management guide for your operating systems for more information and instructions on registering, deregistering, modifying, and renaming node names. See the DECnet-Plus DECdns Management guide for information about dnscp and for detailed instructions on managing the namespace and its contents.
DECnet-Plus lets you manage remote systems running Phase IV software from a system running DECnet-Plus network management. To execute an NCP command, follow the specific platform instructions.
Because NCL is not backwards compatible with NCP, NCP scripts do not
work under the NCL utility. To run NCP scripts, you need to use the
convert command in the decnet_migrate utility. For
more information on this utility, see the network management guide for
your operating system.
Enter the following within the NCL utility:
ncl> ncp tell foobar show executor characteristics
You must enter the entire NCP command at the ncl> prompt or type ncl ncp at the system prompt. For example:
%ncl ncp tell foobar show executor characteristics <>
You can use the NCP emulator tool to manage remote Phase IV nodes with the TELL and SET EXECUTOR NODE commands. For example, to zero the executor counters on a remote Phase IV node from a local Phase V node, enter the following:
$ run sys$system:ncp NCP> tell remnod"account password" zero exec counters
The NCP emulator tool is not intended for management of Phase V nodes. Refer to DECnet-Plus for OpenVMS Network Management guide for more information about the NCP emulator tool. For example, the following error is returned when an NCP emulator command is attempted on a Phase V system without specifying a remote Phase IV system:
NCP> zero exec counters %NCP-W-SYSMGT, System-specific management function not supported <>
The console carrier provides access to the remote console subsystem (ASCII console) of a network server on a LAN. The console carrier interface does not use NCL. Instead, you can enter commands at the operating system to use the console carrier.
For further information about the console carrier, consult the network management documentation for your operating system.
The Node module has one entity, the global node entity, which
crowns the hierarchy represented in the entity model described by the
Digital Network Architecture. All other modules described in this book
are subordinate to the Node module. When enabled, each node is visible
to all other nodes on the network. Access to a node's entities must be
made through the node.
To enable a node, use the command enable nodenode-name with either the local CMIP listener or the address watcher argument. For remote nodes with valid names, enabling the address watcher changes the node state from off (service interface disable) to on (service interface enabled). The CMIP listener must be enabled on that node. If the CMIP listener is not enabled, the node cannot accept management commands, and therefore cannot be turned on. For the node on which the director is executing, two enable directives may be necessary to accomplish the same action. The first enables the CMIP listener, and the second enables the address watcher, for example:
ncl> enable node node-name function [=] {cmip listener}
{address watcher} <>
Figure 2-1 shows the hierarchical relationship of the Node global entity to all of the other (local) entities that are described in this book.
Figure 2-1 The Node Global Entity in the DNA Entity Hierarchy
The node entity is the only entity in the Node module. All
other entities described in this book are subordinate to the
node entity, as demonstrated by the components of their entity
names.
enable [node node-id] function
function
disable [node node-id] function
function
(OpenVMS)
rename [node node-id] new name
full-name
show [node node-id] [all [attributes] | all
characteristics | all counters | all identifiers | all status]
Commands that manage a node entity specify the node using this format:
node node-id
Node being managed by the command.
NCL_PROFILE_002.HTML OSSG Documentation 2-DEC-1996 12:47:36.46
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.