INTERR - RSX DECnet Management Interrogator  INTERR RSX-11M/M-Plus Task for DECnet Management July 1983 Bruce R. Mitchell Machine Intelligence and Industrial Magic PO Box 601 Hudson, WI 54016 18 July, 1983 INTERR - RSX DECnet Management Interrogator  INTERR - RSX DECnet Management Interrogator Table of Contents 1.0 Introduction 2.0 The Typical Corporate DECnet Network 2.1 Scope 2.2 Introduction 2.3 General Configuration 3.0 Network Management, NCP and NICE/NML 3.1 Scope 3.2 Introduction 3.3 NCP 3.4 NICE/NML 4.0 Network Configuration and INTERR 4.1 Scope 4.2 Invoking the Program 4.3 Command Structure 5.0 Structure and Operation of the INTERR Program 5.1 Introduction 5.2 General Structure 5.2.1 Data 5.2.2 Code 5.2.2.1 Mainline 5.2.2.2 Subroutines 5.2.2.3 System Routines 6.0 Building and Installation 6.1 Introduction 6.2 Distribution Kit 6.3 Build Procedure 6.4 Comments 7.0 INTERR Error Messages 7.1 Introduction 7.2 Fatal Error Messages 7.3 Informational Messages 8.0 Caveats 8.1 Introduction 8.2 Limitations INTERR - RSX DECnet Management Interrogator Table of Contents 8.3 Disclaimer INTERR - RSX DECnet Management Interrogator Table of Contents  INTERR - RSX DECnet Management Interrogator Abstract Abstract ________ A program which runs under the Digital Equipment Corporation RSX-11M/M-Plus operating system for PDP-11 computers is described. The function of the program is to facilitate startup of DECnet computer networking software on the host machine. This is done by interrogating the NICE/NML network management program on a network "master" node about the configuration of the network. Structure, installation and use of the program are discussed. Keywords: Communication, computer control, computer networking, computer programs, computer software, Digital Equipment Corporation, DEC, DECnet, PDP-11, RSX-11. This work was performed by the author as part of an ongoing effort to support and encourage the use of DECnet computer networking. INTERR - RSX DECnet Management Interrogator Introduction 1.0 Introduction Users of Digital Equipment Corporation ("DEC") PDP-11 computers are fortunate in that they have access to what is probably the most sophisticated computer networking software in the world. Digital's DECnet is a comprehensive communications system in both hardware and software. It is well designed, easy to install, simple to use, and user friendly. Through the approprate application of DECnet, DEC computers can pass programs and information back and forth as desired. The "virtual terminal" facility of DECnet makes it possible to log in to another computer via the network and operate as though one were actually connected to the remote "host" computer. Various other levels of service are available to the user depending on the user's sophistication. Because of DECnet's popularity, in many companies, a growing network of moderate to large-scale computers has emerged over the past five years. This network (the "corporate network") usually contains on the order of 50 interlinked computers ("nodes"). An emerging problem in management of such a network is that when a new node enters the network, its unique identification (node number and up to 6 character node name) must be made known permanently throughout the entire network. In the past, this has usually been done by simply asking the managers of each node to INTERR - RSX DECnet Management Interrogator Page 2 Introduction update their node information assignment files. This might have been acceptable when a network was on the size order of 10 to 20 nodes, but the situation rapidly grows out of control with expansion of the network. With a network of 200 or more nodes, often foreseen in the next 10 years, it will be quite impossible to reliably contact all the node managers to do anything, much less update all their network routing data bases simultaneously. The only possible solution to this problem is to use the network itself to dynamically update the network configuration information. If the necessary information is stored on a master node and loaded into each machine at the time the networking software is started, each node will have the most current information on the configuration of the network as long as the machines are restarted relatively frequently - a safe assumption, since periodic maintenance is required on computers. This document describes the "INTERR" network configuration information control program developed by MIIM which dynamically loads the current network configuration from a master node. The program is written for DEC PDP-11 computers running under the RSX-11 operating system. INTERR - RSX DECnet Management Interrogator Page 3 Introduction NOTE The author does not guarantee the usability of this software on other than a DEC computer under the RSX operating system. INTERR - RSX DECnet Management Interrogator Page 4 The Typical Corporate DECnet Network 2.0 The Typical Corporate DECnet Network 2.1 Scope This section presents a brief overview and description of a typical corporate DECnet DEC computer network for those who may not be familiar with networking. 2.2 Introduction A typical corporate DEC computer network is a heterogeneous group of Digital computers or "nodes" which are geographically distributed across the United States. These computers are electrically connected together and communicate with each other via DECnet DDCMP (Digital Data Communications Message Protocol) information links. Most of the computers in the corporate network are medium to large scale minicomputers and superminicomputers. The size range is from small PDP-11/23 systems to VAX-11/780 systems up to DECsystem 2020s. Each has a particular reason for being connected to the network, and those reasons are as varied as the machines themselves. Some machines collect process data and send it elsewhere for data analysis; some machines are database servers to other INTERR - RSX DECnet Management Interrogator Page 5 The Typical Corporate DECnet Network machines; some are connected for convenience in debugging and communicating to other nodes in the network. It is a varied group of machines which supports an equally varied group of users. 2.3 General Configuration The corporate network is not formally structured. In one sense, it may be considered a star network, because (usually) the corporate headquarters is the hub to which all outlying plants connect. In other cases, it may be considered a ring or loop network, because several rings often exist among computers in various areas for reasons of reliability. Taken as a whole, however, its structure is indeterminate - and constantly in a state of flux. While the network is constantly changing configuration, there is often a nexus of machines in the corporate headquarters which are always expected to be available. Quite often, one of these machines is expected to be up 24 hours a day, 365 days a year. It thus is an ideal choice for a network "master" node, usually having a well-known address and redundant communication links to the network. INTERR - RSX DECnet Management Interrogator Page 6 Network Management, NCP and NICE/NML 3.0 Network Management, NCP and NICE/NML 3.1 Scope This section covers some of the basics of network management as it relates to NCP, the Network Control Program, and NICE/NML, the Network Information and Control Executor / Network Management Listener. 3.2 Introduction Configuration and management of configuration of a DECnet falls into two classes. These classes are static configuration and dynamic configuration. Static configuration covers such items as the local node name and number, the maximum node address within the network, and the names and node numbers of other nodes within the network. Dynamic configuration covers such items as whether a node is currently reachable and the best way to reach it. In general, dynamic configuration of a DECnet is handled by the network software itself. When a node enters the network, routing information is updated automatically to reflect this; similarly, when a node leaves the network, it is removed from the list of active nodes. Lines going up and going down are also handled automatically, and routing is adjusted according to which INTERR - RSX DECnet Management Interrogator Page 7 Network Management, NCP and NICE/NML lines are currently available. Static configuration of a DECnet is done by the node managers through SYSgen and startup command files. This type of configuration includes line costs, node names and addresses, the maximum node number for the network, and static network subpartitioning. It is in this class of network configuration that we are interested. 3.3 NCP NCP, the Network Control Program, is used on RSX-11M nodes to control dynamic configuration of the network as seen by the local node. NCP is capable of setting a number of parameters on the local node, including the names and numbers of remote nodes in the network. It is this capability in which we are most interested. NCP is usually invoked at the time the network is started on the local node to make the node names and addresses for the network known to local users of the network. This is usually done through a command file containing commands of the form: NCP SET NODE (number) NAME (name) where the node number can be any number from 1 to 255, and the name can be any string of 6 alphanumeric characters. INTERR - RSX DECnet Management Interrogator Page 8 Network Management, NCP and NICE/NML (When NCP is given a command, it opens a logical link to NICE/NML on the local node and passes NICE/NML a command packet stating what should be done. More on this later.) This NCP command file must be present on all nodes in the network and must be current. If it is not present, the node will recognize that other nodes are present in the network but will know them only by node number, not by name. An additional problem in this case is that the NTDEMO program will only show the host node. On the other hand, if the NODASSIGN file is incorrect, nodes may be assigned the wrong names or wrong numbers, causing programs to connect to the wrong nodes with potentially dangerous results. Neither of the above situations is acceptable, but it is more and more difficult to make sure that all copies of the node assignment file are current. There is, however, another solution. 3.4 NICE/NML DECnet nodes often interrogate each other for information about the configuation of the network on other nodes. This information is obtained through NICE/NML, the Network Information and Control Executor / Network Management Listener. This is a INTERR - RSX DECnet Management Interrogator Page 9 Network Management, NCP and NICE/NML remote "object" with a well-known "address" to which NCP can connect to obtain information on the state of a remote node. NICE/NML can provide information on nodes known to its own host node, nodes that are active and visible to its host node, or on various other types of network parameters. It can also be used to set network parameters on its host node; this is done through either the local node's NCP program or a remote node's NCP program, given that the remote node NCP has sufficient network privilege. The information server capability of NICE/NML is of use in network configuration. The INTERR program connects to NICE/NML on a network "master" node and interrogates its' NICE/NML for information on known nodes. Given this information, INTERR can configure its own node, as will be seen in the section which covers structure and operation of the program. INTERR - RSX DECnet Management Interrogator Page 10 Network Configuration and INTERR 4.0 Network Configuration and INTERR 4.1 Scope This section covers operation of the INTERR program on an RSX-11M or RSX-11M-Plus system. 4.2 Invoking the Program INTERR may be invoked, or run, in a variety of ways. The proper way to invoke the program depends on three things. In relative order of importance, these are: 1. Whether the host system is started by a command file. 2. Whether INTERR is installed in the system. 3. Where the INTERR.TSK task file resides. 4. Whether the user is privileged. If the host system is started by a command file, it is possible to have the command file do all necessary operations to run the INTERR task. In this case, no further consideration is necessary. If the host system is not started by a command file, but INTERR is installed in the system, what is required is (1) the NETNML alias be defined for the node which will provide NICE/NML service, (2) type "RUN INTERR" on the host terminal after DECnet INTERR - RSX DECnet Management Interrogator Page 11 Network Configuration and INTERR is started on the host. INTERR will be called in for the user. If INTERR is not installed, it is not possible for an unprivileged user to run the program. In this case, the invoking command line for a privileged user becomes: RUN ddnn:[ggg,nnn]INTERR, where ddnn:[ggg,nnn] is the device name and UFD where the INTERR.TSK image resides. Again, INTERR must be run after DECnet has been started on the host and the NETNML alias must be set up previous to invocation. For more information, see your system manager and/or node manager. 4.3 Command Structure INTERR has no command parsing or command structure. INTERR - RSX DECnet Management Interrogator Page 12 Structure of the INTERR Program 5.0 Structure and Operation of the INTERR Program 5.1 Introduction This section presents a very general overview of the internal structure and the method of internal operation of the INTERR program. 5.2 General Structure INTERR is written in DEC Macro-11 assembly language. It is approximately 1500 lines of source code, including the conditional debugging support routines. No exotic programming tricks are used in the code. Wherever possible, available system routines are used to perform functions. 5.2.1 Data - The data sections of INTERR are contained in RW D-PSECT INDATA. These sections contain directive parameter blocks for system and network calls, message strings for output to the host terminal and to the system console, buffer areas for data storage, debugging messages for output to the host terminal, and variables for use within the program. Each section of differing data is contained within a .SBTTL INTERR - RSX DECnet Management Interrogator Page 13 Structure of the INTERR Program stating the function of the data following the .SBTTL. Because the data has been separated out into a D-PSECT, it is possible to build INTERR as an I and D space task under RSX-11M-Plus. Note, however, that there is little advantage in this and therefore the INTGEN command file does not allow this as an option. 5.2.2 Code - The code sections of INTERR are contained in RO I-PSECT INCODE. These sections open the network, do network I/O to NICE/NML on the remote node, store data and retrieve it, spawn command lines to the MCR... CLI, and print messages on the invoking terminal and on the system console. Each section of code is divided by functionality into .SBTTL sections. Each .SBTTL states the function of the code following it. Because the code has been separated out into an I-PSECT, it is possible to build INTERR as an I and D space task under RSX-11M-Plus. Note, however, that there is little advantage in this and therefore the INTGEN command file does not allow this as an option. The code is functionally divisible into two parts; the INTERR - RSX DECnet Management Interrogator Page 14 Structure of the INTERR Program mainline and subroutines. 5.2.2.1 Mainline - The mainline code assigns logical unit numbers (LUNs) to the network, the invoking terminal, and the system console. It then attempts to open the network. If unsuccessful, an error message is printed on the invoking terminal and an exit with error status is made. Once the network is open, the program attempts to connect by object number to NICE/NML on the network management node, NETNML. If the connect fails, an error message is printed on the invoking terminal and an exit with error status is made. A successful connect to the remote object does not necessarily mean that what is connected to is NICE/NML. A check is made for correct version number data in the connect block. If the version number data is incorrect, an error message is printed on the invoking terminal and an exit with error status is made. At this point in the program it is known that the remote object is indeed NICE/NML. The program now sends an enquiry message to NICE/NML asking it for names and numbers of all known nodes in its database. NICE/NML responds with a packet stating either failure or success with more data following. If a failure code is returned, an error message and optional error text from INTERR - RSX DECnet Management Interrogator Page 15 Structure of the INTERR Program NICE/NML is printed on the invoking terminal and an exit with error status is made. The program now enters a continuous loop, issuing receive requests and processing the received data from NICE/NML. The sequence of events in this loop proceeds as follows: Attempt to receive a message from NICE/NML. On a gross failure, print an error message and exit with error status. Otherwise, test the returned data for the last packet flag; if it is found, exit the loop. The sending node always returns information on itself first; if this is the remote executor node, ignore it and try again. Likewise, it is not necessary to have information on the local node; if the returned data is for the local node, ignore it and try again. Otherwise, store the data in a data block area and go try for more data. When the last packet is received, the program closes the network. It then enters another loop; inside this loop it sets the node names and numbers received from the remote node. The procedure here is as follows: A command line to NCP is built from the node name and number. The command line is of the form "NCP SET NODE xxxxx NAME nnnnnn", where xxxxx is the node number, zero-filled, and nnnnnn INTERR - RSX DECnet Management Interrogator Page 16 Structure of the INTERR Program is the node name. This command line is then spawned to the MCR... command line interpreter and optionally "pseudo-echo" printed on the invoking terminal. If the spawn fails, the program prints an error message and exits with error status. otherwise, the program waits for the spawned command to complete and loops for another node name and number. Eventually, the program finishes spawning command lines and exits the above loop. It now logs a message on the console terminal stating that it successfully set the node names for the network. Finally, it exits to RSX with success status. 5.2.2.2 Subroutines - The two subroutines within INTERR are called only on the occurrence of a fatal error. ERREXT prints a message on the invoking terminal stating an I/O or FCS error and the contents of the Directive Status Word ($DSW). NMLEXT prints a message on the invoking terminal stating a network error code and the contents of an optional text error returned by remote NICE/NML. 5.2.2.3 System Routines - A number of system routines and functions are used to perform various functions within INTERR. In particular, the network routines are used to open, close and obtain data from the INTERR - RSX DECnet Management Interrogator Page 17 Structure of the INTERR Program network, and and the CBTA family of routines are used to convert binary data into ASCII strings. INTERR - RSX DECnet Management Interrogator Page 18 Building and Installation 6.0 Building and Installation 6.1 Introduction This section covers building and installation of INTERR, starting with the distribution kit and ending with a runnable task image. 6.2 Distribution Kit The INTERR distribution kit can be provided on a number of different media, but is small enough to fit on a single density floppy disk or a short magnetic tape. The INTERR distribution kit contains the following files in RSX Files-11 (ODS Level I) format: 1. INTERR.MAC - Macro source file for task 2. INTERR.RNO - Runoff source file for this document 3. INTERR.DOC - This document in printable form 4. INTGEN.CMD - Generation command file 5. README.1ST - General description and instructions 6. README.RNO - Runoff source file for README.1ST 6.3 Build Procedure INTERR - RSX DECnet Management Interrogator Page 19 Building and Installation The build procedure for INTERR is as follows: 1. Log on to the target system in a privileged account. 2. Copy all files on the distribution kit into a (preferably) empty UFD. If you adhere to RSX SIG standards, place the distribution kit in a [300,*] UFD. PIP ddnn:[ggg,nnn]/CD=eenn:[hhh,ooo]*.* where ddnn: is the target device, [ggg,nnn] is the target UFD, eenn: is the source device, and [hhh,ooo] is the source UFD. 3. Verify that the macro assembler (...MAC) and the Taskbuilder (...TKB) are installed. 4. Verify that the network macro library file NETMAC.MLB is present in UFD [1,1] on the target system LB: device. 5. Change UIC and device to the UFD containing the distribution kit. SET /UIC=[ggg,nnn] ASN ddnn:=SY: 6. Invoke the indirect command file processor on the build command file, INTGEN.CMD. @INTGEN 7. Wait for the command file to complete execution. 8. Change UIC and device to the network task UFD on LB: SET /UIC=[ggg,54] ASN LB:=SY: 9. Copy the INTERR.TSK file into this UFD. PIP /CD=ddnn:[ggg,nnn]INTERR.TSK 10. Install the task, if necessary. (This is not necessary for a command file started network.) INSTALL LB:[ggg,54]INTERR This completes the build and installation procedure for INTERR. INTERR - RSX DECnet Management Interrogator Page 20 Building and Installation 6.4 Comments INTERR.MAC assembles into an object file occupying about 14 disk blocks. When INTERR is built under RSX-11M-Plus against an FCSFSL resident library, the task image occupies about 12 disk blocks. When it is built without a resident library, it also occupies about 12 disk blocks; there is no advantage in building INTERR against an FCS resident library, because it uses no FCS routines. An RSX-11M version builds to approximately the same sizes with or without FCSRES resident libraries. If INTERR is built with debugging support (D$$BUG is defined in the prefix file INTERPRE.MAC during INTGEN), the object and task files will be larger. INTERR - RSX DECnet Management Interrogator Page 21 INTERR Error Messages 7.0 INTERR Error Messages 7.1 Introduction Error messages may be returned by the INTERR program for a number of reasons; however, the occurrence of any error message indicates a fatal error. These fatal error messages are caused by the occurrence of problems which are severe enough to cause the program to immediately stop execution and return to command level. This class of message is always of the form: INT-F-xxx, where INT indicates the task name, F indicates a fatal error, xxx is the 3-letter mnemonic for the error, and is a short explanation of what caused the error. An additional class of messages exist which the everyday user should normally never see. These are debugging messages, intended for use only when the program is under development and being debugged. Debugging messages are produced solely for the programmer's information. This class of message is always of the form: INT-D-xxx, The appearance of a debugging message should be ignored by the INTERR - RSX DECnet Management Interrogator Page 22 INTERR Error Messages user, but brought to the attention of either the system manager or the program's maintainer. 7.2 Fatal Error Messages INT-F-NOF, Network open failed This message occurs when the program is unable to open a link to DECnet on the local node. The probable cause is that DECnet is not running. INT-F-NCF, Network connect to NETNML failed This error is caused by a failure to establish a logical link to the network management node, the alias of which is NETNML. Probable cause: NETNML is not defined as an alias. INT-F-ROU, NICE/NML not installed on remote node This error is caused by a failure to connect to the Network Management Listener on the NETNML node. Probable cause: NICE/NML is not installed on the remote node, or the NML object is not defined at the remote node. INT-F-WND, Incorrect or no NICE/NML connect data returned The INTERR program connected to what was apparently NICE/NML on the NETNML node, but did not receive the correct status data back in the first message from NICE/NML. This error may be caused by a different task installed as the NML object or by connecting to a Phase II node. INT-F-UND, Unexpected NICE/NML error during data reception The program was in a normal data receive state, but NICE/NML unexpectedly returned an error code rather than a data packet. Possible cause: Fatal corruption of the network on either host node or NETNML. INT-F-NEF, NICE/NML enquiry send failed An attempt was made to send the enquiry packet to INTERR - RSX DECnet Management Interrogator Page 23 INTERR Error Messages remote NICE/NML, but for some reason it failed. Possible reasons for failure include a catastrophic failure of the network and a temporary link failure between the host and NETNML. INT-F-NRF, NICE/NML response failed The header packet before transmission of node data was expected from remote NICE/NML, but the receive failed for some reason. INT-F-NRE, NICE/NML rejected enquiry NICE/NML on the remote node refused the information request from INTERR. Possible causes include insufficient network or remote system privilege, or an incorrect data format in the request block. INT-F-NSF, Spawn NCP command to MCR... failed It was not possible to spawn the NCP SET etc. command to the MCR... command line interpreter. Possible causes include a fatal corruption of the host system. 7.3 Informational Messages Return code = xxx, Error detail = yyy " optional text " This error message is always found in conjunction with a previous fatal network error message. It prints the network error code and error code detail. If any optional text error message was present, that is printed underneath the first lines. I/O error code = xxx, $DSW = yyy This message is always found in conjunction with a previous fatal error message. It prints the FCS or I/O error code and the contents of the directive status word for informational and debugging purposes. INTERR - RSX DECnet Management Interrogator Page 24 Caveats 8.0 Caveats 8.1 Introduction This section deals with limitations, shortcomings and peculiarities of the INTERR task which should be known by users of the task. 8.2 Limitations The Network Control Program, ...NCP, must be installed on the host system. An alias, NMLNOD, for the network master node must be set up on the host system before INTERR is run. The Network Information and Control Executor / Network Management Listener, NICE/NML, must be installed on the network master node, NMLNOD. In addition, NICE/NML must be known as object type 19 on NMLNOD. 8.3 Disclaimer The author does not recommend or guarantee use of this software on other than a DEC computer under the RSX operating system. This software assembles, taskbuilds and runs correctly under INTERR - RSX DECnet Management Interrogator Page 25 Caveats the Autopatch A version of RSX-11M-Plus Versions 2.0 and 2.1, and the Autopatch B version of RSX-11M Version 4. It should also build and run correctly under other versions of RSX, but has not been tested under other versions of RSX and therefore is not guaranteed to run under other versions of RSX. Because this work was done by the author on personal time, without company funding, Machine Intelligence and Industrial Magic will not be held responsible for ongoing support of this program or for difficulties encountered with it. Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Building and Installation . . . . . . . . . . . . . . . . . 18 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . 24 INTERR Error Messages . . . . . . . . . . . . . . . . . . . 21 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 Network Configuration and INTERR . . . . . . . . . . . . . . 10 Network Management, NCP, and NICE/NML . . . . . . . . . . . 6 Structure and Operation of the INTERR Program . . . . . . . 12 The Typical Corporate DECnet Network . . . . . . . . . . . . 4