VSI DECnet-Plus for OpenVMS Network Control Language Reference

Operating System and Version:
VSI OpenVMS IA-64 Version 8.4-1H1 or higher
VSI OpenVMS Alpha Version 8.4-2L1 or higher

Preface

This book describes the syntax and features of the Network Control Language (NCL), and the NCL commands that you use for network management modules.

1. About VSI

VMS Software, Inc. (VSI) is an independent software company licensed by Hewlett Packard Enterprise to develop and support the OpenVMS operating system.

2. Intended Audience

This book is written for network managers responsible for managing DECnet-Plus for OpenVMS networks. It also contains NCL syntax for management entities and management options supported by DECnet-Plus for UNIX.

3. Document Structure

The manual consists of the following chapters and appendices:

Chapter 1, Introduction to NCL

Provides an overview of the functions provided by NCL.

Chapter 2, Node Module

Describes the Node module.
Chapter 3, Alias Module (OpenVMS)Describes the Alias module.
Chapter 4, CSMA-CD ModuleDescribes the CSMA-CD module.
Chapter 5, DCMP Module (OpenVMS)Describes the DCMP module.
Chapter 6, Device ModuleDescribes the Device module.
Chapter 7, DECdns ModulesDescribes the DECdns modules.
Chapter 8, DECdts ModuleDescribes the DECdts module.
Chapter 9, Event Dispatcher ModuleDescribes the Event Dispatcher module.
Chapter 10, FDDI ModuleDescribes the FDDI module.
Chapter 11, Frame Module (OpenVMS)Describes the Frame module.
Chapter 12, HDLC ModuleDescribes the HDLC module.
Chapter 13, LAPB ModuleDescribes the LAPB module.
Chapter 14, LLC2 ModuleDescribes the LLC2 module.
Chapter 15, Loopback Application ModuleDescribes the Loopback Application module.
Chapter 16, Modem Connect ModuleDescribes the Modem Connect module.
Chapter 17, MOP ModuleDescribes the MOP module.
Chapter 18, NSP ModuleDescribes the NSP module.
Chapter 19, OSAK ModuleDescribes the OSAK module.
Chapter 20, OSI Transport ModuleDescribes the OSI Transport module.
Chapter 21, Routing ModuleDescribes the Routing module.
Chapter 22, Session Control ModuleDescribes the Session Control module.
Chapter 23, Token Ring Module (UNIX)Describes the Token Ring module.
Chapter 24, X.25 Access ModuleDescribes the X.25 Access module.
Chapter 25, X.25 Client Module (OpenVMS)Describes the X.25 Client module.
Chapter 26, X.25 Protocol ModuleDescribes the X.25 Protocol module.
Chapter 27, X.25 Relay ModuleDescribes the X.25 Relay module.
Chapter 28, X.25 Server ModuleDescribes the X.25 Server module.
Chapter 29, XOT Module (OpenVMS I64 and OpenVMS Alpha)Describes the XOT module.
Appendix A, Interpreting NCL Error Messages

Lists common error messages.

Appendix B, Common Data Types for NCLDescribes common data types.

4. Related Documents

DECnet-Plus for OpenVMS documentation is available in two sets:

  • Documentation set for DECnet-Plus for OpenVMS

  • Supplemental X.25 for OpenVMS documentation set

Table below lists the documentation that supports this version of the DECnet-Plus for OpenVMS software.

Table 1. DECnet-Plus for OpenVMS Documentation
DocumentContents
DECnet-Plus for OpenVMS Documentation Set
VSI DECnet-Plus for OpenVMS Introduction and User's GuideDescribes the manuals in the documentation sets, outlines the DECnet-Plus for OpenVMS features and tools, explains how to use and manage an end system, and provides a comprehensive glossary of DECnet terminology.
VSI DECnet-Plus for OpenVMS Release NotesDescribes changes to the software; installation, upgrade, and compatibility information; new and existing software problems and restrictions; and software and documentation corrections.
VSI DECnet-Plus Planning GuideProvides configuration and planning guidelines, including namespace planning information, to help you transition a network from the DECnet Phase IV to DECnet Phase V architecture.
VSI DECnet-Plus for OpenVMS Installation and Configuration

Explains how to install and configure the DECnet-Plus for OpenVMS software using the three configuration options (FAST, BASIC, and ADVANCED). Also explains how to modify an existing configuration.

Explains how to configure the X.25 functionality included with the DECnet- Plus for OpenVMS VAX software (formerly provided by the VAX P.S.I. Access and VAX P.S.I. products).

Explains how to install the separate X.25 for OpenVMS software product available for OpenVMS I64 and OpenVMS Alpha systems. For configuration information, see the VSI X.25 for OpenVMS Configuration manual.

Explains how to install and configure the optional OSI applications software components (OSI Applications Kernel (OSAK), OSI File Transfer, Access, and Management (FTAM), and OSI Virtual Terminal (VT)).

VSI DECnet-Plus for OpenVMS Network Management GuideProvides in-depth information about how to monitor and manage DECnet-Plus for OpenVMS systems using various tools and Network Control Language (NCL) commands. Explains how to set up and use event dispatching and how to perform all day-to-day management tasks for the local DECnet- Plus for OpenVMS node, including setting up OpenVMS clusters, managing security, downline loading, and monitoring the network.
DECnet-Plus for OpenVMS Installation and Quick ReferenceProvides quick-reference information about the tools that help you manage and monitor a DECnet-Plus network. Use this guide with the VSI DECnet-Plus for OpenVMS Network Management Guide.
VSI DECnet-Plus for OpenVMS Network Control Language Reference GuideOutlines command descriptions and examples for all Network Control Language (NCL) commands that you execute to manage, monitor, and troubleshoot the network. Begins with an orientation chapter that contains information about how to execute NCL commands, followed by a command chapter for each module in the DECnet Phase V layered model.
VSI DECnet-Plus for OpenVMS Problem Solving GuideExplains how to isolate and solve DECnet problems in an OpenVMS environment that can occur while the network is in operation. Includes information about how to perform loopback tests and how to use the DTS/DTR utility to solve problems.
VSI DECnet-Plus for OpenVMS DECdns Management GuideExplains VSI DECnet-Plus Distributed Name Service (DECdns) concepts and how to manage a DECdns distributed namespace. Use this manual with the VSI DECnet-Plus Planning Guide.
VSI DECnet-Plus for OpenVMS DECdts ManagementIntroduces VSI DECnet-Plus Distributed Time Service (DECdts) concepts and describes how to manage the software and system clocks.
VSI DECnet-Plus DECdts ProgrammingContains DECdts time routine reference information and describes the time-provider interface (TPI).
VSI DECnet-Plus OSAK ProgrammingExplains how to use the OSAK (OSI Applications Kernel) interface to create OSI (Open Systems Interconnection) applications for any supported operating system.
DECnet-Plus OSAK Programming ReferenceProvides reference information on using the OSAK interface to create OSI applications on any supported operating system.
VSI DECnet-Plus OSAK SPI Programming Reference ManualProvides reference information about using the OSAK session programming interface (SPI) to create OSI applications on any supported operating system.
VSI DECnet-Plus FTAM and Virtual Terminal Use and ManagementExplains how to use and manage FTAM (File Transfer, Access, and Management) software for remote file transfer and management and VT (Virtual Terminal) for remote login to OSI-compliant systems.
VSI DECnet-Plus FTAM ProgrammingExplains how to access the FTAM protocol through FTAM’s API (application programming interface).
VSI DECnet-Plus for OpenVMS ProgrammingContains information about how to design and write an application that follows a client/server model and uses the OpenVMS Interprocess Communication ($IPC) system service and the transparent and nontransparent communication with the queue Input/Output ($QIO) system service. Explains how to write programs using the OpenVMS system services to communicate with OSI transport services. Provides information about the Common Management Information Service (CMISE) API.
DECnet/OSI for VMS CTF UseExplains how use the Common Trace Facility (CTF) troubleshooting tool to collect and analyze protocol data from networking software.
Supplemental X.25 Documentation Set
VSI X.25 for OpenVMS ConfigurationDiscusses how to configure X.25 for OpenVMS on an OpenVMS I64 or OpenVMS Alpha system. For information about how to configure the X.25 functionality on OpenVMS VAX systems, see the VSI DECnet-Plus for OpenVMS Installation and Configuration manual.
VSI X.25 for OpenVMS Management GuideExplains how to manage and monitor an X.25 system using network tools.
VSI X.25 for OpenVMS Security GuideExplains the X.25 security model and the tasks required to set up and manage X25 security.
VSI X.25 for OpenVMS Problem SolvingProvides guidance on how to solve problems that can occur while using an X.25 system.
X.25 for OpenVMS UtilitiesExplains how to use and manage X.25 Mail and X.29 communications.
X.25 for OpenVMS AccountingExplains how to use X.25 accounting to obtain performance records and information about how X.25 is being used.
X.25 for OpenVMS ProgrammingExplains how to write X.25 and X.29 programs to perform network operations.
X.25 for OpenVMS Programming ReferenceProvides reference information for X.25 and X.29 programmers.
DECnet/OSI for VMS VAX WANDD ProgrammingProvides information about using the programming interface for the WANDD devices.

5. Terminology

An adjacent node is a node connected to the local node by a single physical line.

These terms are used interchangeably:
  • Transition and migration

  • Phase IV and DECnet Phase IV

  • Phase V and DECnet Phase V

  • End system and end node

  • Intermediate system and router

  • Running database and operational database

  • Sink node and logging node

6. VSI Encourages Your Comments

You may send comments or suggestions regarding this manual or any VSI document by sending electronic mail to the following Internet address: . Users who have VSI OpenVMS support contracts through VSI can contact for help with this product.

7. OpenVMS Documentation

The full VSI OpenVMS documentation set can be found on the VMS Software Documentation webpage at https://docs.vmssoftware.com.

8. Typographical Conventions

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Cluster systems or clusters in this document are synonymous with VMScluster systems.

The contents of the display examples for some utility commands described in this manual may differ slightly from the actual output provided by these commands on your system. However, when the behavior of a command differs significantly between OpenVMS Alpha and Integrity servers, that behavior is described in text and rendered, as appropriate, in separate examples.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:
ConventionMeaning

Ctrl/ x

A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x

A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

Return

In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

A horizontal ellipsis in examples indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.

  • The preceding item or items can be repeated one or more times.

  • Additional parameters, values, or other information can be entered.

.
.
.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( )

In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ]

In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

[ |]

In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are options; within braces, at least one choice is required. Do not type the vertical bars on the command line.

{ }

In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

bold text

This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic text

Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT

Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace type

Monospace type indicates code examples and interactive screen displays.

In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

-

A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers

All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

9. Acronyms

The following acronyms are used throughout this book:

ACSE

Association Control Service Element

ASE

application service element

ASN.1

Abstract Syntax Notation One

BER

basic encoding rules

CMIP

Common Management Information Protocol

CML

CMIP Management Listener

DAP

Data Access Protocol

DCS

defined context set

DDCMP

Data Communications Message Protocol

DECdns

Distributed Name Service

NA

Network Architecture

DTR

DECnet Test Receiver

DTS

DECnet Test Sender

ES–IS

end system to intermediate system protocol

EVL

Event Dispatcher

EVL

event logger

FAL

file access listener

FTAM

File Transfer, Access, and Management

HDLC

High-Level Data Link Control

MIR

loopback mirror

MOP

Maintenance Operations Protocol

NSAP

network service access point

NCL

Network Control Language

NSP

Network Services Protocol

OSI

Open Systems Interconnection

OSUL

Open Systems Upper Layer

PCI

protocol control information

PDU

protocol data unit

PPCI

presentation protocol control information

PSDN

packet switching data network

SPCI

Session Protocol Control Information

SPDU

session protocol data unit

SSDU

session service data unit

TCP/IP

Transmission Control Protocol/Internet Protocol

TPDU

transport protocol data unit

TSDU

transport service data unit

XOTX.25 over TCP/IP

Chapter 1. Introduction to NCL

This reference guide describes how to use the Network Control Language (NCL) command line interface. You should be familiar with the concepts and terminology of the entity model of network management, as described in the VSI DECnet-Plus for OpenVMS Network Management Guide.

This chapter tells you how to use NCL in the following ways:
  • Invoke, use, and exit the Network Control Language

  • Issue NCL commands from your terminal

  • Define common data types for NCL

  • Interpret NCL error messages

1.1. Rights Identifiers Required for Use of NCL

DECnet-Plus for OpenVMS uses OpenVMS rights identifiers to check access on all manageable entities. This differs from the Phase IV software, which used OpenVMS privileges for access to the permanent database and for write access. Read access to the volatile database in Phase IV was unprotected.

1.1.1. Access to Local Network Data

In DECnet-Plus for OpenVMS, the rights identifier NET$EXAMINE grants a user read access to the network configuration data. The NET$MANAGE rights identifier grants read and write access to the network configuration data, and NET$SECURITY grants ability to set default accounts. These new rights allow the network manager to restrict access to network parameters. Access is granted to an individual user by means of the Authorize utility on OpenVMS. The following command examples grant access:
UAF> grant/id net$examine Joe  ! Grant user Joe read access to local network data
UAF> grant/id net$manage  Joe  ! Grant user Joe read/write access to local network data
UAF> grant/id net$security Joe  ! Grant user Joe ability to set default accounts

In lieu of NET$MANAGE rights, the BYPASS privilege grants read and write access.

When issuing NCL commands to the local node (for example, NCL SHOW ALL or NCL SHOW NODE 0 ALL), the rights of the executing process determine whether access is granted.

1.1.2. Access to Remote Network Data (OpenVMS)

When issuing NCL commands to the remote node (for example, NCL SHOW NODE remote-node-name ALL or NCL SET NCL DEFAULT ENTITY NODE remote-node-name), a connection is established to the CML application on the remote node. Access checks performed on the remote node are dependent on the account the remote CML application is running in (on an OpenVMS node). When the connection comes into an OpenVMS machine, a process is created to run the CML application. The account used is determined in the following order:
  1. If explicit access control is specified, the specified account is used.

  2. If there is a default account for the application receiving the request, it is used.

  3. If a proxy account is specified, or there is a default proxy account for the remote user, it is used.

  4. If none of the above are specified, the session entity is checked for a default nonprivileged account to use.

If the account that runs the CML application does not have the NET$EXAMINE for read access, or NET$MANAGE identifier for read and write access, then the access is denied by the management agent.

The manager of the remote node must take explicit action to allow an individual user access to the network configuration information. For example:
  • Run the Authorize utility and grant an account the proper rights

  • Run Authorize and create a proxy account and grant the proxy account the proper rights

  • Determine the user name associated with the SESSION CONTROL APPLICATION CML. Run the Authorize utility to ensure that the account has NET$EXAMINE for read-only access.

The last option is one of the selections offered by NET$CONFIGURE when configuring the application database. If you select a default account for the CML application, NET$CONFIGURE grants NET$EXAMINE right to that account by default.

1.2. Network Management Graphical User Interface

You can access NCL through either a command line interface or graphical user interface (GUI). The GUI allows network managers to view the status of network components and control those components from a Motif-based window interface. The GUI interface is located at sys$system:net$mgmt.exe (NET$MGMT).

This utility provides a hierarchical graphical approach to the management of DECnet-Plus. The manageable components of DECnet-Plus (modules, entities, and subentities) are represented in a tree-like structure below the icon that represents the node you are managing. This provides an easy way to familiarize yourself with the organization of these manageable entities. If you choose to enable the displaying of NCL commands from the Default Actions pull-down menu, this utility can also help familiarize you with NCL syntax.

In addition to issuing NCL commands on your behalf, NCL GUI can also perform task-oriented functions that involve many NCL commands or are complex in some way. The currently supported NCL GUI tasks are:
  • show known links
  • show known node counters
  • check transports

The same rights required to run NCL are also required to run this utility.

For further information, refer to the VSI DECnet-Plus for OpenVMS Network Management Guide.

1.3. Getting Started with NCL

You can issue NCL commands from a terminal or from a command file. You can use NCL to manage network entities on local and remote nodes. If you are familiar with Phase IV network management and the Network Control Program (NCP), you can use the decnet_migrate utility as an option to map NCP commands to their NCL equivalents. See the VSI DECnet-Plus for OpenVMS Network Management Guide for further details.

1.3.1. Invoking NCL

There are several methods of invoking the interactive NCL utility:

  1. Type run sys$system:ncl at the DCL prompt $:
    $ run sys$system:ncl
    ncl>
  2. Define a symbol at the DCL prompt (or insert the symbol in your LOGIN.COM file) and then type NCL at the DCL prompt as follows:

    $ ncl :== $ sys$system:ncl
    $ ncl
    ncl>
  3. Enter an NCL command line.
    $ ncl any ncl command

    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.COM file.

  4. Enter MCR at the DCL prompt:

    $ mcr ncl
    ncl>
  5. Enter an MCR command:
    $ mcr ncl any ncl command
    $

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:

  • To abort an NCL operation, press Ctrl/C or Ctrl/Y.

  • 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
  • To indicate comments that are not to be read by the system, use an exclamation point (!) anywhere in a command line.

  • To exit from NCL, type exit or press Ctrl/Z at the ncl> prompt.

1.3.2. Accessing Online NCL Help Information

When you enter Help, you enter a standard help library containing descriptions of the network management entities and their attributes. NCL online help is a quick reference in addition to this book.

To access online NCL Help in OpenVMS, type help at the ncl> prompt. For UNIX, type a question mark (?). A list of available topics immediately appears, for example:
ncl> help or ?
  Information available:

  add        advertise  block      boot       change     clear      connect
  create     define_(Tru64_UNIX)   delete     Directory_Module      disable
  disconnect dump       echo       enable     Entity_Hierarchy
  Event_Messages        flush_(OpenVMS)       getnif     getsif     ignore
  limit      load       loop       NCL_Introduction      Network_Management
  pass       ping_(IP_Routers)     Please_Read_Me        query
  read_(Tru64_UNIX)     remove     rename     reset      restrict   set
  show       shut       shutdown   snapshot   SNA_Peer_Server_Module
  start      startloop  stop       stoploop   synchronize           test
  testevent  undefine_(Tru64_UNIX) unlimit    update     zero

  Topic?
The NCL entities are listed by verb, event message, module description, and data type. You must type in the topic name exactly as you see it. For example, to find the syntax for adding an X25 Relay Client subentity, you would do as follows:
Topic? add

ADD

  Additional information available:
  modem_connect    mop         osi_transport  routing
  session_control  x25_access  x25_protocol   x25_relay
  x25_server

ADD Subtopic?
At this prompt you type x25_relay:
ADD Subtopic? x25_relay
ADD

  x25_relay

    Additional information available:

    client     pvc

ADD x25_relay Subtopic?
At this prompt you type client:
ADD x25_relay Subtopic? client

ADD

  x25_relay

    client

         add  [node  node-id] x25 relay client client-name
               filters
               rights identifiers



      Additional information available:

      Characteristics       Identifiers

ADD x25_relay client Subtopic?

Continue down the hierarchy exactly as it appears in the syntax section of each entity module, as illustrated in Part 2 of this book.

NCL help includes several non-verb help topics that provide additional information about using NCL. The following display shows these help topics and their subtopics:

Entity_Hierarchy
  Additional information available:

  Node       DNS_Clerk  DNS_Server DSA        DTSS       Event_Dispatcher
  Alias_(OpenVMS)       Session_Control       OSAK       NSP
  OSI_Transport         Routing    X25_Protocol          X25_Access
  X25_Client_(OpenVMS)  X25_Relay_(Alpha)     X25_Server XOT_(OpenVMS_Alpha)
  LAPB       CSMA-CD    LLC2       MOP        HDLC       DDCMP_(OpenVMS_VAX)
  FDDI       Modem_Connect         Device     Frame_(OpenVMS)
  Token_Ring_(Tru64_UNIX)          Loopback_Application

Event_Messages
  Additional information available:

  csma-cd_station       ddcmp_link_(OpenVMS_VAX)         device_unit
  dtss       event_dispatcher      fddi_station          hdlc_link  lapb_link
  llc2_sap   modem_connect_line    mop_circuit           node       nsp
  osak       osi_transport         routing    session_control
  token_ring_(Tru64_UNIX)          x25_access x25_client_(OpenVMS)
  x25_protocol          x25_relay_(Alpha)     x25_server xot_(OpenVMS_Alpha)

NCL_Introduction
  Additional information available:

  Invoking_NCL                     Creating_Logs         Common_Commands
  Abbreviation_of_Commands         Syntax     Recalling_Commands    Output
  Specifying_Access_Control        Default_Context       Using_Snapshot
  Customizing_NCL

Network_Management
  Additional information available:
  Access_Control        Naming_Service_Management
  Remote_Node_Management           Logical_Names_(OpenVMS)
  Startup_Scripts_(OpenVMS)        Shutdown_and_Restart_(OpenVMS)
  MOP_(OpenVMS)         Event_Dispatcher_(OpenVMS)       Running_Over_TCP-IP
  Tools

Please_Read_Me
  Additional information available:

  Using_NCL_Help        Overview_of_NCL_Help Entity_Organization
  Managing_Entities_Using_NCL
A DECnet-Plus help file has been added to the DCL help library. To invoke the help, enter the following command:
$ help decnet-plus

1.3.3. Creating Log Files

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 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. The default file extension for an NCL log file is .ncl. The utility returns an error message if a log file does not exist.

Use the disable ncl logging command at any time to turn off NCL logging or to exit NCL.

You can execute commands saved in an NCL log file during subsequent NCL utility sessions. However, you must ensure that the proper context for the commands in the log file has been established. Check the contents of an NCL log file before running it in later utility sessions.

1.3.4. Connecting to a Remote Node by Address

Under normal conditions, you can identify the remote node by name in the NCL command. However, if the name service is interrupted or unavailable, you can still reach remote nodes to perform management functions. You can use either the remote node's Phase IV address (if the remote node is configured to have one), or the remote node's network services access point (NSAP). Refer to the VSI DECnet-Plus Planning Guide for 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
ncl> show node net$49000CAA000400053020 routing circuit syn-0-0

1.4. Common NCL Commands

The following sections briefly describe a set of NCL commands supported by most network management entities:
  • 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; they are described here to prevent unnecessary repetition throughout the book.

In addition to these NCL commands, there are a number of commands that apply only to specific entities; for example, the rename command for the Node entity, or the dump and load commands for the Device Unit entity.

1.4.1. add and remove

Some characteristic attributes have a value that consists of a set of values. Use the add command to add one or more new values to a set value:
ncl> add node 0 osi transport cons filters {filter_2,filter_3}

This command line adds two new values, filter_2 and filter_3, to the set of values represented by the cons filters characteristic of the OSI Transport entity. The values are enclosed in { }, and if more than one value is to be added in the same command, each value is separated from the previous value by a comma.

To specify the empty set (that is, a set with no values), specify { } as the value.

Similarly, use the remove command to remove one or more values from a set value:
ncl> remove node 0 osi transport cons filters {filter_3}

This command line removes the value filter_3 from the set.

Use the add and remove commands only on characteristics with set values (as indicated in the description of the characteristic).

You can also use the set command to change the values of a set-valued characteristic. However, the set command replaces the current contents of the set with the values you specified.

1.4.2. create and delete

Use the create command to create a new instance of an entity. Most entities support the create command; however, some entities are created automatically by software, and so do not support the create command. For example, entities that correspond to communications links are usually created dynamically as these links are opened.

Use the delete command to delete an instance of an entity. As with create, most entities support the delete command; however, some entities are deleted automatically by software, and so do not support the delete command. For example, entities that correspond to communications links are usually deleted dynamically as these links are closed. You cannot delete an entity if it has child entities; you must delete all child entities before you can delete the parent entity. It is usually, though not always, the case that you must disable an entity before you can delete it.

1.4.3. disable and enable

Many entities have a status attribute called state, whose value reflects the current operational state of the entity. The value of state is usually either:

off

The entity is disabled. In this state, the entity exists and can be manipulated in various ways (for example, by having its characteristics modified), but will not perform its primary functions.

on

The entity is enabled. In this state, the entity is fully operational.

Use the disable command to place the entity in its disabled (off) state. Many entities do not permit you to modify their characteristics while they are enabled, so you must use the disable command before using the add, remove, or set commands. Also, it is often the case that you cannot delete an entity while it is enabled, so you must use the disable command before using the delete command:
ncl> disable modem connect line line-1

This command line disables the entity to suspend its operation temporarily and suspends operation of the corresponding physical line.

Use the enable command to place the entity in its enabled (on) state. Most entities do not become operational immediately when you create them; you must use the enable command after the create command. If you disable an entity to modify its characteristics or to suspend its operation for a time, you must use the enable command to make the entity operational again.

1.4.4. set

Use the set command to modify one or more attributes of an entity:
ncl> set node 0 osi transport delay factor=6,delay weight=10

This command line modifies two characteristics of the OSI Transport entity. If you specify more than one characteristic in a set command, use a comma to separate each characteristic and its value.

If you specify a characteristic name, but no value, the characteristic is set to its default value. The following example sets delay factor to its default value, 4:
ncl> set node 0 osi transport delay factor
Use set to give a value to a characteristic whose value is a set, for example:
ncl> set node 0 osi transport cons filters={filter_2,filter_3}
However, note the difference between this command and the following command:
ncl> add node 0 osi transport cons filters={filter_2,filter_3}

The set command gives the cons filters characteristic a set value with two components: filter_2 and filter_3; if the set previously had other values, these are lost. The add command, on the other hand, adds the values filter_2 and filter_3 to whatever values the characteristic already has; any other current values are retained.

To specify the empty set (that is, a set with no values), specify { } as the value.

You can change the set of attributes called characteristics only by direct management commands and not by the system or indirect commands. For example, you can change characteristics by the set command, but not by the create or enable commands. However, some characteristics are read-only and never change. Each entity section gives complete information about the entity's characteristics, if any, and explains if and how they are modified.

Sequences, sets, and similar constructed data types must be explicitly stated in a set command.

There are certain restrictions on the use of set to modify characteristics:
  • Some characteristics can be modified only while the entity is disabled.

  • A few characteristics can be modified only while the entity is disabled, and can then have only their value increased, not decreased.

1.4.5. show

You use the show command to display the value of one or more attributes of an entity. The general form of a show command is:
ncl> show entity-name attribute-specifier,...
An attribute-specifier can be the name of a particular attribute; for example:
ncl> show node 0 ddcmp link link-5 protocol, transmit underruns, state
This command line displays the following attributes of the entity ddcmp link link-5:
  • The characteristic protocol

  • The counter transmit underruns

  • The status state

An attribute-specifier can also specify an entire class of attributes, as follows:
  • all [attributes]

  • all characteristics

  • all counters

  • all identifiers

  • all status

The following example displays all counters and status attributes of the entity ddcmp link link-5:
ncl> show node 0 ddcmp link link-5 all counters, all status
You can combine individual attribute names and attribute class names; for example:
ncl> show node 0 ddcmp link link-5 protocol, all counters

This example displays the value of the characteristic protocol and the value of all counters.

There are a few attributes whose value cannot be displayed. These are usually attributes that represent secure information, such as passwords.

1.5. NCL Command Syntax

An NCL command can contain the following elements, in the order shown:

verb [entity name] [,argument/attribute] [,prep-phrase]
The following example demonstrates this:
ncl> show node .mass.boston.welder routing circuit ethernet-1 -
_ncl> all status,by user=harry, password=truman
This command shows the current values for all status attributes for routing circuit Ethernet-1 on node .mass.boston.welder with access control information supplied. The components of this command are:
  • Verb (or directive): show

  • Entity name: node .mass.boston.welderrouting 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.

  • all status, an attribute specifier

  • by (preceded by a comma), a prepositional phrase

  • 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 counters, with -
_ncl> direction = outgoing
If the command is directed to the local system, it is not necessary to include the node entity's class/instance in the command. For example, the following command creates the specified entity on the local node:
ncl> create routing type csma-cd

1.5.1. Verbs

NCL commands form three broad categories:
  • 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.

  • 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.

  • 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 example:
    ncl> disable routing circuit circuit-1

    This command line sets that circuit's state to off, and causes an event to be logged to indicate this change.

1.5.2. Entity Name

Entities are specified by their full name in the entity hierarchy and consist of one or more class/instance pairs. For example, the routing circuit reachable address entity is one of the subentities that comprises the Routing module. The reachable address entity is subordinate to the routing circuit entity, which is subordinate to the top-level routing entity in the Routing module. An example of the entity's full name is:
node 0 routing circuit ether-1 reachable address foo

Node 0 is a class/instance pair for the global Node entity. Node 0 is a designation for the local system and is the default value for NCL commands. The "node node-name" element in an NCL command is thus not required when the operation to be performed is for an entity on the local system.

1.5.3. Attribute Specifiers

Certain NCL commands, such as show, can include one or more attribute specifiers. The following sections describe the five basic attribute specifiers.

1.5.3.1. Attribute Groups

You can specify one or several attribute groups, separated by commas, in a show command. If you specify all, this is equivalent to specifying all the attribute groups that are legal for a command.

NCL and the CMIP Management Listener (CML) do not support entity-specific attribute groups. The common attribute group names are:
  • all [attributes]

  • all characteristics

  • all counters

  • all identifiers (default)

  • all status

See the individual show command descriptions to see which attribute groups are legal for each command.

1.5.3.2. 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.

1.5.3.3. 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 maintained dynamically by the system and cannot be reset by the system manager.

1.5.3.4. 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 recreating it with a new name. See specific entity description sections for more information on entities that have multiple identifiers.

1.5.3.5. Status Attributes

Status attributes record current conditions of the entity, such as its state. Usually status attributes are set dynamically by the system to reflect current conditions set up by different operations. You can display current status values, but you cannot directly modify them. However, certain network management actions (such as enabling or disabling an entity) may alter the values of status attributes.

1.5.4. 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.

1.5.5. Prepositional Phrases

Most NCL commands accept two types of prepositional phrases:

  • Use "by phrase" to specify an access control string for remote system management.

  • Use "with qualifying-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. See individual command descriptions to determine which commands support the use of prepositional phrases.

1.5.5.1. Qualifying NCL Commands

Use the with prepositional phrase to qualify an NCL command to limit the scope of its operation. Also called filtering, this process is useful in displaying or acting upon only certain information. The expression supplied as part of the with clause must be an attribute of the entity (or entities) specified in the command.
ncl> show node 0 session control application *, with maximum instances>0

For every session control application entity on node 0 (the local system), NCL finds the entities with maximum instances greater than zero, and returns the identifying information about those session control application entities.

The with prepositional phrase is a Boolean expression that can use the relational operators shown in Table 1.1, “Relational Operators for a with Clause ”.
Table 1.1. Relational Operators for a with Clause

Symbol

Meaning

=

Equals

<>

Not equals

<

Less than

<=

Less than or equal to

>

Greater than

>=

Greater than or equal to

1.5.5.2. Restrictions of With Clause

It is possible (but improbable) for the value of an attribute to change between the time the attribute value is tested against the with clause value and the time the directive is actually issued to the entity. This limitation can lead to cases such as the following:
ncl> show 0 session control port *, with send queue > 0

Node 0 Session Control Port %XCC354000
AT 1991-11-13-16:32:03.249-05:00I0.269

Status

     Send Queue = 0

In this case, the attribute briefly goes non-zero, then immediately returns to zero again. Unfortunately, the attribute changed value between the time it was sampled by the entity filtering software in the CML and the time that the Show directive was issued to that entity instance. This is generally not a problem. Most attributes are stable so this rarely happens.

1.5.6. Using Abbreviations

All NCL commands are made up of the same components: keywords, values, and punctuation. Keywords and punctuation are the parts of the NCL syntax that remain the same for every network; values are the parts that change depending on the particular configuration of a network. Values include entity instance identifiers and attribute/argument values. In general, you cannot abbreviate values, but you can abbreviate keywords as long as the abbreviation is unique. A misspelling may cause NCL to treat an entity name as if it were an attribute name. However, if spelled correctly, it recognizes multiword keywords.

For example, the following command lines are equivalent:

ncl> show node finance routing circuit *
ncl> sho no finance ro ci *
The node identifier, in this case, finance, cannot be abbreviated. In fact, identifiers anywhere in a command cannot be abbreviated. For example, the following two commands are not equivalent:
ncl> show node finance name
ncl> show node f name

The latter command tries to communicate with node f, not node finance.

The following example shows an ambiguous command line:
ncl> s n finance r c * probe rate

The command is ambiguous because the abbreviation s could stand for either the set or show command.

However, if the value itself consists of keywords, then it can be abbreviated. For example, the data type EntityClass, by definition, contains keywords representing the various entity class names. These keywords can be abbreviated in the same way as normal keywords, as long as the abbreviations are unique (unambiguous). See Appendix B for more information on data types and keywords.

As another example, note that the following two commands are equivalent. Both pass all events received by the event dispatcher from the routing entity.
ncl> pass ev d out s local_stream gl f ((r), all)
ncl> pass event dispatcher outbound stream local_stream global filter -
_ncl> (( routing ), all)

1.5.7. Specifying Full Names in an NCL Request

You can substitute an unqualified name for a full name in an NCL command only when the remote node specified in the command and the local node use the same primary naming service and their full names are identical except for the unqualified names themselves.

Consider the following cases:
                      LOCAL NODE           REMOTE NODE

Full name:            ns:.lkg.localnode    ns:.lkg.remotenode
Unqualified name:     localnode            remotenode
Synonym:              locnod               remnod

Full name:            local:.localnode     local:.remotenode
Unqualified name:     localnode            remotenode
Synonym:              locnod               remnod
In these cases, you can substitute the unqualified name for the full name in the NCL command:
ncl> set event dispatcher outbound stream ost_1 sink node remote node
This next example, however, is different:
                      LOCAL NODE             REMOTE NODE

Full name:            ns:.uct.localnode      ns:.lkg.remotenode
Unqualified name:     localnode              remotenode
Synonym:              locnod                 remnod

Full name:            ns:.localnode          local:.remotenode
Unqualified name:     localnode              remotenode
Synonym:              locnod                 remnod

Full name:            local:.uct.localnode   local:.remotenode
Unqualified name:     localnode              remotenode
Synonym:              locnod                 remnod
In this example, you must specify the full name for the remote node in the NCL command:
ncl> set event dispatcher outbound stream ost_1 -
_ncl> sink node ns:.lkg.remotenode
On a Tru64 UNIX system, you must specify the following:
ncl> set session control proxy dth source end user = -
_ncl> { [ node=local:.remotenode , end user=uic=[0,0]dan ] }

You cannot substitute the node synonym for a full name in the NCL command. However, in most cases, because the unqualified name and the node synonym are usually identical, it may appear that the synonym substitution was successful.

1.5.8. Specifying Hex Strings

You must use the %X format to specify hex strings in NCL foreign commands. You can issue commands using the ’’H format for hex strings only at the ncl> prompt.

1.5.9. Using Wildcard Characters in a Command

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.

The rules for using wildcard characters are as follows:
  • 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.

  • 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 entitynode 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.

  • Do not use wildcard characters with NCL control commands.

  • If you use wildcard characters with an entity instance name, a display of all the instances of a class appears.

  • NCL supports the use of wildcards for any directive except create.

  • 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.

1.5.10. Recalling a Command

To recall previously entered NCL commands, press the up-arrow key. After recalling an NCL command, modify it by using Ctrl/A to switch between insert and overstrike modes of editing. You can also use the Delete key to edit a command line. Re-enter the command by pressing the Return key. Press the down-arrow key to recall the next (most recent) command in the NCL command recall buffer.

1.5.11. NCL Command Output

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

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:
  1. OpenVMS NCL error messages; that is, errors that occur at the level where OpenVMS is processing NCL commands.

  2. Common NCL exception messages; that is, errors that occur within NCL and which apply to more than one command.

  3. 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.

1.5.12. Displaying Unique Identification (UID) Values

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 characteristic sand 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.

1.5.13. Specifying Access Control Information

When using NCL commands to manage entities on remote systems in the network, use the appropriate method of supplying access control information as follows:
  • 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" (that is, 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, j_smith 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, password=DoNotUse
       .
       .
       .
  • Specify an access control string.

    The access control string (ACS) consists of a user name and password for an account on the remote system.

    Enter the user name and password immediately following the node name, surrounded by quotes:

    ncl> show node .admin.artists"j_smith DoNotUse" session control application -
    _ncl> graphics_exchange all counters

    On remote OpenVMS systems, to do a show operation you need the NET$EXAMINE right when specifying access control information. For write access (for example, set, disable, enable etc.), you need NET$MANAGE right or BYPASS privilege on the remote system.

    On remote Tru64 UNIX systems, you do not need privileges to do a show operation when specifying access control information. However, for write access, you must have superuser access to the system.

The use of proxy accounts is a more manageable method of establishing access control schemes between two systems. The VSI DECnet-Plus for OpenVMS Network Management Guide contains more information about controlling remote network access through the use of proxy accounts.

1.5.14. Establishing Default Context

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. Refer to Section 1.1 for further information on the rights identifiers required to access a remote or local node. (You need at least the NET$EXAMINE right to issue the set default commands discussed in this section.) Use the set ncl default entity command to set up a default entity. 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 access control string specified with an entity.

1.5.14.1. Default Context Usage Notes

When supplying access information, VSI recommends that you provide both the username and password in a single command. In addition, the command should include a default node entity. Here are two recommended 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

Once established, default entity and access control information remains in effect for the duration of the NCL session or until it is modified by subsequent set ncl default commands.

When a set ncl default command contains new access information but lacks a default node entity, the new access information is stored, but is not used until some subsequent set ncl default entity node command is issued. For example, the following two commands set new access information but do not specify a default node entity:

ncl> set ncl default access by user=username, password=password

ncl> set ncl default entity [subentity | subentities], -
_ncl> access by user=username, password=password

The following example shows the result of using a command of this type.

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 ()

Note that the access control information created in the preceding commands 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 commands apply to that node until the user modifies the default node entity. For example, with the default node entity set to remnod, you can set the default entity to session control on node remnod without respecifying the node entity:

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 respecify) 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 subentity session control if you want to set default to a lower subentity on that node. For example, NCL does not parse the following command because the entity session control is not respecified:

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

Since NCL could not parse the command, the NCL defaults remained unchanged. Instead, the following 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 preceding example the instance identifier fal specified a particular instance of a session control application entity. 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 *

Note that if the default access control information and the default entity are now modified, but no node entity is specified, the old default access control remains in effect.

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 *

In the preceding example, the new default access information is 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 node entity fails, the default node entity is reset to the local node. Default subentity information is cleared as well because subentities are node-specific. The default access information is left as is, but it remains 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 ()

1.6. Using Snapshot

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
  .                           .                   .                  .
  .                           .                   .                  .
  .                           .                   .                  . 

Note

Snapshot information is only retained for the duration of an NCL session. Therefore, you must enter the snapshot command and subsequent show commands 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 node name in each NCL command, as long as the commands are issued within the same NCL session.

1.7. Setting Up Optional Initialization or Key Definition Files

You can customize your NCL environment by using either the optional initialization file or optional key definition file.
  • The initialization file contains NCL commands that are executed when you start NCL; that is, before you receive the NCL prompt ncl>. 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 is executed before the ROUTING.NCL script:
    $ ncl @routing.ncl
  • 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 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.

1.7.1. KEYPAD Definition for NCL

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.

1.8. Accessing Name Service Information

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 VSI DECnet-Plus for OpenVMS Network Management Guide manual for more information and instructions on registering, deregistering, modifying, and renaming node names. See the VSI DECnet-Plus for OpenVMS DECdns Management Guide for information about dnscp and for detailed instructions on managing the namespace and its contents.

1.9. Using NCP for Remote Network Management

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 VSI DECnet-Plus for OpenVMS Network Management Guide.

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 VSI 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

1.10. Console Carrier

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 VSI DECnet-Plus for OpenVMS Network Management Guide.

Chapter 2. Node Module

The Node module has one entity, the global node entity, which crowns the hierarchy represented in the entity model described by the Network Architecture (NA). 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.

Figure 2.1, “The Node Global Entity in the NA Entity Hierarchy” 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 NA Entity Hierarchy
The Node Global Entity in the NA Entity Hierarchy

2.1. node

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.

Syntax

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]

2.1.1. Entity Name

Commands that manage a node entity specify the node using this format:

node node-id

Node being managed by the command.

If you want to operate on the local node, you can either omit the node identifier in your NCL command, or you can specify node 0, which identifies the local node.

2.1.2. Commands

enable

Turns on the node entity with or without the address watcher.

rename

Changes the node's name within the node and does not affect the name server directly. It uses the new name and an immediate keep me here transaction with the name servers which then update themselves based on the node's new name.

2.1.3. Arguments

function function

Specifies a function to disable or enable on the node. For the enable command, the function argument is optional. Specifying one, both, or neither has the effect of changing the state to on.

address watcher

Enables the address watcher function. Enabling this function allows the node to update its address identifier when a change of address is detected.

Disabling this function causes the state attribute to be set to off, but the node can still respond to management through its CMIP interface. The disable function is only supported on OpenVMS.

CMIP listener

Enabled automatically by the software. This function permits the node to respond to management through its CMIP listener interface. The CMIP listener function is only supported on Tru64 UNIX.

new name full-name

Specifies the new name to be assigned to the node.

2.1.4. Characteristic Attributes

implementation

Particular DECnet implementation of the node. You cannot modify this characteristic.

listener template (Tru64 UNIX)

Name of the OSI Transport template to be passed through the CMIP listener to Session Control. You cannot modify this characteristic.

maximum listeners (Tru64 UNIX)

Maximum number of CMIP listeners that the node supports. Zero specifies an unlimited number of listeners. You cannot modify this characteristic.

version

Version number of the network management architecture specification to which the implementation conforms. You cannot modify this characteristic.

2.1.5. Counter Attributes

changes of address

Number of times the node's address has changed.

changes of id

Number of times the node's ID has changed.

creation time

Time at which the entity was created. This time reflects the time at which the node was first booted.

idrom check failures

Number of times an IDROM was checked for consistency and was found to be in error.

renames

Number of times the node has been renamed (see the rename command).

2.1.6. Identifier Attributes

address

Set of protocol towers that together form a Session Control application address for the node's CMIP listener.

name

Full name of the node as it is registered in your namespace; name is the primary identifier.

2.1.7. Status Attributes

functions enabled

Functions that are currently enabled for the node (see the enable command).

id

Indicates the unique 48-bit ID of the node.

state

State of the node.

booting

The node is attempting to downline load. You cannot manage the node in this state. If the boot process is successful, the node enters the off state. This function is only supported on OpenVMS.

dead

The node is unusable and unmanageable as the result of a power failure or similar event. The node must be rebooted. This function is only supported on OpenVMS.

off

The node is manageable, but not all of its functions are enabled.

on

All of the node's functions are enabled and the node is fully manageable. The on state is the normal operating state.

uid

Node's unique identifier, which is generated when the node is created.

2.1.8. Event Messages (Tru64 UNIX)

address changed

Generated each time the node address changes.

Arguments:

old address

Protocol tower set that constituted the old node address.

new address

Protocol tower set that constitutes the new node address.

id changed

Generated each time the node's ID status attribute changes value.

Arguments:

old id

Node's old 48-bit ID.

new id

Node's new 48-bit ID.

idrom check failure

Generated each time an IDROM was checked and failed the test.

Arguments:

contents

Value of the failed IDROM.

owner

Name of the device on which the failed IDROM address exists.

renamed

Generated each time the node's name changes.

Arguments:

old name

Old full name of the node.

new name

New full name of the node.

2.1.9. Exception Messages (Tru64 UNIX)

For rename:

update of backtranslation soft links failed

Update of backtranslation soft links failed on the rename directive.

update of new name failed

New name update has failed on the rename directive.

unregistered name

The attempt to rename the node failed because the name and/or UID were not registered in DNS.

Chapter 3. Alias Module (OpenVMS)

This chapter describes all the commands you can use to manage the entities that constitute the Alias module. The Alias module provides the means to define an alternate network address that is shared by multiple nodes in the same OpenVMS cluster. This makes it possible to treat an OpenVMS cluster, or several nodes within an OpenVMS cluster, as though it were a single node in the network.

Figure 3.1, “Hierarchy of Alias Module Entities” shows the hierarchical relationship of the entities that constitute the Alias module.

Figure 3.1. Hierarchy of Alias Module Entities
Hierarchy of Alias Module Entities

3.1. alias

The alias entity is the top-level entity in the hierarchy belonging to the Alias module. The entity is the root from which alias port subentities may be defined.

Syntax

create [node node-id] alias

delete [node node-id] alias

show [node node-id] alias [all [attributes] | all counters]

3.1.1. Counter Attributes

creation time

Specifies the time at which the entity was created.

3.1.2. Exception Messages

For create:

already exists

An alias entity already exists.

wrong node type

An alias entity cannot be created on an alias node.

For delete:

module enabled

Disable the alias entity before trying to delete it.

3.2. alias port

An alias port entity provides the means to define an alternate network address for this node, which is shared by other nodes in the same OpenVMS cluster. When the alias port entity is enabled, this node becomes an active member of the OpenVMS cluster alias it specifies.

The first node in the OpenVMS cluster to create an alias port for a particular alias address causes that alias to be created. Subsequent nodes that create an alias port for the same alias establish connections (ports) to that alias. The alias becomes active when the first node enables its alias port for that alias. The port-name refers to the port managed by this command.

Note

When a node enables an alias port, that node registers itself with other members of the alias.

Syntax

create [node node-id] alias port port-name [node id ID802]

delete [node node-id] alias port port-name

disable [node node-id] alias port port-name

enable [node node-id] alias port port-name

set [node node-id] alias port port-name { outgoing default boolean | selection weight integer }

show [node node-id] alias port port-name [all [attributes] | all characteristics | all counters | all identifiers | all status]

shut [node node-id] alias port port-name

3.2.1. Commands

shut

Places the specified alias port entity in the shut state. Note that other nodes participating in the alias will continue to accept connections for the alias after this command is executed.

3.2.2. Arguments

node id

The LAN address to assign to the alias. Use the node id argument for the first cluster member to create the alias. Omit the argument for subsequent cluster members.

3.2.3. Characteristic Attributes

outgoing default

Specifies whether this alias should be used as the default alias for this node. If set to true, this alias name is used for connect requests on all outgoing connections from session control applications with their outgoing alias attribute set to true. Only one alias port can have this characteristic set to true.

selection weight

Default: NoneValue: 1-255

The number of sequential incoming connects to be passed to this member node in the round-robin sequence before proceeding to the next member node in the sequence. A value of zero means this node is not eligible to receive incoming connections to this alias address. Selection weight is used to apportion incoming alias connections according to the capacity of each alias member. Nodes with greater capacity should have larger values of selection weight, while local area OpenVMS cluster satellites should generally have a value of zero. Setting the selection weight to a very low non-zero number, such as 1, encourages needless connection delay because each incoming connection is treated in a round-robin fashion. That is, as each new connection comes in, it must be passed to the next cluster member. We recommend values between 5 and 10.

Note

The nsp maximum transport connection value determines the number of connections on an alias member. If the alias port is enabled, changing the nsp maximum transport connection value has no effect.

3.2.4. Counter Attributes

creation time

Specifies the time at which the entity was created.

3.2.5. Identifier Attributes

name

This string is the port identifier and is also the DECdns-registered node object name of the Alias psuedo-node.

3.2.6. Status Attributes

node-id

The 6-byte node-id field in the Alias pseudo-node's NSAP.

state

Specifies the status of the alias port entity.

off

The alias port entity is enabled

on

The alias port entity is enabled

shut

The alias port entity is enabled and supports existing connections using this alias. However, no further alias connection requests are honored. When all existing alias connections are closed, the alias port entity transitions to the off state.

3.2.7. Exception Messages

For create:

already exists

An alias port entity already exists.

too many alias port entities

The maximum number of alias port entities has been exceeded.

For delete:

cannot delete the entity while it is enabled

Disable the alias port entity before trying to delete it.

Chapter 4. CSMA-CD Module

This chapter describes all the commands you can use to manage the entities that constitute the CSMA-CD module. A Carrier Sense Multiple Access with Collision Detection (CSMA-CD) local area network (LAN) provides high-speed communications channels for connecting computers and other digital devices located within a moderate-sized geographic area. Like other LANs, the CSMA-CD LAN falls between long-distance, low-speed networks that carry data for hundreds or thousands of kilometers, and specialized, high-speed intercommunications that are generally limited to tens of meters. The CSMA-CD LAN is intended for use primarily in such areas as office automation, distributed data processing, terminal access, distributed systems, and other situations that require economical connection to a local communication medium with sporadic traffic at high-peak data rates.

Figure 4.1, “Hierarchy of CSMA-CD Module Entities” shows the hierarchical relationship of the entities that constitute the CSMA-CD module.

Figure 4.1. Hierarchy of CSMA-CD Module Entities
Hierarchy of CSMA-CD Module Entities

The Network Architecture CSMA-CD module incorporates the functions and operations defined in the Ethernet Specification Version 2.0 and the ISO 8802-3 (IEEE 802.3) CSMA-CD Access Method and Physical Layer specification as well as parts of the ISO8802-1 (IEEE 802.1) Addressing, Internet working, and Network Management and the ISO 8802-2 (IEEE 802.2) Logical Link Control specifications. To this, the Network Architecture CSMA-CD module adds features often needed by users of the datalink. A typical such data link user is the Network layer of the Network Architecture.

4.1. csma-cd

The csma-cd entity is the top-level entity in the hierarchy of entities belonging to the CSMA-CD module.

Syntax

create [node node-id] csma-cd

delete [node node-id] csma-cd

show [node node-id] csma-cd [all [attributes] | all characteristics]

4.1.1. Characteristic Attributes

version

Default: Current version number

Version number of the CSMA-CD data link architecture specification to which the implementation conforms. You cannot modify this characteristic.

4.1.2. Exception Messages

For create:

already exists

A csma-cd entity already exists.

For delete:

has children (Tru64 UNIX)

Cannot delete while subentities exist.

cannot delete while subentities exist (OpenVMS)

Cannot delete while subentities exist.

4.2. csma-cd port

A csma-cd port entity represents an access point to the service offered by the CSMA-CD module. A client transmits and receives data through a port. Ports are created and deleted by client use of open and close service interface procedures. The port-name refers to the port managed by this command.

Syntax

show [node node-id] csma-cd port port-name [all [attributes] | all counters | all identifiers | all status]

4.2.1. Counter Attributes

Unless stated otherwise, counts include both normal and multicast traffic and all protocol types, service access points (SAPs), and protocol identifiers.

creation time

Time at which the port was created.

multicast octets received

Number of multicast data octets that were received successfully and made available to the port user. The count is the number of octets in the CSMA-CD user data field and does not include MAC (media access control, a sublayer of the CSMA-CD Data Link layer) headers. Comparing this count to the octets received count yields the gross percentage of bandwidth that was consumed (over time) by multicast PDUs received by the port.

multicast octets sent

Number of multicast data octets that were sent successfully through the port. The count is the number of octets in the MAC user data field, including any padding or length fields; it does not include MAC headers. Comparing this count to the octets sent count yields the gross percentage of bandwidth that was consumed (over time) by multicast PDUs transmitted by the port.

multicast pdus received

Number of multicast PDUs that were received successfully and made available to the port user. Counted PDUs passed address and protocol filtering and were received without errors. Comparing this count to the pdus received count yields a gross percentage of CSMA-CD usage for multicast pdus received by this port.

multicast pdus sent

Number of multicast PDUs that were sent successfully through the port. Comparing this count to the pdus sent count yields a gross percentage of CSMA-CD usage for multicast pdus sent by this port.

octets received

Total number of MAC user data octets that were received successfully and made available to the port user. Counted frames passed address and protocol filtering for both individual and multicast MAC addresses and were received without errors. The count is the number of octets in the CSMA-CD user data field plus any padding, Ethernet length fields, or logical link control (LLC) header fields; it does not include MAC headers. Adding the octets received count to the protocol overhead calculated from the pdus received count yields the amount of CSMA-CD bandwidth consumed by frames received by the port.

octets sent

Total number of user data octets that were sent successfully through the port. The count is the number of octets in the MAC user data field including any padding or length fields; it does not include MAC headers. Adding the octets sent count to the protocol overhead calculated from the pdus sent count yields the amount of CSMA-CD bandwidth consumed (over time) by frames sent by the port.

pdus received

Total number of PDUs that were received successfully and made available to the port user. Counted PDUs passed address and protocol filtering and were received without errors. The count provides a gross measurement of incoming CSMA-CD usage by the port.

pdus sent

Total number of PDUs that were sent successfully through the port. The count provides a gross measurement of outgoing CSMA-CD usage by the port.

unavailable user buffers

Number of times that no user buffer was available at the port for an incoming frame that passed all filtering for the port. Used in conjunction with the pdus received count, this counter can indicate the rate of user buffer receive problems.

4.2.2. Identifier Attributes

name

Simple name assigned to the port when it is created.

4.2.3. Status Attributes

client

Name specified by the data link user when the port was opened.

ethernet protocol types

Set of Ethernet protocol types that are currently recognized for this port.

length present

The data link adds a length field on transmit frames. It assumes the presence of a length field and attempts to remove it on received Ethernet frames. When false, the data link does not add and remove length fields. This attribute is irrelevant for ISO 8802-3 formatted frames, which always have a length field.

false

The data link does not add and remove length fields.

true

The data link adds and removes length fields.

llc sap addresses

Set of individual and group logical link control (LLC) service access point (SAP) addresses that are currently recognized for this port.

llc service

Type of LLC (logical link control) PDU processing that is required on the port (as defined by the user when the port was opened).

class 1

The data link provides class 1, type 1 service.

user-supplied

The user is responsible for handling the LLC protocol.

mac addresses

Set of individual and multicast MAC (medium access control) addresses that are currently recognized for this port.

receive mode

Type of receive mode that is currently enabled for the port.

normal

The port receives only those frames that meet the normal address and protocol filtering requirements requested by the user.

promiscuous

The port receives all frames regardless of format and MAC address.

snap protocol identifiers

Set of subnetwork access protocol (SNAP) identifiers that are currently recognized for this port.

station

Name of the station associated with this port as specified by the user when the port was opened.

uid

Entity's unique identifier, which is generated when the port is created.

4.3. csma-cd station

A csma-cd station entity manages a CSMA-CD controller. Wherever Phase IV DECnet manages a line, DECnet-Plus manages a station. Each station corresponds to a particular logical link control (LLC), medium access control (MAC), and physical attachment. The station-name refers to the station managed by this command.

Syntax

create [node node-id] csma-cd station station-name communication port port-id

delete [node node-id] csma-cd station station-name

disable [node node-id] csma-cd station station-name

enable [node node-id] csma-cd station station-name mac address ID802

set [node node-id] csma-cd station station-name station buffers integer (OpenVMS)

show [node node-id] csma-cd station station-name [all [attributes] | all characteristics | all counters | all identifiers | all status]

4.3.1. Arguments

communication port

The system device name assigned to this station.

On OpenVMS systems, the name must be in the format ddc, where dd is the OpenVMS device name prefix and c is the controller letter. For a complete list of CSMA-CD devices and their OpenVMS device names, see the DECnet-Plus for OpenVMS Release Notes.

On Tru64 UNIX systems, the name must be in the format ddn, where dd is the Tru64 UNIX device name prefix and n is the device number.

This argument determines the value of the communication port characteristic and is required.

mac address

Individual medium access control (MAC) address for the station. If you do not specify a MAC address, the network uses the address specified in the first EnableMacAddress user interface call directed to this station.

4.3.2. Characteristic Attributes

station buffers

Default: 4

Value: 1–64

Number of receive buffers reserved for the station. You cannot modify this characteristic.

4.3.3. Counter Attributes

Unless stated otherwise, counts include both normal and multicast traffic and all protocol types, service access points (SAPs), and protocol identifiers.

alignment errors

Number of times a received frame did not contain an integral number of octets.

carrier check failures

Number of times the data link did not sense the receive carrier signal or detected an error in the receive carrier signal during transmission of a frame.

collision detect check failures

Number of times the collision detect test signal was not sensed after a transmission. If this count approximates the number of frames sent, either the collision detect circuitry is not working correctly or the test signal is not implemented.

creation time

Time at which the station was created.

data overruns

Number of times the hardware lost one or more consecutive, partially complete, incoming frames because it could not keep up with the incoming frame rate. Used in conjunction with pdus received, this count provides a measure of hardware resource and bandwidth failures.

excessive collisions

Number of times a transmission failed because the maximum allowable number of retransmission attempts all culminated in collisions.

frame check errors

Number of times a received frame containing an integral number of octets failed the frame check sequence (FCS).

frame size errors

Number of times the user requested transmission of a frame outside the range of valid frame sizes.

frames too long

Number of times a received frame exceeded the maximum length allowed by CSMA-CD medium access control.

initially deferred pdus sent

Number of times a PDU was deferred by the station access algorithm on the first attempt at transmission, but was then transmitted successfully without collision. Used in conjunction with pdus sent, this count measures the rate of CSMA-CD contention with no collisions.

late collisions

Number of times a collision was detected after the allotted time for collisions had expired.

multicast octets received

Number of multicast data octets that were received successfully. The count is the number of octets in the CSMA-CD user data field and does not include MAC headers. Comparing this count to the octets received count yields the gross percentage of bandwidth that was consumed (over time) by multicast frames received by the local system.

multicast octets sent

Number of multicast data octets that were sent successfully. The count is the number of octets in the MAC user data field, including any padding or length fields; it does not include MAC headers. Comparing this count to the octets sent count yields the gross percentage of bandwidth that was consumed (over time) by multicast frames transmitted by the local system.

multicast pdus received

Number of multicast PDUs that were received successfully. Comparing this count to the pdus received count yields a gross percentage of CSMA-CD usage for multicast PDUs received by this system.

multicast pdus sent

Number of multicast PDUs that were sent successfully. Comparing this count to the pdus sent count yields a gross percentage of CSMA-CD usage for multicast PDUs sent by this system.

multiple collisions pdus sent

Number of times a PDU was transmitted successfully on the third or later attempt by the station access algorithm after normal collisions on previous attempts. Used in conjunction with pdus sent, this count provides a measure of CSMA-CD media contention at a level where there are collisions and the backoff algorithm no longer works efficiently.

octets received

Total number of MAC user data octets that were received successfully from frames that passed address and protocol filtering for both individual and multicast MAC addresses. The count is the number of octets in the CSMA-CD user data field plus any padding, Ethernet length fields, or LLC header fields; it does not include MAC headers. Adding the octets received count to the protocol overhead calculated from the pdus received count yields the amount of CSMA-CD bandwidth consumed by frames received by the local system.

octets sent

Total number of user data octets that were sent successfully. The count is the number of octets in the MAC user data field including any padding or length fields; it does not include MAC headers. Adding the octets sent count to the protocol overhead calculated from the pdus sent count yields the amount of CSMA-CD bandwidth consumed (over time) by frames sent by the local system.

pdus received

Total number of PDUs that passed address and protocol filtering and were received without errors. The count provides a gross measurement of incoming CSMA-CD usage by the local system; this information can be used with other counters to approximate the average receive frame size or to determine the ratio of errors to successful receives.

pdus sent

Total number of PDUs successfully sent. The count provides a gross measurement of outgoing CSMA-CD usage by the local system; this information can be used with other counters to approximate the average transmit frame size or to determine the ratio of errors to successful transmissions.

receive data length errors

Number of times a frame was received with a length field value that was invalid for the number of octets actually received by medium access control.

send data length errors

Number of times the user requested transmission of an 802.3 frame with a length field value that was not valid for the number of octets actually passed.

single collision pdus sent

Number of times a PDU was successfully transmitted on the second attempt by the station access algorithm after a normal collision occurred on the first attempt. Used in conjunction with pdus sent, this count provides a measure of CSMA-CD media contention at a level where there are collisions, but the backoff algorithm still works efficiently.

station failures

Number of times the station self-testing procedures reported failure.

unavailable station buffers

Number of times a complete, fully received PDU was discarded because no station buffer was available. Used with pdus received, this count provides a measure of receive problems related to the station buffer.

unavailable user buffers

Number of times no user buffer was available for an incoming frame that passed all filtering for the port. Used with the pdus received count, this counter can indicate the rate of user buffer receive problems.

unrecognized individual destination pdus

Number of times a received PDU with an individual destination MAC address was discarded because there was no port with the correct Ethernet protocol type, SNAP protocol identifier, or link logical control SAP address enabled.

unrecognized multicast destination pdus

Number of times a received PDU with a multicast destination MAC address was discarded because there was no port with the correct Ethernet protocol type, SNAP protocol identifier, or link logical control SAP address enabled.

4.3.4. Identifier Attributes

name

Simple name assigned to the station when it is created.

4.3.5. Status Attributes

address filters

All individual MAC addresses currently enabled by any of the ports on the station.

communication port

DECnet-Plus device name for the station.

hardware address

Individual medium access control (MAC) address that was assigned during manufacture of the communications hardware that is associated with the station.

mac address

Current MAC address (if any) of the station. For more information about the MAC address, refer to the enable command.

receive mode

Current receive mode for the station. Some stations may not support all modes.

normal

The station receives only those frames (individual and multicast) that meet the normal format, protocol, and access control requirements.

all multicast

The station receives all individual-addressed frames that meet the normal format, protocol, and address requirements, and all multicast-addressed frames regardless of their format, protocol, and address types. This function is only supported on OpenVMS.

promiscuous

The station receives all frames (individual and multicast) regardless of format, Ethernet protocol type, SNAP identifier, LLC SAP address, or MAC address. This function is only supported on OpenVMS.

state

Operational state of the station.

failed

Either an attempt to enable the station failed during the self-test or the station was on and the data link determined that the station would now fail the self-test.

initializing

The station is currently being initialized and tested by the data link.

off

The station is disabled.

on

The station is enabled and available for use.

For more information on station states, refer to the appropriate network management guide.

uid

Entity's unique identifier, which is generated when the station is created.

4.3.6. Event Messages

alignment error

This event is generated whenever an incoming frame does not contain an integral number of octets. This error can be caused by several conditions, such as electromagnetic interference, late collisions, or improperly set hardware parameters (for example, receiver squelch).

carrier check failure

This event is generated on a transmission that failed, either because the data link did not sense the receive carrier signal that must accompany transmission of a frame, or because the data link did not detect an error. This error indicates a failure in either the transmitting or receiving hardware, such as the transceiver or transceiver cable.

data overrun

This event is generated whenever an incoming frame is lost because of a hardware resource failure such as insufficient hardware buffers or insufficient CPU time.

excessive collision

This event is generated whenever a transmission fails because the medium access algorithm reached the maximum number of allowable retransmission attempts resulting from collisions. This error can occur when too many systems are trying to transmit at the same time or when there are cable problems.

frame check error

This event is generated whenever an incoming frame fails the frame check sequence (FCS) test. This error can be caused by several conditions, such as electromagnetic interference, late collisions, or improperly set hardware parameters (for example, receiver squelch).

frame too long

This event is generated whenever a remote system sends a frame that exceeds the CSMA-CD MAC maximum length.

late collision

This event is generated whenever a transmission fails because a collision was detected after the allowed window for collisions had elapsed. This error indicates either a problem with another system's carrier sense or a weak local transmitter.

receive data length error

This event is generated whenever a remote system sends an 802.3 frame having a length field value that is not valid for the number of octets actually received by the MAC.

unavailable station buffer

This event is generated whenever an incoming frame is discarded because there is no station buffer available to receive it. This error indicates a lack of local station buffers; that is, a lack of buffers between the cable and the user buffers.

unavailable user buffer

This event is generated whenever an incoming frame is discarded because there is no user buffer queued to the appropriate port to receive it. This error indicates a lack of buffers in the user process; that is, the buffers supplied by the user for the Receive function.

unrecognized individual destination pdu

This event is generated whenever an incoming frame that matches an enabled individual MAC address is discarded because the frame does not satisfy the filter criteria of any port. This error indicates that a remote system is using a protocol that is locally unsupported or that the local system has not enabled a protocol type, protocol identifier, or LLC SAP address that it should have.

unrecognized multicast destination pdu

This event is generated whenever an incoming frame that matches an enabled multicast MAC address is discarded because the frame does not satisfy the filter criteria of any port. This error indicates that the local system has not enabled an Ethernet protocol type, SNAP identifier, or LLC SAP address that it should have, or that a remote system is sending traffic that is invalid for the combination of multicast and the currently specified protocol type, SNAP identifier, or LLC SAP.

4.3.7. Exception Messages

For create:

already exists

A csma-cd station entity already exists.

communication port in use

Failure to create the csma-cd station entity because the communications port is already reserved by another entity.

invalid communications port

Failure to create the csma-cd station entity because you cannot run CSMA-CD data link on this communications port.

For delete:

station in use (UNIX)

Attempt to delete the csma-cd station entity failed because there is at least one active port still associated with this station. You must wait until the ports go away to delete this station.

wrong state

Failure to delete the csma-cd station because the station must be disabled before deletion.

Chapter 5. DCMP Module (OpenVMS)

This chapter describes all the commands you can use to manage the entities that constitute the Data Communications Message Protocol (DCMP) module. The DCMP module is a data link control procedure that ensures a reliable data communication path between communication devices connected by data links. DCMP has been designed to operate over full- and half-duplex synchronous and asynchronous channels in both point-to-point and multipoint modes. It can be used in a variety of applications such as distributed computer networking, host/front-end processing, remote terminal concentration, and remote job entry-exit system operation.

Figure 5.1, “Hierarchy of DCMP Module Entities” shows the hierarchical relationship of the entities that constitute the DCMP module.

Figure 5.1. Hierarchy of DCMP Module Entities
Hierarchy of DCMP Module Entities

5.1. dcmp

The dcmp entity is the top-level entity in the hierarchy of entities belonging to the DCMP module.

Syntax

create [node node-id] dcmp

delete [node node-id] dcmp

show [node node-id] dcmp [all [attributes] | all characteristics]

5.1.1. Characteristic Attributes

dna version

Version number of the DCMP architecture specification to which the implementation conforms. You cannot modify this characteristic.

5.1.2. Exception Messages

For create:

already exists

A DCMP entity already exists.

5.3. dcmp link logical station

The dcmp link logical station entity manages a link to a remote station. The link-name is the DCMP link associated with the logical station and the station-name refers to the logical station managed by this command.

Syntax

create [node node-id] dcmp link link-name logical station station-name

delete [node node-id] dcmp link link-name logical station station-name

disable [node node-id] dcmp link link-name logical station station-name

enable [node node-id] dcmp link link-name logical station station-name

set [node node-id] dcmp link link-name logical station station-name {active base integer | active increment integer | address address | babble timer integer | buffer source source | dead threshold integer | dying base integer | dying increment integer | dying threshold integer | holdback timer integer | inactive base integer | inactive increment integer | inactive threshold integer | maximum buffers integer | maximum transmit integer | polling state effect | transmit timer integer | transmit window integer }

show [node node-id] dcmp link link-name logical station station-name [all [attributes] | all characteristics | all counters | all identifiers | all status ]

5.3.1. Characteristic Attributes

active base

Default: 255

Value: 0–255

Base priority to which an active tributary is reset after it has been polled.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

active increment

Default: 0

Value: 0–255

Value to be added to the active tributary priority each time the scheduling timer expires.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

address

Default: 1

Value: 1–255

Data link address of the remote station or tributary. You can modify this characteristic only when the entity is disabled.

babble timer

Default: 6000

Value: 1–65535

Time, in milliseconds, for which a selected tributary or remote station is allowed to transmit. This characteristic is not used on full-duplex links.

This characteristic is not supported if the characteristic protocol of the owning dcmp link entity is set to tributary.

buffer source

Default: Implementation-specific

Value: See description

Source of the receive buffers.

client supplied

Buffers are provided by the client entity.

common pool

Buffers are assigned from the common buffer pool.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control. You can modify this characteristic only when the entity is disabled.

dead threshold

Default: 8

Value: 0–255

Number of times an active, inactive, or dying tributary is polled before its status attribute polling substate is changed to dead because of receive timeouts.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

dying base

Default: 0

Value: 0–255

Base priority to which a dying tributary is reset after being polled.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

dying increment

Default: 16

Value: 0–255

Value to be added to a dying tributary's priority each time the scheduling timer expires.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

dying threshold

Default: 2

Value: 0–255

Number of times an active or inactive tributary is polled before its status attribute polling substate is changed to dying because of receive timeouts.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

holdback timer

Default: 0

Value: 0–13000

Maximum time, in milliseconds, that the local station can delay acknowledging a received message if there is no data to send.

The value of this characteristic is linked to the retransmit timer used on the remote station. A suggested value is between 10% and 20% of that timer. However, the actual values you can use may be limited by the communications product.

The default value indicates that no holdback is used and the local station must acknowledge immediately.

inactive base

Default: 0

Value: 0–255

Specifies the priority to which an inactive tributary is reset after it has been polled.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

inactive increment

Default: 64

Value: 0–255

Value to be added to an inactive tributary's priority each time the scheduling timer expires.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

inactive threshold

Default: 8

Value: 0–255

Number of times an active tributary is polled before its status attribute polling substate is changed to inactive because of no data response.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

maximum buffers

Default: 4

Value: Implementation specific

Maximum number of buffers that a tributary can use from the common buffer pool. A value of 0 means that there is no limit to the number of buffers that can be used. This characteristic is supported only if the buffer source characteristic is set to common pool.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control. You can modify this characteristic only when the entity is disabled. Also, you can only increase the characteristic value.

maximum transmit

Default: 4

Value: 1–255

Maximum number of messages that a tributary or a remote half-duplex station can send at one time. The value of this characteristic must be greater than or equal to that of transmit window on the selected station.

This characteristic is not supported if either of the following conditions is true:
  • The characteristic protocol of the owning dcmp link entity is set to tributary.

  • The communications link is full-duplex and point-to-point.

You cannot modify this characteristic.

polling state

Default: Automatic

Value: See description

Specifies the effect of the local station's polling algorithm on the state of a tributary. The value of this characteristic is reflected in the value of the status attribute polling substate.

active

The state is locked to active.

automatic

The state varies according to the operation of the polling algorithm.

dead

The state is locked to dead.

dying

The state is locked to dying.

inactive

The state is locked to inactive.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

transmit timer

Default: 0

Value: 0–65535

Time, in milliseconds, that the local station waits between data transmissions.

This characteristic is supported only if the characteristic protocol of the owning dcmp link entity is set to control.

transmit window

Default: 1

Value: 1–255

Maximum number of data messages that the local station can send without receiving an acknowledgment. This characteristic applies only when the remote station is a control station or on a half-duplex, point-to-point link. The value of this characteristic must be less than or equal to the equivalent of the maximum transmit characteristic on the control station or remote station.

5.3.2. Counter Attributes

buffers temporarily unavailable

Number of times the local station could not service messages from the remote station because there were no receive buffers available.

buffers too small

Number of times the local station could not service messages from the remote station because the receive buffers were not large enough.

creation time

Time at which this entity was created.

incomplete replies to select

Number of selection intervals that were not properly terminated (that is, by a message with the Select bit set in the header), during which a transmission was received or an attempt at transmission was detected.

This counter is supported only if the protocol characteristic of the owning dcmp link entity is set to control, or when the link is a half-duplex, point-to-point link.

local reply timeouts

Number of times the local station failed to receive an acknowledgment before the reply timer expired.

locally initiated state changes

Number of times the station protocol state changed through action of the local station.

naks received indicating buffer too small

Number of times the remote station reported that it could not service a message because the receive buffer was not large enough.

naks received indicating buffers temporarily unavailable

Number of times the remote station reported that it could not service a message because no receive buffer was available.

naks received indicating data field block check error

Number of times the remote station reported that a block check error was detected in the data field of an incoming message.

naks received indicating header block check error

Number of times the remote station reported that a block check error was detected in the header block of an incoming message.

naks received indicating rep response

Number of times the remote station reported that it did not receive all the messages sent from the local station.

naks sent with rep response

Number of times the local station detected that not all of the messages sent from the remote station were received correctly.

no replies to select

Number of times the select timer expired for any of the following reasons:
  • No valid control message was received.

  • No valid header to a data message was received.

  • No valid header to a maintenance message from the selected station was received.

  • No transmission from the remote station was received.

This counter is supported only if the protocol characteristic of the owning dcmp link entity is set to control, or when the link is a half-duplex, point-to-point link.

pdus received with data field check block error

Number of messages received with a check error in the data field.

pdus received with header block check error

Number of messages received with a check error in the header block.

receive error thresholds reached

Number of times the receive error threshold has been reached.

remote reply timeouts

Number of times the local station received a REP message and sent an acknowledgment in return. This sequence indicates that all messages sent from the remote station have been correctly received.

remotely initiated state changes

Number of changes in the station protocol state caused by action of the remote station.

sdu octets received

Number of data octets received from the remote station.

sdu octets sent

Number of data octets sent to the remote station.

sdus received

Number of data messages received from the remote station (not including retransmissions).

sdus sent

Number of data messages sent to the remote station (not including retransmissions).

selection error thresholds reached

Number of times the selection error threshold has been reached.

This counter is not supported if the characteristic protocol of the owning dcmp link entity is set to tributary.

selection intervals

Number of times the local station selected the remote or a tributary station. The counter does not appear if the link uses the tributary protocol. In addition, the counter appears only when the local station is the control station for a number of tributaries, or is operating over a half-duplex, point-to-point link.

This counter is supported only if the protocol characteristic of the owning dcmp link entity is set to control, or when the link is a half-duplex, point-to-point link.

send error thresholds reached

Number of times the send error threshold has been reached.

strts received while in maintenance

Number of times the local station received a STRT protocol message while in the Maintenance state.

5.3.3. Identifier Attributes

name

Simple name assigned to the link logical station when it is created.

5.3.4. Status Attributes

polling substate

State of a tributary as determined by the polling algorithm. This attribute applies only when the value of the link's protocol characteristic is set to control. The value of this attribute is affected by the value of the characteristic polling state. If the characteristic polling state is set to automatic, the value of this status attribute reflects the current state of the polling algorithm. For all other values of the polling state characteristic, the values of both attributes are the same.

active

The tributary is active and responds with data when selected.

dead

The tributary did not respond when selected within the appropriate timeout period, when already in the Dying or Inactive state. The tributary is ignored until the station reinitializes.

dying

The tributary, currently in the Inactive or Active state, has not responded within the appropriate timeout period when selected.

inactive

The tributary has not sent any data when selected by the control station. However, the tributary has responded with an appropriate message when selected.

protocol state

State of the data link protocol with the remote station.

halted

The protocol is stopped and no messages are being exchanged with the remote station.

maintenance

The protocol is off line and dealing with maintenance messages only.

running

The protocol is on line and exchanging messages with the remote station.

starting

There is an attempt to initialize the protocol between the local and remote stations. This uses the STRT and STACK PDUs.

state

Operational state of the local logical station.

off

The station is disabled.

on

The station is enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

5.3.5. Event Messages

buffer too small

Generated each time a message is received whose data field is larger than the buffers available on the local station.

Arguments:

buffer size

Size of the receive buffer at the local station.

count

Size of the received data message as specified in the message header.

locally initiated state change

Generated each time the state of the local station changes as a result of action on the local node.

Arguments:

new state

New value of the logical station's protocol state attribute.

old state

Previous value of the logical station's protocol state attribute.

receive error threshold reached

Generated each time the number of consecutive receive-related errors reaches the receive error threshold limit of 7.

remotely initiated state change

Generated each time the state of the link changes as a result of action on the remote node.

Arguments:

new state

New value of the logical station's protocol state attribute.

old state

Previous value of the logical station's protocol state attribute.

selection error threshold reached

Generated each time the number of consecutive selection-related errors reaches the selection error threshold limit of 7. This event is supported only when the protocol characteristic of the owning dcmp link entity is set to control, or when the link is half-duplex, point-to-point.

send error threshold reached

Generated each time the number of consecutive transmit-related errors reaches the transmit error threshold limit of 7.

strt received while in maintenance

Generated each time a strt message is received while the value of the status attribute protocol state of the local station is set to maintenance.

5.3.6. Exception Messages

For create:

already exists

A dcmp link logical station entity already exists.

maximum stations exceeded

The station cannot be created because there are already the maximum stations defined for this link. This can occur when there is already one logical station defined for that link.

For delete:

wrong state

Failure to delete the DCMP link logical station because the logical station must be disabled before deletion.

5.4. dcmp port

A dcmp port entity represents an access point to the Data Link layer service offered by dcmp. Ports are created and deleted automatically when a client of dcmp uses the link. The port-name refers to the port managed by this command.

Syntax

show [node node-id] dcmp port port-name [all [attributes] | all identifiers | all status]

5.4.1. Identifier Attributes

name

Simple name assigned to the port when it is created.

5.4.2. Status Attributes

client

Name of the client entity.

link

Name of the DCMP link that the client is using.

logical station

Name of the DCMP link logical station supplied by the client when the port was opened.

state

State of the port.

call attached

The port is assigned to a client and the link is associated with the current call on the line. Applies only when the link operates over a switched line.

open

The port is assigned to a client.

open disabled

The port is assigned to a client, but the link or logical station entity used by the port is disabled.

type

Type of port.

normal

For normal data communications.

service

For service operations. This is the value that modules such as MOP would use.

Chapter 6. Device Module

This chapter describes all the commands you can use to manage the entities that constitute the Device module. The Device module provides management of physical devices attached to a network system that must load microcode from a host system before it is operational.

Figure 6.1, “Hierarchy of Device Module Entities” shows the hierarchical relationship of the entities that constitute the Device module.

Figure 6.1. Hierarchy of Device Module Entities
Hierarchy of Device Module Entities

6.1. device

The device entity is the top-level entity in the hierarchy of entities belonging to the Device module.

Syntax

create [node node-id] device

delete [node node-id] device

show [node node-id] device [all [attributes] | all characteristics | all status]

6.1.1. Characteristic Attributes

version

Version of the device architecture to which the implementation conforms. You cannot modify this characteristic.

6.1.2. Status Attributes

uid

Entity's unique identifier, which is generated when the entity is created.

6.1.3. Exception Messages

For create:

already exists

A device entity already exists.

For delete:

has children

Cannot delete while subentities exist.

6.2. device unit

The device unit entity controls the loading and dumping of microcode for a specific communications device. The simple-name refers to the device unit managed by this command.

Syntax

create [node node-id] device unit simple-name name device-name

delete [node node-id] device unit simple-name

dump [node node-id] device unit simple-name

enable [node node-id] device unit simple-name

load [node node-id] device unit simple-name

set [node node-id] device unit simple-name {auto load boolean | dump destination filespec | dump on error boolean | load source filespec }

show [node node-id] device unit simple-name [all [attributes] | all characteristics | all counters | all identifiers | all status ]

6.2.1. Commands

dump

Dumps the device corresponding to the unit subentity.

load

Loads the device corresponding to the unit subentity.

6.2.2. Arguments

name device-name

The physical device this device unit entity controls.

6.2.3. Characteristic Attributes

auto load

Default: True

Value: True or false

Specifies whether the device should try to load its microcode without management intervention. Autoloading would occur after initialization, a failure, or a dump.

device

Physical device to which this device unit entity is related. The value of this characteristic is a copy of the name argument specified when this entity is created.

dump destination

Default: None

Value: File destination

File specification to hold the contents of the device's microcode when a dump occurs.

dump on error

Default: False

Value: True or false

Whether a device should try to dump its microcode after a device failure. Set this characteristic only for those devices that support the dump operation.

load source

Default: None

Value: File specification

File specification that contains the device's microcode. This is used during a load operation.

6.2.4. Counters

creation time

Time at which this entity was created.

device failures

Number of times the unit has failed.

failed dumps

Number of times an attempt to dump the device's microcode has failed.

failed loads

Number of times an attempt to load the device's microcode has failed.

forced dumps

Number of times the dump command has been used to force the device to dump its microcode.

forced loads

Number of times the load command has been used to load the device's microcode.

successful dumps

Number of times the device has successfully dump edits microcode.

successful loads

Number of times the device has successfully loaded its microcode.

6.2.5. Identifier Attributes

name

Simple name assigned to the device unit when it is created.

6.2.6. Status Attributes

firmware identifier

Implementation-specific string that identifies the firmware loaded into a device.

operational communication port (OpenVMS)

Specifies which channels of a multiple-line device unit are determined to be working by the module self-test. Each name identifies a working device communication port. Channels that are not named are not operational.

state

Current state of the communications device.

disabled

The device unit entity has been created, but an enable directive has not yet been issued.

dump failed

An attempt to dump the device's microcode has failed. This value appears only if the characteristic auto load is false.

dumping

An attempt to dump the device's microcode is in progress.

load failed

An attempt to load the device's microcode has failed. This value appears only if auto load is false.

loading

An attempt to load the device's microcode is in progress.

running

The device's microcode has been loaded and the device is ready to send and receive data.

stopped

This state can occur in one of the following circumstances:
  • The device entity unit has been enabled and auto load is false.

  • The device has been reinitialized by the system.

  • The device failed, a dump operation has completed (the characteristic auto dump is true, but the characteristic auto load is false.)

uid

Entity's unique identifier, which is generated when the entity is created.

6.2.7. Event Messages

device failure

Generated each time a failure is detected on a device.

Arguments:

failure reason

Reason for the device failure. The values of this argument are implementation specific.

firmware identifier

Identifier of the device's microcode.

next state

Next state of the device. This depends on the values of the auto load and dump on error characteristics.

dumping

The entity will try to dump the device's microcode.

loading

The entity will try to load the device's microcode.

stopped

The entity will stop, awaiting a dump or load command.

failed dump

Generated each time there is a failure to dump the device's microcode.

Arguments:

dump destination

Destination that the dump operation used.

dump reason

Reason for the dump failure.

directive

In response to a dump command.

failure

In response to a device failure while in the running state.

failure reason

Reason why the dump failed. The values of this argument are device specific.

failed load

Generated each time there is a failure to load the device's microcode.

Arguments:

failure reason

Reason for the load failure. The values of this argument are device dependent.

load reason

Reason for the load operation.

directive

In response to a load command.

dump

After completion of a dump operation.

failure

After a device failure.

initial

Initial loading of the device at device unit enable when auto load is true.

load source

Source used to retrieve the microcode during the load operation.

successful load

Generated each time the device's microcode is loaded successfully.

Arguments:

firmware identifier

Firmware identifier of the loaded microcode.

load reason

Reason for the load operation.

directive

In response to a load command.

dump

After completion of a dump operation.

failure

After a device failure.

initial

Initial loading of the device at device unit enable when auto load is true.

load source

Source used to retrieve the microcode during the load operation.

6.2.8. Exception Messages (OpenVMS)

For dump:

dump failure

The dump operation failed.

illegal dump destination

The value of the dump destination characteristic is not a valid file specification. Check the value of the character, correct as necessary, and reissue the dump command.

For load:

illegal load source

The value of the load source characteristic is not a valid file specification. Check the value of the characteristic, correct as necessary, and reissue the load command.

load failure

The load operation failed.

Chapter 7. DECdns Modules

The VSI DECnet-Plus Distributed Name Service (DECdns) is a networkwide service that makes it possible to use network resources without having to know their physical location. DECdns has two NCL modules: DNS Server and DNS Clerk.

7.1. DNS Server Module

The DNS Server module maintains a distributed database for use by the client modules on other nodes of the network. The responsibilities of this entity include responding to lookup requests, managing the namespace, and updating object entries.

Figure 7.1, “Hierarchy of DNS Server Module Entities” shows the hierarchical relationship of entities that constitute the DNS Server module.

Figure 7.1. Hierarchy of DNS Server Module Entities
Hierarchy of DNS Server Module Entities

Note

You can manage the DECdns entities from either NCL or the DECdns Control Program (DNSCP). The commands are the same for both interfaces and are documented in the VSI DECnet-Plus for OpenVMS DECdns Management Guide.

7.2. DNS Clerk Module

The DNS Clerk is the module of the Network Architecture Naming Service that interfaces directly with client applications. A clerk module is required on every DECnet-Plus node whether or not that node also functions as a DECdns name server. The clerk is created during configuration of the network software.

Figure 7.2, “Hierarchy of DNS Clerk Module Entities” shows the hierarchical relationship of entities that constitute the DNS Clerk module.

Figure 7.2. Hierarchy of DNS Clerk Module Entities
Hierarchy of DNS Clerk Module Entities

Note

You can manage the DECdns entities from either NCL or the DECdns Control Program (DNSCP). The commands are the same for both interfaces and are documented in the VSI DECnet-Plus for OpenVMS DECdns Management Guide.

Chapter 8. DECdts Module

The VSI DECnet-Plus Distributed Time Service (DECdts) is a networkwide time service that enables you to synchronize and manage the system clocks in a distributed network.

Figure 8.1, “Hierarchy of DECdts Module Entities” shows the hierarchical relationship of the entities that constitute the DECdts module.

Figure 8.1. Hierarchy of DECdts Module Entities
Hierarchy of DECdts Module Entities

Chapter 9. Event Dispatcher Module

This chapter describes all the commands you can use to manage the entities that constitute the Event Dispatcher module. The event dispatcher is an integral component of the Network Architecture (NA) that processes events generated by entities in the network. Each component layer architecture of the Phase V NA architecture, such as Routing, NSP, and ISO Transport, may define certain occurrences, actions, transitions, or conditions as events that are reported and may be logged to assist network or system management. The Event Dispatcher module allows these conditions to be logged and monitored to allow a system manager to view the state of the network. Individual messages are listed and described throughout this manual with the entities that produce them.

Figure 9.1, “Hierarchy of Event Dispatcher Module Entities” shows the hierarchical relationship of the entities that constitute the Event Dispatcher module.

Figure 9.1. Hierarchy of Event Dispatcher Module Entities
Hierarchy of Event Dispatcher Module Entities

9.1. event dispatcher

The event dispatcher entity is the top-level entity in the hierarchy of entities belonging to the Event Dispatcher module. Each NA node must implement an event dispatcher.

Syntax

create [node node-id] event dispatcher

disable [node node-id] event dispatcher

enable [node node-id] event dispatcher

show [node node-id] event dispatcher [all [attributes] | all characteristics | all counters | all status ]

test [node node-id] event dispatcher

9.1.1. Commands

test

The test command is used by the manager to request that an event be logged to test the entire event logging subsystem. This directive tests the complete event logging system from entity to manager and causes the test requested event to be logged.

9.1.2. Characteristic Attributes

NA version

Default: Current version number

Version number of the NA event-logging architecture specification to which the implementation conforms. You cannot modify this characteristic.

9.1.3. Counter Attributes

creation time

Time at which this entity was created.

events lost

Number of events lost at the event dispatcher queue.

test requested (UNIX)

Number of events being generated with the test directive.

9.1.4. Status Attributes

state

Status of the event dispatcher entity.

off

The event dispatcher entity is disabled.

on

The event dispatcher entity is enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

9.1.5. Event Messages

events lost

Generated whenever the event dispatcher cannot allocate resources to queue more events for processing. The event-logging function guarantees that this event cannot be lost. Also, you cannot block this event unless all events for all modules are blocked.

This event is placed at the end of the queue. If another event cannot be queued because of resource limitations while this event is still the last event in the queue, the number argument is updated to reflect the latest total of lost events.

Argument:

number

Number of consecutive events lost.

test requested

Logged when the test directive is issued.

9.1.6. Exception Messages (UNIX)

For enable:

children in wrong state

Another Event Dispatcher module entity is still enabled. Retry the command after you have disabled all of these entities:

  • event dispatcher outbound stream

  • event dispatcher relay

  • event dispatcher relay logging

  • event dispatcher sink

  • event dispatcher sink inbound stream

9.2. event dispatcher outbound stream

An event dispatcher outbound stream entity represents an outgoing connection to a sink on a local or remote node. An outbound stream entity manages the connection to the sink, and it filters, processes, and transmits events to the sink.

Syntax

block [node node-id] event dispatcher outbound stream stream-name {global filter class-name, event-name | specific filter instance-name, event-name }

connect [node node-id] event dispatcher outbound stream stream-name

create [node node-id] event dispatcher outbound stream stream-name [maximum buffer size integer]

delete [node node-id] event dispatcher outbound stream stream-name

disable [node node-id] event dispatcher outbound stream stream-name method method

disconnect [node node-id] event dispatcher outbound stream stream-name

enable [node node-id] event dispatcher outbound stream stream-name

ignore [node node-id] event dispatcher outbound stream stream-name {global filter class-name, event-name | specific filter instance-name, event-name }

pass [node node-id] event dispatcher outbound stream stream-name {global filter class-name, event-name | specific filter instance-name, event-name }

reset [node node-id] event dispatcher outbound stream stream-name

set [node node-id] event dispatcher outbound stream stream-name {catch all filter action | connect retry timer integer | connect timer enabled boolean | disconnect timer integer | sink address sink-address-tower | sink end user end-user-spec | sink node full-name | sink object full-name | template simple-name (UNIX) }

show [node node-id] event dispatcher outbound stream stream-name [all [attributes] | all characteristics | all counters | all identifiers | all status ]

shutdown [node node-id] event dispatcher outbound stream stream-name

testevent [node node-id] event dispatcher outbound stream stream-name event instance-name, event-name

9.2.1. Commands

block

Sets the filters to block the specified events for the entity instance or class. It causes the named events to be blocked.

connect

Causes the outbound stream entity to request a connection to its sink partner. This directive causes the entity to issue a single session connect request to its sink partner, unless the state is already On Connected, in which case the directive has no effect and returns the success response.

disconnect

Disconnects the outbound stream connection to its sink partner. The disconnect directive aborts the entity's outbound stream connection to the sink.

ignore

Sets the filters to ignore the specified events for the entity instance or class. The ignore directive causes the named events to be ignored.

pass

Sets the filter to pass the specified events for the entity instance or class. The pass directive causes the named events to be passed.

reset

Resets the catch all, specific and global filters to the default value. It causes these filters to be reset to the values they had when the entity was created. It is equivalent to setting the values for these filters to their defaults.

shutdown

Requests an orderly shutdown of the connection to the sink partner. The shutdown directive attempts an orderly shutdown of the connection in cooperation with the sink.

testevent

Tests the filter action state for the specified event. This directive applies the filtering algorithm to the named event instance returning the applicable Filter Action, and an indication of whether the search was resolved by the Specific Filter, Global Filter, or Catch All Filter attribute.

9.2.2. Arguments

global filter, class-name, event-name

Specifies a global event filter. The class-name variable specifies a class name, excluding all instance names (for example, node, mop, circuit), The event-name variable identifies the event to be blocked, ignored, or passed. To block, ignore, or pass all events for the class, specify all instead of an individual event.

maximum buffer size integer

Optional argument that specifies the maximum number of octets to be used for event processing of this stream. The current value is displayed in the buffer size status attribute. You can specify a size smaller than the implementation's default, provided it is still sufficient to hold the events lost event. We recommend that you use the default buffer size.

method method

Specifies whether an existing connection should be aborted immediately or shut down in an orderly fashion.

abort

The stream calls the disconnect operation to abort the connection immediately. (This process is described under the disconnect command.)

orderly

The stream calls the shutdown operation to perform an orderly shutdown of the connection. (This process is described under the shutdown command.) The default method is orderly.

specific filter, instance-name, event-name

Specifies a specific event filter. The instance-name variable specifies a full entity name, including the node name and including a specific instance (for example, (node usa:.wmass.ashfld mop circuit una-0), The event-name variable identifies the event to be blocked, ignored, or passed. To block, ignore, or pass all events for the class, specify all instead of an individual event.

9.2.3. Characteristic Attributes

catch all filter

Default: Pass

Value: Block or pass

Action to take if neither the specific filter nor the global filter contains an entry that matches an event.

block

Discard the event.

pass

Report the event.

connect retry timer

Default: 120

Value: 0–65535

Number of seconds to wait after a disconnect or connection reject before reattempting a connection. Connection attempts continue until a connection is made or until the connect timer enabled attribute is set to false or the outbound stream is disabled. If the outbound stream is already connected to the sink when the timer expires, no connection is attempted at that time. The timer resets and connection attempts continue whenever the timer expires.

connect timer enabled

Default: True

Value: True or false

Specifies whether the connect timer is operational (see connect retry timer).

disconnect timer

Default: 0; see description

Value: 0–4294967295

Number of seconds to wait before disconnecting an idle connection. Zero indicates that there is no disconnect timer and connections are never automatically disconnected.

global filter

Current global filter as it has been constructed by block, ignore, and pass commands for this stream. By default, the global filter is set to block all events for the following entities: event dispatcher, event dispatcher sink, and event dispatcher sink inbound stream and to pass all events for the event dispatcher outbound stream entity. You cannot modify this characteristic.

sink address

Default: No address

Value: Sink address tower set

Sink address tower for this stream. Modifying this characteristic affects only subsequent connect requests; existing connections are unaffected.

sink end-user

Default: Number = 82

Value: End-user-specification

Sink Session Control end-user specification for this stream.

sink node

Default: Local node

Value: Full-name

Full DNS node name of the sink for this stream. Modifying this characteristic affects only subsequent connect requests; existing connections are unaffected. This full name is used in combination with the sink end-user characteristic to establish the sink connection.

sink object

Default: No sink object

Value: Full-name

Full DNS object name of the sink for this stream. Modifying this characteristic affects only subsequent connect requests; existing connections are unaffected. This full name should match the object name characteristic of the target sink.

specific filter

Default: No specific filter

Current specific filter setting as constructed by block, ignore and pass commands for this stream. You cannot modify this characteristic.

template (UNIX)

Default: No template

Value: Simple-name

Transport template (see osi transport template) for this stream's connections.

9.2.4. Counters Attributes

confidence changes

Number of times the confidence variable has changed while connections were in the open state.

connect requests

Number of times a connection to a remote node was requested by this stream, either by an explicit command or by the connection timer.

connections accepted

Number of times an outbound connection request was accepted by the sink partner.

creation time

Time at which this entity was created.

disabled

Number of disable events for this stream.

enabled

Number of enable events for this stream.

events lost

Number of events lost because of outbound stream buffer overrun.

filter changes

Number of times the filter has changed.

shutdowns

Number of times a shutdown command or operation was issued.

9.2.5. Identifier Attributes

name

Simple name assigned to the outbound stream when it was created.

9.2.6. Status Attributes

buffer size

Maximum number of octets allowed for event processing of this stream. This value is defined in the create command for the stream.

state

Status of the outbound stream.

off

The stream is disabled.

on

The stream is enabled.

onconnected

The stream is enabled and has an established connection.

onconnecting

The stream is enabled and is in the process of establishing a connection.

ondisconnecting

The stream is enabled, but is in the process of disconnecting from a connection.

onshutdownrequested

The stream is enabled and has an established connection, but is in the process of shutting down;the stream will disconnect after it transmits all events that were outstanding when the shutdown command was issued.

uid

Entity's unique identifier, which is generated when the entity is created.

9.2.7. Event Messages

change confidence

Generated each time the transport service detects a change in the connection's confidence value. (The confidence value indicates whether the Transport layer expects a transmit operation to succeed.) This event suggests a change in the connectivity between the outbound stream and the sink.

Argument:

confidence

New transport confidence value.

false

It is unlikely that a transmit operation would succeed under the current circumstances.

true

It is likely that a transmit operation would succeed under the current circumstances.

change filter

Generated each time the filter for a stream is changed, whether it is changed by a block, ignore, or pass command or by using set to change the value of the catch all filter characteristic. The initial values of the filters for a stream are reported as arguments in the enable stream event. A filter change event is filtered according to its new values.

Arguments: (for OpenVMS)

new catch all filter

Current catch-all filter setting.

new global filter

Current global filter setting.

new specific filter

Current specific filter setting.

old catch all filter

Previous catch-all filter setting.

old global filter

Previous global filter setting.

old specific filter

Previous specific filter setting.

disable

Generated each time an outbound stream is disabled by a disable command.

disconnect

Generated each time a connection is closed on an outbound stream. The disconnect can be caused by the event dispatcher closing idle connections, a management command, a network failure, a sink crash, or a sink disconnect.

Arguments:

disconnect data

Identifies the cause of the disconnect.

0

remote disconnect

2

shutdown requested (OpenVMS)

3

management directive

reason

Session Control layer reason for the disconnect.

enable

Generated each time an outbound stream is enabled by an enable command.

Arguments:

catch all filter

Value of the catch-all filter when the stream is enabled.

global filter (optional)

Value of the global filter when the stream is enabled.

specific filter (optional)

Value of the specific filter when the stream is enabled.

events lost

Generated whenever the outbound stream cannot allocate resources for event transmission. The event-logging function guarantees that this event cannot be lost. Also, you cannot block this event unless all events for all modules are blocked.

This event is placed at the end of the queue. If another event cannot be queued because of resource limitations while this event is still the last event in the queue, the number argument is updated to reflect the latest total of lost events.

Argument:

number

Number of consecutive events lost.

shutdown

Generated each time a shutdown operation results in an orderly disconnect. You cannot block shutdown events for an outbound stream.

Arguments:

reason

canceled

The shutdown was "neutralized" by an intervening disconnect; therefore, the receiver should not shut down.

disconnect timer

The shutdown was caused by the disconnect timer.

disable directive

The shutdown was caused by a disable command that specified an orderly shutdown.

shutdown directive

The shutdown was caused by a shutdown command.

9.2.8. Exception Messages

For connect:

connection failed

The connection attempt failed. The exception may include additional arguments that give more information about the failure.

Arguments:

reason

The connection failed at the Session Control layer.

data

This field can include optional data that describes the reason the connection attempt failed.

no sink specified

All of the sink specifier attributes are null.

wrong state

The operation failed because the entity was not in off, onconnecting, or ondisconnecting state.

For block and ignore:

illegal block

The attempted block operation is illegal; for example, the command attempted to block the event dispatcher outbound stream events lost or shutdown events.

illegal element

The command did not include a class-name or instance-name argument, or an argument contained one of the following illegal elements: wildcard, node name, node class, illegal class.

For delete:

wrong state

The operation failed because the entity was not in an off state.

For disable:

incomplete

Orderly disable could not be completed due to lack of transport confidence.

9.3. event dispatcher relay

The event dispatcher relay entity processes events from Phase IV DECnet-Plus systems. It receives Phase IV format events and posts them into the DECnet-Plus logging system.

Syntax

create [node node-id] event dispatcher relay

delete [node node-id] event dispatcher relay

disable [node node-id] event dispatcher relay

enable [node node-id] event dispatcher relay

show [node node-id] event dispatcher relay [all [attributes] | all status ]

9.3.1. Status Attributes

state

Status of the event dispatcher relay entity.

off

The event dispatcher relay entity is disabled.

on

The event dispatcher relayentity is enabled.

9.3.2. Exception Messages

For delete:

entity has children

Cannot delete while subentities exist.

wrong state

Failure to delete the event dispatcher relay entity because the relay must be disabled before deletion.

9.4. event dispatcher relay logging

Three event dispatcher relay logging entities are created and enabled automatically whenever an event dispatcher relay entity is enabled. The logging entities (console, file, and monitor) control the destination of Phase IV events. Each logging entity can be disabled and reenabled individually. All three logging entities are deleted automatically when the Phase IV relay entity is disabled.

Syntax

disable [node node-id] event dispatcher relay logging logging-name

enable [node node-id] event dispatcher relay logging logging-name

show [node node-id] event dispatcher relay logging logging-name [all [attributes] | all counters | all identifiers | all status ]

9.4.1. Counter Attributes

creation time

Time at which this entity was created.

events relayed

Number of Phase IV events relayed for this logging type.

9.4.2. Identifier Attributes

name

Logging type is console, monitor, or file.

9.4.3. Status Attributes

state

Status of the event dispatcher relay logging entity.

off

The event dispatcher logging entity is disabled.

on

The event dispatcher logging entity is enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

9.4.4. Event Messages

event relayed

Generated whenever a Phase IV event is received. It relays the Phase IV event into the DECnet-Plus Event Logging Architecture. The entire DECnet-Plus NICE message is encapsulated into the NICE (Network Information and Control Exchange) data argument.

Argument:

NICE data

Phase IV event display

9.5. event dispatcher sink

An event dispatcher sink entity represents a sink. A sink manages incoming connections and filters incoming events. Each sink maintains a filter that is applied to all streams that are assigned to that sink. The simple-name refers to the sink managed by this command.

block [node node-id] event dispatcher sink simple-name {global filter class-name, event-name | specific filter instance-name, event-name}

create [node node-id] event dispatcher sink simple-name maximum buffer size integer

delete node node-id] event dispatcher sink simple-name

disable [node node-id] event dispatcher sink simple-name

enable [node node-id] event dispatcher sink simple-name

ignore [node node-id] event dispatcher sink simple-name {global filter class-name, event-name | specific filter instance-name, event-name}

pass [node node-id] event dispatcher sink simple-name {global filter class-name, event-name | specific filter instance-name, event-name}

reset [node node-id] event dispatcher sink simple-name

set [node node-id] event dispatcher sink simple-name {catch-all filter action | client type sink-type | device name filespec | description latin1string | display uids boolean | end user end-user-spec | file name filespec | object name full-name | template simple-name | user client end-user-spec}

show [node node-id] event dispatcher sink simple-name [all [attributes] | all characteristics | all counters | all identifiers | all status]

testevent [node node-id] event dispatcher sink simple-name event instance-name, event-name

9.5.1. Commands

block

Sets the filters to block the specified events for the entity instance or class. It causes the named events to be blocked.

ignore

Sets the filters to ignore the specified events for the entity instance or class. The ignore directive causes the named events to be ignored.

pass

Sets the filter to pass the specified events for the entity instance or class. The pass directive causes the named events to be passed.

reset

Resets the catch-all, specific and global filters to the default value. It causes these filters to be reset to the values they had when the entity was created. It is equivalent to setting the values for these filters to their defaults.

testevent

Tests the filter action state for the specified event. This directive applies the filtering algorithm to the named event instance returning the applicable FilterAction, and an indication of whether the search was resolved by the SpecificFilter, GlobalFilter, or CatchAllFilter attribute.

9.5.2. Arguments

global filter, class-name, event-name

Specifies a global event filter. The class-name variable specifies a class name, excluding all instance names (for example, node, mop, circuit), The event-name variable identifies the event to be blocked, ignored, or passed. To block, ignore, or pass all events for the class, specify all instead of an individual event.

maximum buffer size integer

This optional argument specifies the maximum number of octets to be used for event processing of this sink. The current value is displayed in the buffer size status attribute. You can specify a size smaller than the implementation's default, provided it is still sufficient to hold the events lost event. If the value specified in this argument is inadequate for the events lost event, an insufficient resources exception is returned.

specific filter, class-name, event-name

Specifies a specific event filter. The instance-name variable specifies a full entity name, including the node name and including a specific instance (for example, (node usa:.wmass.ashfld mop circuit una-0). The event-name variable identifies the event to be blocked, ignored, or passed. To block, ignore, or pass all events for the class, specify all instead of an individual event.

9.5.3. Characteristic Attributes

catch all filter

Default: Pass

Value: Block or pass

Specifies the action to take if neither the specific filter setting nor the global filter setting matches an event or if a filter setting that does match an event is set to Ignore.

block

Discard the event.

pass

Report the event.

client type

Default: Console

Value: See description

Specifies the application to accept the events received by the sink. This can only be set when the event dispatcher sink entity is disabled (when the sink state is off).

console

Events go to the operator's console.

device

Events go to a device (refer to the device name characteristic).

file

Events go to a file (refer to the filename characteristic).

description

Default: Null

Value: Latin1String

Application description string.

device name

Default: Null

Value: Latin1String

Name of the device to which events are going to be logged, if the client type of the sink is device.

displayuids

Default: True

Value: Boolean

A Boolean value indicating whether to include the UIDs when displaying an event.

end user

Default: Number = 82

Value: End-user-specification

Sink Session Control end-user specification for this sink. For UNIX, do not modify this characteristic.

file name

Default for UNIX: /usr/adm/event_file

Value: File specification

Default for OpenVMS: SYS$MANAGER:NET$EVD_SINK_sinkname.LOG

Value: File specification

Name of the file to which events are going to be logged if the client type of the sink is file.

global filter

Current global filter as it has been constructed by block, ignore, and pass commands for this sink. By default, the global filter is set to block all events for the following entities: event dispatcher, event dispatcher sink, and event dispatcher sink inbound stream. You cannot modify this characteristic.

object name

Default: No sink object

Value: Full-name

Full DNS object name of the sink. Modifying this characteristic affects only subsequent connect requests; existing connections are unaffected.

specific filter

Default: No specific filter

Current specific filter setting as constructed by block, ignore and pass commands for this sink. You cannot modify this characteristic.

template (UNIX)

Default: No template

Value: Simple-name

Transport template (see the osi transport template entity) for this sink's connections.

user client (UNIX)

Default: Null

Value: End-user-specification

Session Control end-user specification for a user program that has been set to receive events.

9.5.4. Counter Attributes

creation time

Time this entity was created.

connections accepted

Number of times a sink connection request was accepted by the sink partner.

events filtered

Number of events for this sink that were filtered by its sink filter.

events lost

Number of events lost due to sink queue overflow.

filter changes

Number of times the filter has changed.

9.5.5. Identifier Attributes

name

Simple name assigned to the sink when it is created.

9.5.6. Status Attributes

buffer size

Maximum number of octets allowed for event processing of this sink. This value is defined in the create command for the sink. This value is limited by the value specified in the maximum buffer size argument of the create command.

state

Status of the sink.

off

The sink is disabled.

on

The sink is enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

9.5.7. Event Messages

change filter

Generated each time the filter for a sink is changed, whether it is changed by a block, ignore, or pass command or by using set to change the value of the catch all filter characteristic. The initial values of the filters for a sink may be reported as arguments in the enable sink event. A filter change event is filtered according to its new values.

Arguments: (for OpenVMS)

new catch all filter

Current catch-all filter setting.

new global filter

Current global filter setting.

new specific filter

Current specific filter setting.

old catch all filter

Previous catch-all filter setting.

old global filter

Previous global filter setting.

old specific filter

Previous specific filter setting.

events lost

Generated whenever the sink cannot allocate resources for event transmission. The event-logging function guarantees that this event cannot be lost. Also, you cannot block this event unless all events for all modules are blocked.

This event is placed at the end of the queue. If another event cannot be queued because of resource limitations while this event is still the last event in the queue, the number argument is updated to reflect the latest total of lost events.

Argument:

number

Number of consecutive events lost.

9.5.8. Exception Messages

For delete (UNIX):

has children

Cannot delete while subentities exist.

wrong state

The attempt to delete the event dispatcher sink entity failed because the sink must be disabled before deletion.

For block, pass, and ignore:

illegal element

The command did not include a class or instance argument, or an argument contained one of the following illegal elements: wildcard, node name, node class, illegal class.

For enable:

invalid name

Invalid name for NA session.

9.6. event dispatcher sink inbound stream

The event dispatcher sink inbound stream entity is the sink-side end of communication between an event dispatcher and a sink. An inbound stream entity is dynamically created, enabled, disabled, and deleted in tandem with the connection it represents.

Syntax

disconnect [node node-id] event dispatcher sink simple-name inbound stream simple-name

show [node node-id] event dispatcher sink simple-name inbound stream simple-name [all [attributes] | all counters | all identifiers | all status ]

9.6.1. Commands

disconnect

Requests the disconnection of the entity's stream connection. It disconnects the entity's stream connection immediately. Event reports in transit are lost and the sink cannot perform an orderly shutdown on a stream.

9.6.2. Counter Attributes

creation time

Time at which this entity was created.

change confidence

Number of times the confidence variable has changed while connections were in the on state.

9.6.3. Identifier Attributes

name

Local name assigned to the entity by its sink parent when it is dynamically created.

9.6.4. Status Attributes

source end user

Source end-user specification, as provided by Session Control.

source node name

Name of the source node, as provided by Session Control.

state

Status of the inbound event stream.

off

The stream is disabled.

on connected

The stream is enabled and connected to the outbound stream.

uid

Entity's unique identifier, which is generated when the entity is created.

9.6.5. Event Messages

change confidence

Generate when the underlying transport service detects that the connection's confidence variable has changed to the new value reported by the confidence parameter. This suggests a change in the connectivity between the outbound stream and the sink.

Argument:

confidence

The new transport confidence value.

false

It is unlikely that a transmit operation would succeed under the current circumstances.

true

It is likely that a transmit operation would succeed under the current circumstances.

disconnect

Generated each time the sink detects that an inbound stream connection has been closed. The disconnect can be caused by a management command, a sink disconnect, a network failure, or by receiving notice that the associated outbound stream entity has been shut down.

Arguments:

disconnect data

Identifies the cause of the disconnect.

reason

Specifies the Session Control layer reason for the disconnect.

shutdown received

Inbound stream disconnected because of a shutdown event.

Chapter 10. FDDI Module

This chapter describes all the commands you can use to manage the entities that constitute the FDDI module. The FDDI module implements one of multiple possible Link level/Network level modules in the OSI layered architecture model.

The Network Architecture (NA) Fiber Distributed Data Interface (FDDI) is the basis for the second generation of network interconnect architecture for VSI. The FDDI module implements one of the multiple possible Link level/Physical level modules in the OSI layered architecture model. The FDDI Physical level includes high-speed, 125-megabaud, fiber-optic links that may be many kilometers in length. The FDDI Link level provides a high-bandwidth, 100-megabit-per-second local area network (LAN), and uses the ANSI standard FDDI Token Ring.

Figure 10.1, “Hierarchy of FDDI Module Entities” shows the hierarchical relationship of the entities that constitute the FDDI module.

Figure 10.1. Hierarchy of FDDI Module Entities
Hierarchy of FDDI Module Entities

The FDDI module incorporates the functions and operations defined in the ANSI FDDI Token Ring media access control (MAC), the ANSI FDDI Token Ring Physical Layer Protocol (PHY), FDDI Physical Layer Medium Dependent (PMD), Station Management (SMT) specifications, parts of the ISO 8802-1 (IEEE 802.1) addressing, internet working and network management, and parts of the ISO8802-2 (IEEE 802.2) logical link control (LLC) specifications.

10.1. fddi

The fddi entity is the top-level entity in the hierarchy of entities belonging to the FDDI module.

create [node node-id] fddi

delete [node node-id] fddi

show [node node-id] fddi [all [attributes] | all characteristics]

10.1.1. Characteristic Attributes

version

Default:

Current version number

Version number of the FDDI architecture specification to which the implementation conforms. You cannot modify this characteristic.

10.1.2. Exception Messages

For create:

already exists

An fddi entity already exists.

For delete:

has children

Cannot delete while subentities exist.

10.2. fddi station

An fddi station entity represents an access point to the service offered by the FDDI module. The FDDI data link can be monitored and controlled through NA network management. The station-name refers to the station managed by this command.

create [node node-id] fddi station station-name communication port device-name

delete [node node-id] fddi station station-name

disable [node node-id] fddi station station-name

enable [node node-id] fddi station station-name mode {normal | internal loopback}

show [node node-id] fddi station station-name [all [attributes] | all characteristics | all counters | all identifiers | all status]

10.2.1. Arguments

communication port

The system device name assigned to this station.

On OpenVMS systems, the name must be in the format ddc, where dd is the OpenVMS device name prefix and c is the controller letter. For a complete list of FDDI devices and their OpenVMS device names, see the DECnet-Plus for OpenVMS Release Notes.

On UNIX systems, the name must be in the format ddn, where dd is the UNIX device name prefix and n is the device number.

This argument determines the value of the communications port characteristic and is required.

10.2.2. Characteristic Attributes

communication port

Name of the hardware port associated with this station, taken from the corresponding argument in the create directive. You cannot modify this characteristic.

smt maximum version id

Highest SMT version ID this station supports. You cannot modify this characteristic.

smt minimum version id

Lowest SMT version ID this station supports. You cannot modify this characteristic.

smt station id

SMT station ID for this station. You cannot modify this characteristic.

smt version id

Currently active SMT version ID for this station. You cannot modify this characteristic.

type

SMT station type for this station. You cannot modify this characteristic.

10.2.3. Counter Attributes

Unless stated otherwise, counts include both normal and multicast traffic and all protocol types, service access points (SAPs), and protocol identifiers.

configuration changes

Number of times the internal configuration of this station changed. (Not present in single attached stations (SAS)).

creation time

Time at which the port was created.

selftest failures

Total number of times a self-test of the station detected an error.

traces received

Number of times the ECM state machine for this station entered the trace state due to a received trace signal.

10.2.4. Identifier Attributes

name

Simple name assigned to the station when it is created.

10.2.5. Status Attributes

last set station id

The station ID of the station that last performed an SMT Change/Add/Remove (PMF frame) operation.

state

Default: None

Value: Off, on or loopback

Operational state of the station.

uid

Entity's unique identifier, which is generated when the entity is created.

10.2.6. Event Messages

configuration change

Internal configuration of the station changed.

selftest failure

An implementation-specific code giving the reason for the station failure. Values are listed in the NA registry.

trace received

ECM state machine of the station entered the trace state due to a trace signal received on any PHY port.

10.2.7. Exception Messages

For create:

already exists

An fddi station entity already exists.

For enable:

communication port in use

Communication port already reserved by another entity.

invalid communication port

Cannot run FDDI data link on this communications port.

For delete:

wrong state

Failure to delete the fddi station entity because the station must be disabled before deletion.

10.3. fddi station link

The fddi station link entity is a subentity of the fddi station entity. The fddi station link subentity provides the management view of LLC and the FDDI MAC. FDDI allows stations to be either single MAC or dual MAC and therefore there can be up to two link subentities for each station. In most cases, a station has at least one link entity. Concentrators may have no link entity and are not addressable on the FDDI, though they may be using other communications channels.

disable [node node-id] fddi station station-name link link-index

echo [node node-id] fddi station station-name link link-index target ID802 timeout integer-16 data octet-string

enable [node node-id] fddi station station-name link link-index

getnif [node node-id] fddi station station-name link link-index target ID802 timeout integer-16

getsif [node node-id] fddi station station-name link link-index target ID802 timeout integer-16type {configuration | operation}

show [node node-id] fddi station station-name link link-index[all [attributes] | all characteristics | all counters | all identifiers | all status]

10.3.1. Commands (UNIX)

echo

Causes the link subentity to transmit an SMT Echo request frame and await the response. If a response is received, it is displayed.

getnif

Causes the link subentity to transmit an SMTNIF (Neighbor Information) request frame and await the response. If a response is received, it is displayed.

getsif

Causes the link subentity to transmit an SMT SIF (Station Information) request frame and await the response. If a response if received, it is displayed.

10.3.2. Arguments

data

Data to transmit in echo request.

target

Default: None

Value: ID802

48-bit LAN address of the target.

timeout

Default: None

Value: 1–65535

Timeout in seconds.

type

Default: None

Value: Configuration or operation

SIF configuration or SIF operation request.

10.3.3. Characteristic Attributes

link address

MAC address assigned during manufacture of the communication hardware that is associated with the station (read-only).

requested trt

Default: 8

Value: 1–65535

Requested token rotation timer. For OpenVMS, the default is determined by the operating system, and this characteristic cannot be set.

restricted token timeout

Default: 1000

Value: 1–65535

Length limit of a restricted token dialog. For OpenVMS, the default is determined by the operating system, and this characteristic cannot be set.

ring purger enable

Default: True

Value: True or false

Controls whether this station is eligible to be a ring purger and should participate in the ring purger election. For OpenVMS, the default is determined by the operating system, and this characteristic cannot be set.

valid transmission time

Default: 3.4

Value: 1–65535

Valid transmission time. For OpenVMS, the default is determined by the operating system, and this characteristic cannot be set.

10.3.4. Counter Attributes

block check errors

Number of times a received frame containing an integral number of octets failed the FCS check.

creation time

Time at which the station was created.

directed beacons received

Number of times the link detected the directed beacon process.

duplicate address test failures

Number of times the duplicate address test failed (detected that the link address was a duplicate).

duplicate tokens detected

Number of times the MAC address test failed (detected that the link address was a duplicate).

error count

Total number of frames that were in error with the E indicator reset, indicating that the error occurred between the upstream MAC and this one.

fci strip errors

Number of times a frame content independent strip operation (bridge strip) was terminated by receipt of a token.

frame count

Total number of frames seen by this link, other than tokens.

frame status errors

Number of times a received frame had the E indicator in error (missing or set) and the FCS was correct.

lost count

Counter lost count.

multicast octets received

Number of multicast data octets that were received successfully in multicast frames of type LLC, implementer, reserved, or SMT. The count does not include the MAC envelope.

multicast octets sent

Number of multicast data octets that were sent successfully in multicast frames of type LLC, implementer, reserved, or SMT. The count does not include the MAC envelope.

multicast pdus received

Number of multicast frames that were received successfully of type LLC, implementer, reserved, or SMT.

multicast pdus sent

Number of multicast frames that were sent successfully of type LLC, implementer, reserved, or SMT.

octets received

Number of octets received successfully in frames of type LLC, implementer, reserved, or SMT. The count does not include the MAC envelope.

octets sent

Number of octets sent successfully in frames of type LLC, implementer, reserved, or SMT. The count does not include the MAC envelope.

pdu length errors

Number of times a received frame had an invalid length, either too long or short for the type, or had an alignment error (odd number of symbols).

pdus received

Number of frames received successfully in frames of type LLC, implementer, reserved, or SMT.

pdus sent

Number of frames sent successfully in frames of type LLC, implementer, reserved, or SMT.

receive data overruns

Number of times the hardware lost one or more consecutive, only partially complete incoming frames because it was unable to keep up with the medium rate. An example is overrun of a bit or octet FIFO queue because of inability to copy data from adapter to host promptly. In conjunction with total frames received, provides a measure of hardware resource and bandwidth failures.

ring beacons initiated

Number of times the ring beacon process was initiated by this link.

ring initializations initiated

Number of times a ring reinitialization was initiated by this link.

ring initializations received

Number of times a ring reinitialization was initiated by some other link.

ring purge errors

Number of times the ring purger received a token while still in the ring purge state.

token count

Number of times a token has been seen by this link.

traces initiated

Number of times the pc_trace process was initiated by this link.

transmit failures

Number of times a transmit error, other than underrun, occurred. This does not include errors in transmitting MAC type frames.

transmit underruns

Number of times a transmit underrun occurred. This indicates the transmit FIFO became empty during frame transmission.

unavailable link buffers

Number of times a complete, fully received frame was discarded because no link buffer was available. In conjunction with total frames received, provides a measure of station-buffer-related receive problems.

unavailable user buffers

Number of times no user buffer was available for an incoming frame that passed all filtering for the port. These are the buffers supplied by users on receive requests. In conjunction with total frames received, provides a measure of user-buffer-related receive problems.

unrecognized individual destination pdus

Number of times a received LLC frame with an individual destination MAC address was discarded because there was no port with the Ethernet protocol type, SNAP protocol identifier, or LLC SAP address enabled. Only frames containing individual destination MAC addresses are counted.

unrecognized multicast destination pdus

Number of times a received LLC frame with a multicast destination MAC address was discarded because there was no port with the Ethernet protocol type, SNAP protocol identifier, or LLC SAP address enabled. Only frames containing multicast destination MAC addresses are counted.

10.3.5. Identifier Attributes

index

An integer that uniquely identifies this link to the parent station entity.

10.3.6. Status Attributes

downstream neighbor

MAC address of the downstream neighbor, if known.

duplicate address flag

Summary output of the duplicate address test algorithm.

frame strip mode

Current frame-stripping mode of the MAC.

SA match

Source address match mode of the frame stripping algorithm matches the source address of the frame with the MAC's MyLongAddress (MLA), and if a match is found, the frame is removed from the token ring.

FCI strip

The FCI strip mode counts the number of frames transmitted since the reception of a token, and strips equal number of frames.

loopback

This is true if the link has been set up to receive frames transmitted by it. This allows loopback testing either on the ring or with one of the PHY port loopback modes.

negotiated trt

Negotiated token rotation timer.

old downstream neighbor

Previous value of the downstream neighbor.

old upstream neighbor

Previous value of the upstream neighbor.

ring error reason

Reason code for the most recent link error.

directed beacon received

Link received particular beacon data.

duplicate address detected

Duplicate address algorithm detected a duplicate address.

duplicate token detected

A duplicate token was detected on the ring.

FCI strip error

Frame content independent strip operation was terminated by the receipt of a token.

no error

No errors have occurred on this ring.

PC trace initiated

PC-trace was initiated by this link.

PC trace received

PC-trace was initiated by some other link.

ring beaconing initiated

Ring beaconing process was initiated by this link. This process is initiated as a result of serious ring failure, such as loss of signal or jabbering station transmitting in violation of the protocol. This indicates to other links on the LAN that corrective action may be required.

ring init initiated

Ring initialization was initiated by this link to initialize the ring and create a token.

ring init received

Ring initialization was initiated by some other link to initialize the ring and create a token.

ring op oscillation

Ring state has been changing continually from operational to initializing.

ring purge error

Link received a token while performing a ring purge operation.

ring latency

Current ring latency as measured by this linkentity.

ring purger state

State of the ring purger election process.

candidate

The link's ring purger process is participating in the ring purger election algorithm as a candidate to become the ring purger.

nonpurger

The link's ring purger process is in an idle state listening for periodic purger hello frames.

off

The link's ring purger process is disabled.

purger

The link's ring purger process is performing the function of removing no owner frames and duplicate token from the ring. In this state, the process transmits periodic purger hello frames.

state

State of the link entity.

broken

Attempt to turn the link on failed the initialization test, or link was on, but failure was detected.

off-fault recovery

State entered when a link entity detects conditions that indicate faulty ring.

off-ready

FDDI data link communication services are not available.

on-ring init

Physical layer service is available and the link entity enabled.

on-ring run

Link detected that the ring initialization has been completed successfully and the ring is operational.

uid

Entity's unique identifier, which is generated when the entity is created.

upstream neighbor address

MAC address of the upstream neighbor, if known.

upstream neighbor duplicate address flag

Default: None

Value: True or false

Upstream neighbor's reported result of its duplicate address test.

10.3.7. Event Messages

block check error

Frame with FCS error was received.

directed beacon received

A directed beacon was received.

duplicate address test failure

Duplicate address algorithm detected a duplicate.

duplicate token detected

Duplicate token is detected.

fci strip error

Frame content independent strip was terminated by a token.

frame status error

Frame with good FCS, but E indicator set was received.

link buffer unavailable

No buffer was available to receive a frame.

pdu length error

Frame of invalid length or odd number of symbols was received.

receive data overrun

A receive overrun hardware error was detected.

ring beacon initiated

Link started the beacon process.

ring initialization initiated

Ring is reinitialized by this link.

ring initialization received

Ring is reinitialized by some other link.

ring purge error

Ring purger received a token while purging.

trace initiated

PC-trace was initiated by this link.

transmit failure

Failure to transmit operation other than underrun.

transmit underrun

Transmit failed due to underrun.

unrecognized individual pdu destination

Frame with unrecognized DSAP or port-id.

unrecognized multicast pdu destination

Frame with unrecognized DSAP or port-id.

user buffer unavailable

Data link user did not supply a receive buffer.

10.3.8. Exception Messages

For GetSIF, GetNIF, and echo (UNIX):

reject

Request was rejected by the target station.

timeout

No response was received.

10.4. fddi station phy port

An fddi station phy port entity provides the management view of the fddi station phy port and the fddi pmd. Each station has at least one physical port and a concentrator is a device that has at least one physical port of type M. A dual-attached station or dual-attached concentrator has a phy port type A and type B. A single-attached station has a phy port of type B. The port-id is an integer that represents the physical port to be managed by the command.

disable [node node-id] fddi station station-name phy port port-id

enable [node node-id] fddi station station-name phy port port-id mode {normal | internal loopback}

show [node node-id] fddi station station-name phy port port-id {all [attributes] | all characteristics | all counters | all identifiers | all status}

10.4.1. Characteristic Attributes

lem threshold

Default: None

Value: For n, 10 -n

Link error monitor threshold. This characteristic cannot be set.

phy type

Type of physical port (A, B, S, or M). This characteristic cannot be set.

pmd type

Type of PMD (transceiver) for this physical port. This characteristic cannot be set.

ANSI multimode

Low power

ANSI multimode type 1

ThinWire

ANSI single mode type 2

Shielded twisted-pair

ANSI SONET

Unshielded twisted-pair

10.4.2. Counter Attributes

creation time

Time at which the port was created.

connections completed

Number of times the physical port entered the in use state, having completed the initialization process.

elasticity buffer errors

Number of times the elasticity buffer function had an overflow or underflow.

lct rejects

Number of times a connection was rejected due to failure of the link confidence test at either end of the physical connection.

lem rejects

Number of times an active connection was disconnected due to rejection by the link error monitor at this end of the physical connection, or by expiration of the Noise timer.

link errors

Total number of raw link error input events seen by the link error monitor.

10.4.3. Identifier Attributes

index

An integer that uniquely identifies this physical port to the parent station entity.

10.4.4. Status Attributes

broken reason

Reason phy port is in broken state, or if in broken state, none.

estimated link error rate

Default: None

Value: 1–256

Link error monitor current estimate of error rate.

neighbor phy type

Status may be A, B, S, M or unknown.

reject reason

Reason the phy port is in a failed or watch state. This is not meaningful when phy port is in some other state.

LCT both sides

link confidence test failed on both sides of the physical connection.

LCT protocol error

Neighboring physical port has been detected to have prematurely exited the link confidence test (LCT).

LEM reject

Link error monitor disconnected this connection due to the error rate exceeding the LEM threshold.

local LCT

Link confidence test failed on this end of the physical connection.

noise reject

Noise timer expired because a single noise event lasted for more than 1.31072 ms.

none

No reason.

remote LCT

Link confidence test failed on the other end of the physical connection.

remote reject

Neighboring physical port broke the connection for an unknown reason.

standby

Physical port and its neighboring physical port form a redundant physical connection (dual-homing feature). In a dual-homed configuration, the B to M connection is the higher priority physical connection, and the A to M connection is the standby physical connection. The standby connection will become active if the B to M connection is lost.

topology reason

Neighboring physical port's physical port type is an illegal match for this physical port's physical port type.

trace in progress

Physical port was initializing when a pc-trace occurred. When a pc-trace occurs, any physical ports that have not yet established a physical connection are shutdown to prevent the topology from changing.

trace received-disabled

Physical port was momentarily disabled because it received a pc-trace when its own pc-trace function was disabled. The pc-trace function is enabled by default. The trace disable switch is not remotely manageable.

state

Operational state of the phy port entity (nonsettable).

broken

The physical port has failed initialization tests and is not available for use.

failed

Same as waiting, except the physical port has failed to complete the last connection attempt. Refer to the physical port's status parameter reject reason, for the reason for connection failure. Connection attempts will continue until successful.

internal loopback

The physical port has been configured to internally present all transmitted symbols to the receive interface. The network connector is inactive. This allows internally generated test frames to be looped back for test purposes.

in use

The physical port has established a connection and is fully operational. Communications services are now available.

off-ready

The physical port is waiting to be enabled or has been disabled by management request.

starting

The physical port has received a response from the neighboring physical port and is exchanging information and performing the link confidence test (LCT) prior to completing the connection.

waiting

The physical port is beginning to establish a connection and is waiting for a response from the neighboring physical port.

watch

Same as starting, except the physical port has failed to complete the last connection attempt. Refer to the physical port's status parameter, reject reason, for the reason for connection failure. Connection attempts will continue until successful.

uid

Entity's unique identifier, which is generated when the entity is created.

10.4.5. Event Messages

link confidence test reject

Counted as LCT rejects.

link elasticity buffer error

Counted as elasticity buffer errors.

link error monitor reject

Counted as LEM rejects.

10.4.6. Exception Messages

For enable:

invalid mode

Specified mode conflicts with station mode.

10.5. fddi port

An fddi port entity represents an access point to the service offered by the FDDI module. A client transmits and receives data through a port. Ports are created and deleted by client use of open and close service interface procedures. The port-name refers to the port managed by this command.

Syntax

show [node node-id] fddi port port-name [all [attributes] | all counters | all identifiers | all status]

10.5.1. Counter Attributes

creation time

Time at which the port was created.

multicast octets received

Number of multicast user data octets received successfully and available to the data link user.

multicast octets sent

Number of multicast user data octets transmitted successfully using the port.

multicast pdus received

Number of multicast frames received successfully and available to the data link user.

multicast pdus sent

Number of multicast frames transmitted successfully using the port.

octets received

Number of user data octets received successfully and available to the data link user.

octets sent

Number of user data octets transmitted successfully using the port.

pdus received

Number of frames received successfully and available to the datalink user.

pdus sent

Number of frames transmitted successfully using the port.

unavailable user buffers

Number of times no user buffer was available at the port for an incoming frame.

10.5.2. Identifier Attributes

name

Simple name assigned to the port when it is created.

10.5.3. Status Attributes

client

Name specified by the data link when the port is opened.

ethernet protocol types

Set of Ethernet protocol types that are recognized for this port. Protocol types for a port may be enabled and disabled by the user at anytime during the port's existence.

length present

Default: None

Value: True or false

Indicates whether or not the data link adds a length field on transmit, assumes the presence of the length field, and removes the length field on receive for Ethernet frames. This attribute is irrelevant for ISO 8802-3 formatted frames because the length field is always present. This is specified by the user when the port is opened. The value true means length fields are added and removed by the data link.

link

Name of the link subentity associated with this port, specified by the user when the port is opened.

llc sap addresses

Set of SNAP protocol identifiers that are recognized for this port. LLC SAP addresses for a port may be enabled and disabled by the user at any time during the port's existence.

llc service

Default: None

Value: Class 1 or user supplied

LLC PDU processing the data link user requires from the port, specified by the user when the port is opened. This is either LLC Class 1, where the entire LLC protocol is handled by the data link, or user-supplied LLC, where the user is responsible for operating part of the LLC protocol.

mac addresses

Set of individual and multicast MAC addresses that are recognized for this port. MAC addresses for a port may be enabled and disabled by the user at any time during the port's existence.

receive mode

Default: None

Value: Normal or promiscuous

Indicates if the port is to receive all frames regardless of format, Ethernet protocol type, SNAP protocol identifier, LLC SAP address, or MAC address. Promiscuous receipt is enabled and disabled by the user. Support of promiscuous mode is optional.

snap protocol identifiers

Set of SNAP protocol identifiers that are recognized for this port. Protocol identifiers for a port may be enabled and disabled by the user at any time during the port's existence.

type

Type of port (LLC or SMT).

uid

Entity's unique identifier, which is generated when the entity is created.

Chapter 11. Frame Module (OpenVMS)

This chapter describes all the commands you can use to manage the entities that constitute the Frame module. The Frame module provides framing functions for a communications link. It enables those who implement their own level 2 protocols to manage the links that use those protocols.

Figure 11.1, “Hierarchy of Frame Module Entities” shows the hierarchical relationship of the entities that constitute the Frame module.

Figure 11.1. Hierarchy of Frame Module Entities
Hierarchy of Frame Module Entities

11.1. frame

The frame entity is the top-level entity in the hierarchy belonging to the Frame module. The entity provides framing functions for a communications link. The entity does not provide any data link protocol capabilities, and is used by those who want or need to operate their own level 2 protocols.

Syntax

create [node node-id] frame

delete [node node-id] frame

disable [node node-id] frame

enable [node node-id] frame

show [node node-id] frame [all [attributes] | all characteristics | all status]

11.1.1. Characteristic Attributes

version

Version of the frame architecture to which the implementation conforms. You cannot modify this characteristic.

11.1.2. Status Attributes

state

State of the frame entity.

off

The frame entity is disabled.

on

The frame entity is enabled.

11.3. frame port

A frame port entity represents an access point to the data link service offered by the Frame module. Ports are created and deleted automatically when a client of DDCMP uses the link.

Syntax

show [node node-id] frame port port-name [all [attributes] | all identifiers | all status ]

11.3.1. Identifier Attributes

name

Simple name assigned to the port when it is created.

11.3.2. Status Attributes

client

Name of the client entity that opened the port.

link

Name of the frame link entity that the client supplied when the port was opened.

state

State of the frame port entity.

open

The port is assigned to a client.

open disabled

The port is assigned to a client, but the appropriate link entity has been disabled.

Chapter 12. HDLC Module

This chapter describes all the commands you can use to manage the entities that constitute the HDLC module. The HDLC module implements one of the protocols in the Data Link layer. The HDLC (High-level Data Link Control) protocol is intended to cover a wide range of applications. This includes one-way, two-way alternate or two-way simultaneous data communication between data stations that are usually buffered, including operations on different types of data circuits; such as, multipoint/point-to-point, duplex/half-duplex, and switched/non-switched. This implementation uses HDLC to offer reliable communication at the Data Link layer for point-to-point synchronous data lines over a wide area network link. The HDLC module typically runs as a Data Link module under the CLNS (Connectionless-Mode Network Service) network protocol.

Figure 12.1, “Hierarchy of HDLC Module Entities” shows the hierarchical relationship of the entities that constitute the HDLC module.

Figure 12.1. Hierarchy of HDLC Module Entities
Hierarchy of HDLC Module Entities

12.1. hdlc

The hdlc entity is the top-level entity in the hierarchy of entities belonging to the HDLC module.

Syntax

create [node node-id] hdlc

delete [node node-id] hdlc

show [node node-id] hdlc [all [attributes] | all characteristics]

12.1.1. Characteristic Attributes

version

Version of the HDLC architecture specification to which the implementation conforms. You cannot modify this characteristic.

12.3. hdlc link logical station

The hdlc link logical station entity controls the characteristics of an HDLC logical station. There is one station for each remote termination of a line associated with the HDLC link. The link-name is the link entity within the HDLC module and the logical-station-name refers to the logical station managed by this command.

Syntax

create [node node-id] hdlc link link-namelogical station logical-station-name

delete [node node-id] hdlc link link-namelogical station logical-station-name

disable [node node-id] hdlc link link-namelogical station logical-station-name

enable [node node-id] hdlc link link-namelogical station logical-station-name

limit [node node-id] hdlc link link-namelogical station logical-station-name

show [node node-id] hdlc link link-namelogical station logical-station-name [all [attributes] | all counters | all identifiers | all status]

unlimit [node node-id] hdlc link link-name logical station logical-station-name

12.3.1. Commands

limit

Limits station exclusively to unsequenced data service.

unlimit

Enables sequenced and unsequenced data service.

12.3.2. Counter Attributes

creation time

Time at which this entity was created.

data octets received

Total number of octets received in the I-field of I-frames and UI-frames. This total excludes protocol ID information in UI-frames and frame retransmissions.

data octets sent

Total number of octets sent in the I-field of I-frames and UI-frames. This total excludes protocol ID information in UI-frames and frame retransmissions.

data pdus received

Total number of I-frames and UID-frames received. This number does not include frames that had to be retransmitted.

data pdus sent

Total number of I-frames and UID-frames sent. This number does not include frames that had to be retransmitted.

frmrs generated

Number of FRMRs (frame rejects) sent.

frmrs received

Number of FRMRs (frame rejects) received.

invalid mode commands

Number of command frames (SABME, SABM, SNRME, SNRM, SARM, and SIM) received that are not applicable to this station.

negotiation failures

Number of times that the XID negotiation with the remote station has failed.

polls received

Number of frames received with the poll bit set.

rejs received

Number of REJ frames (rejects) received.

rejs sent

Number of REJ frames (rejects) sent.

rnrs received

Number of RNR (receive not ready) supervisory frames received from the remote station.

rnrs sent

Number of RNR (receive not ready) supervisory frames transmitted.

times acknowledge timer expired

Number of times the acknowledge timer has expired.

times station halted

Number of times the station halt event has occurred.

times station initializing

Number of times the station initialized event has occurred.

times station inoperative

Number of times the entity's status attribute state became inoperative.

times station maintenance

Number of times the entity's status attribute state became maintenance.

times station resetting

Number of times the station reset event has occurred.

times station running

Number of times the station running event has occurred.

times station setup failed

Number of times the station setup failure event has occurred.

unknown ui pdus received

Number of UI-frames the local station received whose protocol ID does not match that of any open port.

xids received

Number of XID (identification) command or response frames received.

12.3.3. Identifier Attributes

name

Simple name assigned to the logical station when it is created.

12.3.4. Status Attributes

command address

Address the local station uses when sending command frames to the remote station.

maintenance mode

Whether the station is in maintenance mode. When set to true, the station will be used exclusively for maintenance operations. When set to false, the station operates in normal fashion.

The limit command sets the value of this attribute to true, and the unlimit to false.

protocol state

State of the data link protocol.

error

A protocol error occurred. For instance, the logical station received an invalid frame.

halted

The protocol could not start. For example, there is no client.

initializing

The protocol is being initialized.

inoperative

The protocol cannot be started because no contact has been established with the remote station.

maintenance

The logical station is in maintenance mode.

resetting

The protocol is resetting after an error.

running

The protocol is running and capable of exchanging frames with the remote station.

remote version

Version number of the HDLC protocol that the remote station is using. This is received as part of an XID message from the remote station.

state

State of the logical station.

off

The logical station is off because of a disable command.

on

The logical station is on because of an enable command.

uid

Entity's unique identifier, which is generated when the entity is created.

12.4. hdlc port

The hdlc port entity represents one end of an HDLC connection. The entity maintains information about that link. Ports are created and deleted automatically when a client of HDLC uses the link. The port-name refers to the port managed by this command.

Syntax

show [node node-id] hdlc port port-name [all [attributes] | all identifiers | all status]

12.4.1. Identifier Attributes

name

Simple name assigned to the port when it is created.

12.4.2. Status Attributes

client

Name of the client using the port.

logical station

hdlc link logical station entity that the port is operating over.

protocol id

Protocol ID that the port is using. For sequenced ports, this value is decided during negotiation. For unsequenced ports, the value is sent in every UI-frame.

state

State of the port.

open

The port is assigned to a client. If the communications line is unswitched, data transfer can begin. For switched lines, an association must be made with the line before data transfer can begin.

open disabled

The port is associated with a client, but the link or logical station associated with it is disabled.

type

Type of port.

sequenced

The port can send and receive sequenced and unsequenced data.

unsequenced

The port can send and receive unsequenced data only.

Chapter 13. LAPB Module

This chapter describes all the commands you can use to manage the entities that constitute the Link Access Protocol Balanced (LAPB) module. The LAPB module implements one of the protocols in the Link layer described by the Network Architecture (NA).

Figure 13.1, “Hierarchy of LAPB Module Entities” shows the hierarchical relationship of the entities that constitute the LAPB module.

Figure 13.1. Hierarchy of LAPB Module Entities
Hierarchy of LAPB Module Entities

13.1. lapb

The lapb entity is the top-level entity in the LAPB module hierarchy of entities. The LAPB module implements the LAPB link level protocol which is a variation of the High-level Data Link Control (HDLC) link level protocol.

Syntax

create [node node-id] lapb

delete [node node-id] lapb

show [node node-id] lapb [all [attributes] | all characteristics]

13.1.1. Characteristic Attributes

version

Default: None

Version: Current version number

Version number of the NA HDLC architecture to which this implementation conforms. You cannot modify this characteristic.

13.3. lapb port

A lapb port entity represents an access point for LAPB module clients to Data Link layer services. The port-name refers to the port managed by this command.

Syntax

show [node node-id] lapb port port-name [all [attributes] | all identifiers | all status ]

13.3.1. Identifier Attributes

name

Simple name assigned to the port when it is created.

13.3.2. Status Attributes

client name

Name of the client with which the port is associated.

link

Name of the link with which the port is associated.

state

State of the lapb port entity.

open

The port is assigned to a client.

open disabled

The port is assigned to a client, but the associated link is disabled.

type

Type of port.

sequenced

The port is used for sending LAPB data.

unsequenced

The port is used for sending loopback data. This is only possible if the maintenance mode characteristic of the relevant lapb link entity is set to true.

Chapter 14. LLC2 Module

This chapter describes all the commands you can use to manage the entities that constitute the LLC2 module. The LLC2 module implements one of the protocols in the Data Link layer described by the Network Architecture (NA).

Figure 14.1, “Hierarchy of LLC2 Module Entities” shows the hierarchical relationship of the entities that constitute the LLC2 module.

Figure 14.1. Hierarchy of LLC2 Module Entities
Hierarchy of LLC2 Module Entities

14.1. llc2

The llc2 entity is the top-level entity in the LLC2 module hierarchy of entities. The LLC2 module controls the operation of the logical link control (LLC) Type 2 data link protocol for local area networks (LANs).

Syntax

create [node node-id] llc2

delete [node node-id] llc2

show [node node-id] llc2 [all [attributes] | all characteristics]

14.1.1. Characteristic Attributes

version

Version number of the NA LLC2 architecture to which this implementation conforms. You cannot modify this characteristic. To display this attribute, specify all or version.

14.2. llc2 port

An llc2 port entity represents an access point to the services offered to clients by the LLC2 module.

Syntax

show [node node-id] llc2 port simple-name [all [attributes] | all identifiers | all status]

14.2.1. Identifier Attributes

name

Simple name assigned to the port when it is created.

14.2.2. Status Attributes

client

Name of the client that opened the port.

link name

Name of the llc2 sap link entity with which this port is associated.

state

State of the llc2 port entity.

open

The port is assigned to a client and is enabled.

open disabled

The port is assigned to a client but is disabled.

14.3. llc2 sap

Each llc2 port entity has an llc2 sap (service access point) entity associated with it. An llc2 sap entity allows links to be multiplexed over its associated port.

Syntax

create [node node-id]llc2 sap sap-name

delete [node node-id] llc2 sap sap-name

disable [node node-id] llc2 sap sap-name

enable [node node-id] llc2 sap sap-name

set [node node-id] llc2 sap sap-name {lan station local-entity-name | local lsap address hex-number}

show [node node-id] llc2 sap sap-name [all [attributes] | all characteristics | all counters | all status | all identifiers]

14.3.1. Characteristic Attributes

lan station

Default: No entity name

Value: Local-entity-name

Name of the LAN station entity used by the SAP. You must specify a value for this attribute before you enable the SAP.

local lsap address

Default: 7E

Value: Hex-number

Address of the local link service access point (LSAP) to be used. The lowest significant bit of this value must be clear; that is, the address must be an individual address.

14.3.2. Counter Attributes

creation time

Time at which this entity was created.

times sap state changed

Number of times the status attribute state has changed from on to off, or from off to on.

14.3.3. Identifier Attributes

name

Simple name assigned to the llc2 sap when it is created.

14.3.4. Status Attributes

lan port

Name of the LAN port that is opened and enabled when this SAP is successfully enabled. If the SAP is not enabled, this status has a null value.

maximum pdu size

Largest frame size, in octets, that can be used to send or receive data on this SAP.

state

State of the llc2 sap entity.

off

The SAP is disabled.

on

The SAP is enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

14.3.5. Event Messages

sap state changed

Generated when the status attribute state changes from on to off, or from off to on.

Argument:

new sap state

New state of the SAP.

14.3.6. Exception Messages

For enable:

enable lan port failed

The LAN port could not be enabled.

Argument:

reason

Specifies why the enable command failed.

invalid argument

Software error.

insufficient resources

There are insufficient system resources to enable the port.

SAP address not available

The SAP address specified by the LSAP (local service access point) address characteristic is already being used, or is invalid.

link data size not supportable

The data size specified by the maximum data size characteristic of one of the sap link entities cannot be supported by the SAP.

open lan port failed

A LAN port could not be opened.

Argument:

reason

Why the port could not be opened.

invalid argument

Software error.

insufficient resources

There are insufficient system resources to open the port.

LAN station not available

The LAN station specified by the lan station characteristic is not usable.

no such LAN station

The LAN station specified by the lan station characteristic does not exist.

Chapter 15. Loopback Application Module

The Loopback Application module allows a network manager to invoke a loopback test between applications on two nodes, thus testing all the supporting layers of the Network Architecture (NA).

The Loopback Application module has two components:
  • The loop access module, which initiates the loopback test.

  • The loop mirror module, which accepts connections from the remote loop access modules and mirrors any data sent to it back to the sender.

Figure 15.1, “Hierarchy of Loopback Application Module Entities” shows the hierarchical relationship of the entities that constitute the Loopback Application module.

Figure 15.1. Hierarchy of Loopback Application Module Entities
Hierarchy of Loopback Application Module Entities

15.1. loopback application

The loopback applicationentity describes features of the Loopback Application module which allows you to run a loopback test between two nodes or itself. The loopback application entity is created and deleted automatically with the node entity, and is always enabled.

Syntax

loop [node node-id] loopback application {address tower-set | count integer | format hex-string | length integer | maximum data integer | maximum mirrors integer | name full-name}

set [node node-id] loopback application {maximum mirrors integer}

show [node node-id] loopback application [all [attributes] | all characteristics]

15.1.1. Commands

loop

Starts a loop test between the loopback applications on the specified source and destination nodes. The node keyword specifies the node from which the loop messages are sent. If you omit this keyword, the test is performed from the node on which you issue the loop command. The name or address argument specifies the node whose loop mirror is used to reflect the messages back to the originator. Specify either the name or address (but not both).

15.1.2. Characteristic Attributes

address tower-set

Number of the destination for loopback messages, in the form of a protocol tower. Specify either this argument or the name argument.

count integer

Default: 1

Value: 0–4294967295

Number of loop messages to be sent to the loop mirror. The test is complete when this number of loop messages has been reflected back by the loop mirror.

format hex-string

Default: 55

Value: 00–FF

Content of the data field of a loop message. Enter a pair of hexadecimal digits. Each octet in the data field of a loop message has this value.

length integer

Default: 40

Value: 0–65534

Length, in octets, of the data field in each loop message.

maximum data

The maximum size, in octets, of the loop message data field that the loop mirror can reflect. If the loop mirror receives a loop message with a longer data field, an error occurs.

For UNIX, to limit the number of loop mirrors, use the maximum instances characteristic of the session control application mir entity.

maximum mirrors integer

Default: 0

Value: 0–4294967295

Enter the maximum number of loop mirrors supported. If you enter the value 0, the node supports an unlimited number of mirrors.

For UNIX, to limit the number of loop mirrors, use the maximum instances characteristic of the session control application mir entity.

name full-name

DNS name of the node to which loopback messages are sent. Specify either this argument or the address argument, but not both.

15.1.3. Exception Messages

For loop:

bad data at mirror

There has been an error in the loopback protocol. The possible errors are:
  • The local node sent a loop message with a data field that was too long.

  • The first octet of the loop message was corrupted when it arrived at the mirror module.

Arguments:

count

Requested number of messages in the loopback test (that is, the value of the count argument).

message number

Number of the loop messages in which the error occurred.

start time

Time at which the loopback test began.

both name and address specified

Both the name and address arguments have been specified. You must specify one of these arguments, but not both.

connection failed

The Session Control connection to the loop mirror failed.

Arguments:

reason

Reason why the connection failed. This is the reason code provided by Session Control.

start time

Time the loopback test began.

data returned differs from data sent

The data field in a loop message reflected back by the loop mirror is not the same as the data field in the loop message that was sent.

Arguments:

count

Requested number of messages in the loopback test (that is, the value of the count argument).

format

Value for each octet of the data field of the loop message (that is, the value of the format argument).

length

Length of the data field of the loop message, as requested by the length argument.

message number

Number of the loop message in which the error occurred.

message returned

Contents of the reflected loop message.

start time

Time the loopback test began.

disconnected

The link to the loop mirror was disconnected before the loopback test was completed.

Arguments:

count

Requested number of messages in the loopback test (that is, the value of the count argument).

message number

Number of the loop message in which the error occurred.

reason

Reason why the link was disconnected. This is the reason code returned by Session Control.

start time

Time the loopback test began.

length too long

The requested length of the data field is greater than the maximum data field length that the loop mirror can handle.

Arguments:

length

Data field length requested, in octets.

maximum data

Maximum data field length supported by the loop mirror.

start time

Time at which the loopback test began.

neither name nor address specified

You have not specified the name or the address argument. You must specify one of these arguments, but not both.

Chapter 16. Modem Connect Module

This chapter describes all the commands you can use to manage the entities that constitute the Modem Connect module. The Modem Connect module implements one of the protocols in the Physical layer described by the Network Architecture (NA).

Figure 16.1, “Hierarchy of Modem Connect Module Entities” shows the hierarchical relationship of the entities that constitute the Modem Connect module.

Figure 16.1. Hierarchy of Modem Connect Module Entities
Hierarchy of Modem Connect Module Entities

16.1. modem connect

The modem connect entity is the top-level entity in the hierarchy of entities belonging to the Modem Connect module.

Syntax

create [node node-id] modem connect

delete [node node-id] modem connect

show [node node-id] modem connect [all [attributes] | all characteristics]

16.1.1. Characteristic Attributes

NA version

Version number of the NA Modem Connect architecture to which the implementation conforms. You cannot modify this characteristic.

16.2. modem connect data port

The modem connect data port entity is associated with aline and handles the transfer of data. Data ports are created and deleted automatically when a client of the Modem Connect module uses a line. The port-name refers to data port managed by this command.

Syntax

show [node node-id] modem connect data port port-name [all [attributes] | all identifiers | all status ]

16.2.1. Identifier Attributes

name

Simple name assigned to the data port when it is created.

16.2.2. Status Attributes

client

Name supplied by the client when the port was opened. This defines which client owns the port.

line

Name of the modem connect line entity that the client supplied when the port was opened.

state

State of data port.

open

The port is assigned to a client.

open disabled

The port is assigned to aclient, but the line entity that port refers to is disabled.

16.3. modem connect line

A modem connect line entity is associated with a physical circuit on the node. Usually, there is one line entity for each circuit. The line-name refers to the line managed by this command.

Syntax

add [node node-id] modem connectline line-name modem options [set]

create [node node-id] modem connectline line-name {communications mode comm-mode | communication port port-name | connection type conn-type (UNIX) | duplex full-or-half | profile profile-name | rate select rate (OpenVMS)}

delete [node node-id] modem connect line line-name

disable [node node-id] modem connectline line-name

enable [node node-id] modem connectline line-name

remove [node node-id] modem connectline line-name modem options [set]

set [node node-id] modem connectline line-name {alternate speed bits-per-second | call accept timer integer | carrier loss timer integer | clock clock-source | encoding normal-nrzi | initial hold timer integer (UNIX) | maximum call setup timer integer | maximum disable transmit timer integer | maximum dsr de-assertion timer integer | maximum enable transmit timer integer | minimum dtr de-assertion timer integer | modem control [full or none] | modem options [ modem-option] | modem protocol format type (UNIX) | modem protocol type prot-type (UNIX) | rate select [high or low] | speed bits-per-second | successful call indication timer seconds | suppress test indicator boolean | transmit holdoff timer integer}

show [node node-id] modem connect line line-name mode [all [attributes] | all characteristics | all counters | all identifiers | all status ]

startloop [node node-id] modem connectline line-name mode {driver or device | local or remote | connector or external }

stoploop [node node-id] modem connectline line-name

16.3.1. Commands

startloop

Causes a Physical layer to place the line in loopback mode.

stoploop

Opens a previously closed Physical layer loop to take it out of loopback mode.

16.3.2. Arguments

communications mode mode

Communications method used on the link. This argument determines the value of the communications mode characteristic. The default value is taken from the device capability. If that is unknown, the default is synchronous.

communications port port-name

The system device name assigned to this line.

On OpenVMS systems, the name must be in the format ddc, where dd is the OpenVMS device name prefix and c is the controller letter. For a complete list of CSMA-CD devices and their OpenVMS device names, see the DECnet-Plus for OpenVMS Release Notes.

On UNIX systems, the name must be in the format ddn, where dd is the UNIX device name prefix and n is the device number.

This argument determines the value of the communications port characteristic and is required.

duplex duplex

Specifies whether the line is full-duplex or half-duplex. This argument determines the value of the duplex characteristic. The default value is taken from the device capability. If that is unknown, the default is set to full.

mode mode

Method of startloop used on line.

connector

Data is looped through a loopback connector attached to the communications device.

device

Data is looped in the communications device.

driver

Data is looped in the driver of the communications device.

external

Data is looped through a null modem or a modem in loopback mode.

local

Communications device has switched its local modem into loopback mode.

null

Line is not in loopback mode. This argument only applies to UNIX.

remote

Communications device has switched the remote modem into loopback mode.

profile latin1string

Name of a local profile to be used with the line. This argument determines the value of the profile characteristic.

16.3.3. Characteristic Attributes

alternate speed

Default: 0

Alternate (low) speed, in bits per second, to operate the line. You can modify this characteristic only when the entity is disabled. This characteristic is supported only when the characteristic communications mode is asynchronous, the characteristic modem control is full, the characteristic modem options includes rateselect, the characteristic clock is internal, and when the alternate line speed is needed.

call accept timer

Default: 0

Minimum time, in milliseconds, between the assertion of data set ready and accepting a call by asserting request to send. This attribute is maintained only if the characteristic modem control is set to none.

carrier loss timer

Default: 15000

Maximum time, in milliseconds, that the carrier detect signal can be absent before the loss of carrier event is generated. This attribute is not supported if the characteristic modem control is set to none.

clock

Source of the transmit and receive clocks.

external

The modem provides the clock.

internal

The communications device provides the clock.

reflected

The DTE transmit clock is are flection of the DCE transmit clock. This minimizes the clock to data skew that the DCE encounters when high line speeds are used.

The default value depends on the setting of the characteristic communications mode. If communications mode is asynchronous, the default value of this characteristic is internal. Otherwise, the default value is external.

The value of this attribute has no effect when the communications line is in loopback mode. In this case, the type of loopback determines the type of clock. This characteristic can only be modified when the entity is disabled.

communications mode

Default: Synchronous

Value: Asynchronous or synchronous

Communications method to be used on the line. The value of this characteristic is a copy of the communications mode argument specified when the entity is created. You cannot modify this characteristic.

communications port

Default: None

Name of the communications port. The value of this characteristic is a copy of the communications port argument specified when the entity is created.

connection type (UNIX)

Default: Nonswitched

Value: Nonswitched or switched

Indicates whether the line is switched or nonswitched. The value of this characteristic is a copy of the connection type argument specified when the entity is created. You cannot modify this characteristic.

duplex

Default: Full

Value: Full or half

Indicates whether the line is full- or half-duplex. The value of this characteristic is a copy of the duplex argument specified when the entity is created.

encoding

Default: Normal

Value: Normal or nrzi

Encoding technique used on the line. This characteristic can only be modified when the entity is disabled.

initial hold timer (UNIX)

Default: 10

Maximum time, in seconds, that the entity waits for an incoming call to be accepted.

maximum call setup timer (UNIX)

Default: 60

Maximum time, in seconds, that the entity waits for the outgoing call to connect.

maximum disable transmit timer

Default: 500

Value: 0–60000

Maximum time, in milliseconds, that clear to send can remain asserted before the line is disconnected after request to send is de-asserted. This attribute is not supported if the characteristic modem control is set to none.

maximum dsr de-assertion timer

Default: 5000

Value: 0–60000

Maximum time, in milliseconds, the entity will wait for data set ready to be de-asserted after it has de-asserted data terminal ready. If this timer expires, the entity assumes it can assert data terminal ready once again. This attribute is not supported if the characteristic modem control is set to none.

maximum enable transmit timer

Default: 2000

Value: 1–5000

Maximum time, in milliseconds, between the assertion of the request to send signal and receiving the assertion of the clear to send signal. This attribute is not supported if the characteristic modem control is set to none.

minimum dtr de-assertion timer

Default: 1000

Value: 0–60000

Minimum time, in milliseconds, that the DTE will de-assert data terminal ready during a disconnection. This attribute is not supported if the characteristic modem control is set to none.

modem control

Default: Full

Value: Full or none

Indicates whether the interchange circuits are to be monitored and used. The value none means that only the data leads are monitored.

The value full must be used when the value of the characteristic duplex is half. This characteristic is supported only if the characteristic connection type is switched.

modem options

Default: No options

Value: Set of options

Set of values that determine the capabilities of the modem.

dialout

The modem can dial the remote modem. Supported only if the value of communications type is switched. This value is supported by UNIX only.

direct

The modem is directly connected to the remote modem through a nonswitched line. Supported only if accompanied with dialout and used only when the modem protocol type supports direct dial. This value is supported by UNIX only.

rate select

The modem is capable of data rate selection.

modem protocol format (UNIX)

Default: See description

Value: See description

Format to use for V.25bis protocol messages. This characteristic applies only when the characteristic modem protocol type is v25bis or dmcl.

asynchronous

Use the asynchronous format.

hdlc

Use the HDLC format.

synchronous

Use the synchronous format.

The default value depends on the value of the characteristic communications mode. If communications mode is asynchronous, the default value of this characteristic is also asynchronous. If the value of communications mode is synchronous, the default value of this characteristic is hdlc.

modem protocol type (UNIX)

Default: V25bis

Value: See description

Protocol that the modem uses to select modem options and to set line control parameters.

at

A set of automatic calling procedures used in the Hayes Smart Modem 2400.

dmcl

The Modem Control Language, based on V.25bis.

v25

A set of automatic calling and answering procedures defined by CCITT. These procedures use the 200-series circuits defined in the CCITT recommendation V.24. The V.25 procedures are also known as parallel automatic calling procedures.

v25bis

A set of automatic calling and answering procedures defined by CCITT. These procedures use the 100-series circuits defined in the CCITT recommendation V.24. The V.25bis procedures are also known as serial automatic calling procedures.

profile

Default: None

Name of the local profile to be used with the line. This profile is used to restrict the range of various line attributes, and to change the defaults for those attributes. The value of this characteristic is a copy of the profile argument specified when the entity is created.

rate select

Default: High

Value: High or low

Specifies which of the line rates is to be used if none is specified when a call is set up.

high

The value of the speed characteristic is used.

low

The value of the alternate speed characteristic is used.

This characteristic is supported only if the characteristic modem control is full, and if the characteristic modem options includes rateselect.

speed

Default: 0

High speed, in bits per second, to be used on the line. This value is always used on asynchronous links. It is used on synchronous links only in the following circumstances:
  • When the value of the clock characteristic is internal.

  • When a null modem cable is detected.

  • When using a loopback mode that uses internal clocking.

successful call indication timer

Default: 30

Maximum time, in seconds, that the entity will wait for indication of a successful call before disconnecting the line. This attribute is not supported if the characteristic modem control is set to none.

suppress test indicator

Default: False

Value: True or false

Specifies whether the test mode signal is to be monitored. If the value is false, a change in the circuit will be monitored and will cause a Test Indication event to be generated.

You should set this characteristic to true in cases where the transitions of this signal are not produced by entering the test mode, so that this signal should be ignored.

transmit holdoff timer

Default: 0

Necessary delay, in milliseconds, between the transmitter being disabled and then reenabled. The value 0 means that the request to send signal can be asserted as soon as the client requests it. This attribute is not supported if the characteristic modem control is set to none.

16.3.4. Counter Attributes

cable faults

Total number of times the communications cable was detected as missing or invalid.

creation time

Time at which this entity was created.

device errors

Total number of times a potential device error has been reported.

framing errors

Total number of framing errors detected on the line. This counter is not supported if the characteristic communications mode is synchronous.

losses of carrier

Total number of times the carrier on the line was lost. This attribute is not supported if the characteristic modem control is set to none.

losses of clock

Total number of times the transmit or receive clock was lost.

outgoing call failures (UNIX)

Total number of times an outgoing call failed to connect.

rate fallbacks

Number of times the DTE changed from the high data rate to the low (alternate) rate. This counter is supported only if the characteristic modem options includes rate select, and if the characteristic modem control is full.

test indications

Number of times the DCE was put into test mode by the remote system. This attribute is not supported if the characteristic modem control is set to none.

times cable detected

Total number of times a valid communications cable was detected following a an error counted by the counter cable faults.

times dce not ready

Total number of times a dce not ready event occurred. This attribute is not supported if the characteristic modem control is set to none.

times reset (OpenVMS)

Number of times the data link client has performed a line reset.

transmit enable timeouts

Number of times the DCE failed to assert clear to send in response to request to send. This attribute is not supported if the characteristic modem control is set to none.

16.3.5. Identifier Attributes

name

Simple name assigned to the line when it is created.

16.3.6. Status Attributes

actual speed

Actual speed of the line, in bits per second. For internal clocking on some microcoded devices, a value of 0 indicates that the device has selected a speed appropriate for the connected interface. For external clocking, a value of 0 indicates that the speed is unknown.

device availability (OpenVMS)

Indicates whether the hardware device associated with the named communications port is installed. Support is mandatory on systems that support line card hot swap. When device availability has the value no device, the interface state takes the value pending DTE Ready and the interface type attribute takes the value unknown.

interface state

State of the physical interface on the line.

connected

A switched line is connected but not ready to transmit or receive data.

connecting

Call setup on a switched line is in progress.

disconnecting

Call clear on a switched line is in progress.

dte not ready

The entity is disabled.

dte ready

The DTE is ready, but the DCE is not ready.

full enabled

The line is enabled for data transmission and reception.

pending dte ready

The entity is enabled but the ready state cannot be entered. For example, the communications cable is not connected.

ready

Both DTE and DCE are ready.

receive enabled

The line is ready to receive data.

transmit enabled

The line is ready for data transmission.

interface type

Type of the physical interface connection.

loopback

A loopback connector has been detected onthe interface.

no cable

No cable is connected to the interface.

null modem

A null modem cable is connected to the interface.

rs232c

A cable conforming to the RS-232-C standard is attached.

rs422

A cable conforming to the RS-422 standard is attached.

rs423-v24

This value appears where a cable is attached but the connector cannot distinguish between the RS-423 and V.24 standards.

rs449

A cable conforming to the RS-449 standard is attached.

unknown

A cable is attached but its type is not known

v28

A cable conforming to any of the CCITTV.24, V.28 standards, the IS 2110 standard, or the EIA-232-D standard.

v35

A cable conforming to the V.35 standard is attached.

x21

A cable conforming to the X.21 standard is attached.

loopback mode

Type of loopback in use on the line. The value of this status attribute is determined by the startloop and stoploop commands.

connector

Data is looped through a loopback connector attached to the communications device.

device

Data is looped in the communications device.

driver

Data is looped in the driver of the communications device.

external

Data is looped through a null modem or a modem in loopback mode.

local

The communications device has switched its local modem into loopback mode.

null

The line is not in loopback mode.

remote

The communications device has switched the remote modem into loopback mode.

modem type

String identifying the local modem. If this status attribute has no value, the type could not be determined.

state

Specifies the status of the modem connect line entity.

off

The line has been disabled.

on

The line has been enabled.

uid

Entity's unique identifier, which is generated when the entity is created.

16.3.7. Interchange Circuit Attributes

The modem connect line entity in the Modem Connect module has an extra set of status attributes that let you examine the instantaneous status of the interchange circuits on the line.

These circuit attributes are known by different names in the various interface standards. Table 16.1, “Modem Connect Line Interchange Circuits” shows how the attribute names used in NCL correspond to those used in the interface standards. For instance, the data terminal ready attribute is the name used for the CCITT V.24 circuit 108/2, the EIA-232-D CD circuit, the RS-499 TR circuit, and so on.

When entering commands, always use the NCL attribute name. When displayed, each attribute has one of the following values:

asserted

The circuit is asserted.

not applicable

The circuit does not exist on the interface.

not asserted

The circuit is not asserted.

unknown

The modem cable is not connected or is invalid.

Table 16.1. Modem Connect Line Interchange Circuits

NCL Attribute Name

Circuit

Description

CCITT V.24

carrier detect

109

Data channel received line signal detector

clear to send

106

Ready for sending

data set ready

107

Data set ready

data terminal ready

108/2

Data terminal ready

local loopback

141

Local loopback

remote loopback

140

Loopback/maintenance test

request to send

105

Request to send

ring indicator

125

Calling indicator

signaling rate indicator

112

Data signal rate selector (DCE)

signaling rate selector

111

Data signal rate selector (DTE)

test mode

142

Test indicator

DIN 66020 Blatt 1

carrier detect

M5

clear to send

M2

data set ready

M1

data terminal ready

S1.2

local loopback

PS3

remote loopback

PS2

request to send

S2

ring indicator

M3

signaling rate indicator

Not supported

signaling rate selector

S4

test mode

PM1

EIA-232-D

carrier detect

CF

Received line signal detector

clear to send

CB

Clear to send

data set ready

CC

DCE ready

data terminal ready

CD

DTE ready

local loopback

LL

Local loopback

remote loopback

RL

Remote loopback

request to send

CA

Request to send

ring indicator

CE

Ring indicator

signaling rate indicator

CI

Data signal rate selector (DCE)

signaling rate selector

CH

Data signal rate selector (DTE)

test mode

TM

Test mode

RS-232-C

carrier detect

Received line signal detector

clear to send

Clear to send

data set ready

Data set ready

data terminal ready

Data terminal ready

local loopback

Not supported

remote loopback

Not supported

request to send

Request to send

ring indicator

Ring indicator

signaling rate indicator

Data signal rate selector (DCE)

signaling rate selector

Data signal rate selector (DTE)

test mode

not supported

RS-449

carrier detect

RR

Receiver ready

clear to send

CS

Clear to send

data set ready

DM

Data mode

data terminal ready

TR

Terminal ready

local loopback

LL

Local loopback

remote loopback

RL

Remote loopback

request to send

RS

Request to send

ring indicator

IC

Incoming call

signaling rate indicator

SI

Signaling rate indicator

signaling rate selector

SR

Signaling rate selector

test mode

TM

Test mode

16.3.8. Event Messages

cable detected

Generated when a valid communication cable is detected following a cable fault event.

Arguments:

current interface type

Type of cable detected.

loopback

A loopback connector has been detected.

null modem

A null modem has been detected.

rs232c

A cable conforming to the RS-232-C standard has been detected.

rs449

A cable conforming to the RS-449 standard has been detected.

rs422

A cable conforming to the RS-422 standard has been detected.

rs423-v24

A cable is attached, but the connector cannot distinguish whether it conforms to RS-423 or V.24 standards.

v.28

A cable conforming to any of the CCITTV.24, CCITT V.28, IS2110, or EIA-232-D standards has been detected.

v.35

A cable conforming to the V.35 standard has been detected.

x.21

A cable conforming to the X.21 standard has been detected.

previous interfacetype

Previous type of cable detected.

no cable

No cable was attached to the interface.

unknown

A cable was attached, but its type was unknown.

cable fault

Generated each time the communications cable is detected as missing or invalid.

Arguments: The call reference argument is present only if the characteristic connection type is switched.

call reference

The call reference number of the call that was disconnected because of the fault.

previous interface type

Type of cable that was connected before the error was detected.

loopback

A loopback connector.

null modem

A null modem cable.

rs232c

A cable conforming to the RS-232-Cstandard.

rs422

A cable conforming to the RS-422 standard.

rs423-v24

A cable is attached, but the connector cannot distinguish whether it conforms to RS-423 or V.24 standards.

rs449

A cable conforming to the RS-449 standard.

unknown

A cable was connected but its type was unknown.

v.28

A cable conforming to any of the CCITT V.24, CCITT V.28, IS2110, or EIA-232-D standards.

v.35

A cable conforming to the V.35 standard.

x.21

A cable conforming to the X.21 standard.

reason

Reason that caused the event to occur.

invalid cable

A cable is attached but it is not one of those recognized.

no cable

No cable can be detected.

clock loss

Generated each time a loss of the transmit or receive clock is detected. Once this event occurs, the value of the interface state attribute changes to pending dte ready.

dce not ready

Generated each time a dce not ready condition is detected. Once this event occurs, the value of the interface state attribute changes to dte ready. This event does not occur if the characteristic modem control is set to none.

device error

A potential device error has been detected. This may be a temporary condition that means the device can continue to be used.

Argument:

reason

Reason for the failure. This is device specific.

framing error

Generated each time an asynchronous framing error occurs.

loss of carrier

Generated each time the carrier frequency is lost while receiving data. This event is not supported if the characteristic modem control is none.

rate fallback

Generated each time the DCE indicates that it is changing from the high data rate (as indicated by the speed characteristic) to the low data rate (as indicated by the alternate speed characteristic. This can occur if there is excessive noise when operating at the high data rate. This event is supported only when the modem has a rate selection capability.

reset (OpenVMS)

Generated each time the Data Link client represents a line reset by means of the service interface.

test indication

Generated each time the remote system tests the DCE. When this event occurs, the value of the interface state attribute changes to