DECnet/OSI_for_OpenVMS________________________ Release Notes August 1995 _______________Documentation Comments _______________ If you have comments or suggestions for this book or any of the DECnet/OSI documents, mail your comments to the following address: DECnet/OSI Documentation Group 550 King St. (LKG2-2/Q5) Littleton, MA 01460 If you have access to the Internet, mail your comments electronically to the following address: doc_quality@lkg.mts.dec.com _____________________________________________________ Revision/Update Information: This is a new manual. Operating System: OpenVMS Alpha and VAX Version 6.1 Software Version: DECnet/OSI Version 6.3 for OpenVMS August 1995 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. © Digital Equipment Corporation 1995 All Rights Reserved The following are trademarks of Digital Equipment Corporation: ACMS, DECdtm, DEC WANrouter, DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DECwindows, DNA, OpenVMS, ULTRIX, VAX, VAXstation, VMS, VMScluster, and the DIGITAL logo. The following are third-party trademarks: Macintosh is a registered trademark of Apple Computer, Inc. MS-DOS is a registered trademark of Microsoft Corporation. OS/2 is a registered trademark of International Business Machines Corporation. OSF/1 is a registered trademark of Open Software Foundation, Inc. SCO is a trademark of Santa Cruz Operations, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd. TCPware is a registered trademark of Process Software Corporation. MultiNet is a registered trademark of TGV, Inc. PATHways is a registered trademark of The Wollongong Group. OSI is a registered trademark of CA Management, Inc. All other trademarks and registered trademarks are the property of their respecitive holders. ________________________________________________________________ Contents 1 General Information 1.1 New Features for DECnet/OSI for OpenVMS...... 1-1 1.2 Upgrading from DECnet/OSI Version 5.7 (Alpha Only)........................................ 1-1 1.3 Reverse Path Caching......................... 1-2 1.4 DEC X.25 Client (Alpha Only)................. 1-2 1.5 Case-Sensitivity of Nodes Running Old Versions of DECnet-VAX Software.............. 1-3 1.6 OpenVMS Operating System Notes............... 1-3 1.6.1 DECnet Option Required When Installing OpenVMS Alpha Version 6.1 (Alpha Only)... 1-3 1.6.2 Upgrading OpenVMS from Version 1.5 (Alpha Only).................................... 1-3 1.6.3 OpenVMS Operating System Monitor Utility.................................. 1-4 1.7 VAX P.S.I. DTE X.121 Mapping (VAX Only) ..... 1-4 1.7.1 To Reconfigure the MTA Dictionary Used by MRX...................................... 1-4 1.7.2 To Use an Image That Does Not Perform X.121 Mapping............................ 1-5 1.8 Use Default Integrated Routing Mode.......... 1-5 2 Installation and Configuration 2.1 New Cluster Configuration Options............ 2-1 2.2 PCSI Installation Used for VAX............... 2-2 2.3 Reinvoke NET$CONFIGURE.COM After Installing DECnet/OSI................................... 2-2 2.4 Access to Transport Congestion Avoidance Values in NET$CONFIGURE...................... 2-3 2.5 Message Displays After Reboot (VAX Only)..... 2-3 iii 2.6 Use of /REMOTE With POLYCENTER Installation (Alpha Only)................................. 2-4 2.7 DCL Symbol Problem........................... 2-4 3 Network Management 3.1 Known Problems, Restrictions and Workarounds.................................. 3-1 3.1.1 NET$SHUTDOWN Known Problems.............. 3-1 3.1.2 RECEIVE BUFFERS Attribute on HDLC LINK Entity (Alpha Only)...................... 3-1 3.1.3 Outgoing Alias Enabled Defaults to TRUE..................................... 3-2 3.1.4 Restrictions on Using DECdtm Services (VAX Only)............................... 3-3 3.2 Routing Notes................................ 3-3 3.2.1 Change to DNA ADDRESS FORMAT Attribute... 3-3 3.2.2 End System No Longer Requires Autoconfiguration for Cluster Alias...... 3-4 3.2.3 Default PROBE RATE Raised................ 3-4 3.3 Transition Notes............................. 3-4 3.3.1 Decimal Syntax DSPs Not Supported........ 3-4 3.3.2 COLLECT Command and Addressing in DECNET_MIGRATE Commands.................. 3-4 3.4 NSP Transport Notes.......................... 3-4 3.4.1 Transmit and Receive Window. Change of Default values........................... 3-5 3.4.2 Unsupported NSP Entity Attributes........ 3-5 3.4.3 Requirements for Deleting and Creating the NSP Entity........................... 3-5 3.4.4 DISABLE Command Problem.................. 3-6 3.5 OSI Transport Notes.......................... 3-6 3.5.1 Connection to Non-Conformant Systems - Connection Failure....................... 3-6 3.5.2 OSI Transport Congestion Avoidance/Change of Default Value......................... 3-7 3.5.3 Transmit and Receive Window. Change of Default Values........................... 3-7 3.5.4 Known Problems and Workaround............ 3-8 3.5.5 Configuring X.25 Access Filters for Use by OSI Transport (VAX Only).............. 3-9 3.5.6 Configuring CONS......................... 3-10 iv 3.5.7 Requirements for Deleting and Creating the OSI Entity........................... 3-11 3.5.8 Communications Between OSI Transport Systems and VOTS V2.0 Systems Using CLNS..................................... 3-11 4 Programming 4.1 Applications Must Wait for Connect Accept to Complete Before Using a Connection........... 4-1 4.2 OpenVMS XTI Implementation................... 4-1 4.2.1 Hints for Using the XTI Library.......... 4-4 4.2.2 OpenVMS Implementation Specific Information.............................. 4-8 4.2.3 Problems/Restrictions.................... 4-8 5 CDI 5.1 DECdns Control Program Limitation............ 5-1 5.2 decnet_migrate Limitation.................... 5-1 5.3 Node Access Problem.......................... 5-1 5.4 Backtranslation Failures Over DOMAIN (DNS/BIND)................................... 5-1 5.5 Problems with CDI$TRACE...................... 5-2 6 DECdns 6.1 Limitation For Number Of Members In A Single Group........................................ 6-1 6.2 DECdns Server Software Is Not Available for Alpha Systems................................ 6-2 6.3 DNS$SHARE.EXE Not Supported.................. 6-2 6.4 DECdns Clerk Startup......................... 6-2 6.5 DECdns Clerks and Servers May Require Additional PAGEDYN Resources................. 6-3 6.6 New DNS$CLERK_STARTUP.COM.................... 6-3 6.7 DECdns Clerks Can Now Use the Outgoing Alias When Connecting to DECdns Servers............ 6-3 6.8 Unknown LAN Device Types..................... 6-4 6.9 High Convergence Directories Not Recommended.................................. 6-4 6.10 Documentation Correction to Name Resolution Operations................................... 6-5 v 6.11 Documentation Correction to "Adding Group Access" Procedure............................ 6-5 6.12 Documentation Correction to "Denying Group Access" Example.............................. 6-5 6.13 Documentation Correction to "Relocating a Clearinghouse" Procedure..................... 6-6 6.14 Known DECdns Problems........................ 6-6 6.15 UNKNOWN and WORLD Pseudo-Namespaces.......... 6-6 6.16 DNS Version 1 and DECdns Version 2 Server Incompatibility.............................. 6-7 6.17 Message Text Change - BADCLOCK............... 6-8 6.18 New DECdns Error Message - DNS-E-LOCALNAMEABBR.......................... 6-8 6.19 Size and Creation of Clerk Cache File........ 6-9 6.20 Removing Obsolete DNS$CACHE Files............ 6-10 6.21 Clarification of WORLD Access in DNS and DECdns....................................... 6-10 6.22 Documentation Correction to DELETE CHILD Command Example.............................. 6-11 6.23 DECdns Servers Support DNS$SkulkStatus Attribute.................................... 6-11 6.24 Default Parameters for Process Limits on DECdns Servers............................... 6-11 7 DECdts 7.1 Automatic Time Zone Changes on Rebooting Clusters..................................... 7-1 7.2 Unknown LAN Device Types..................... 7-1 7.3 Configuring LANs with Global Servers......... 7-1 7.4 Corrections for CHANGE DTSS Command.......... 7-2 7.5 Advertising Global Servers................... 7-2 7.6 Advertising Global Servers Document Change... 7-3 7.7 Documentation Addition for SHOW DTSS Local and Global Server Commands .................. 7-3 7.8 Documentation Correction to SHOW DTSS Command Example...................................... 7-3 7.9 The DTSS Synchronization Completed Event Is No Longer Blocked by Default................. 7-4 7.10 Document Change - Interoperation with NTP.... 7-4 7.11 Using a Time-Provider on DECdts Server Nodes........................................ 7-4 7.12 Time-Provider Interface (TPI) Advisory....... 7-5 vi 7.13 Update to List of Supported Radio Receivers.................................... 7-5 8 FTAM 8.1 Installation................................. 8-1 8.1.1 OSIF$ CONFIGURE.COM Procedure............ 8-1 8.1.2 Installation Verification Procedure (IVP).................................... 8-1 8.2 Documentation................................ 8-1 8.3 Size Restriction for FTAM-3 Fixed Files...... 8-2 8.4 DTE Address Logical.......................... 8-2 8.5 DAP/Gateway.................................. 8-2 8.6 OpenVMS File Protection Assignment Upon File Creation..................................... 8-2 8.7 File Error Recovery.......................... 8-3 9 FTAM Application Programming Interface (API) 9.1 FTAM Application Programmer Interface (API)........................................ 9-1 9.2 Changed OSIF.H osif_ae_entry Structure....... 9-1 9.3 Documentation Notes.......................... 9-2 9.3.1 osif_deassign_port Incorrectly Documented............................... 9-3 osif_deassign_port................................. 9-4 9.3.2 FTAM Programming......................... 9-6 9.3.3 Unsupported Functions.................... 9-6 9.3.4 Problems................................. 9-6 9.3.5 Suggestions.............................. 9-7 9.4 FTAM API Example............................. 9-7 9.4.1 Access to the Contents Type Database..... 9-8 9.4.2 FTAM API Message Files................... 9-8 9.4.3 Privileges Required to Use OSAK.......... 9-8 vii 10 Virtual Terminal 10.1 Local Command Mode........................... 10-1 10.1.1 CTRL-@................................... 10-1 10.1.2 Amode Repertoire......................... 10-1 10.2 Initiator.................................... 10-1 10.3 Responder.................................... 10-1 10.4 Gateways..................................... 10-2 10.4.1 VT/LAT Gateway Will Hang................. 10-2 10.4.2 Starting VT/LAT and Telnet Gateways (Alpha Only)............................. 10-2 10.5 Interoperability with DECnet/OSI Virtual Terminal Version 1.0 for ULTRIX.............. 10-2 10.5.1 SEND VT-BREAK............................ 10-2 10.5.2 SEND SYNCH............................... 10-3 10.6 Interoperability with DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX......... 10-3 10.6.1 SEND SYNCH............................... 10-3 10.6.2 VT-BREAK................................. 10-3 11 OSAK 11.1 New features................................. 11-1 11.1.1 OSAK Application Programming Interface (API).................................... 11-1 11.1.2 New OSI Session Programming Interface.... 11-1 11.2 Known Problems and Restrictions.............. 11-1 11.2.1 OSAK Software............................ 11-1 11.2.1.1 Session Disconnect Timer Not Supported.............................. 11-2 11.2.1.2 NCL Does Not Display Form 1 AE-Titles Correctly.............................. 11-2 11.2.1.3 Enumerated Data Types Not Decoded...... 11-2 11.2.1.4 OSAKtrace Output Alignment Problem..... 11-2 11.2.1.5 Use of NCL for Remote Management of OSAK Software.......................... 11-2 11.2.2 OSAK API and SPI Programming Interfaces............................... 11-2 11.2.2.1 Incorrect Decoding of SET.............. 11-3 11.2.2.2 Session Segmentation Not Supported..... 11-3 11.2.2.3 Multiple Upper Layer Addreses Not Allowed on a Transport Selector........ 11-3 11.2.2.4 Support for Programming Languages...... 11-4 viii 11.2.2.5 Receiving Odd Length NSAPs............. 11-4 ix 1 ________________________________________________________________ General Information 1.1 New Features for DECnet/OSI for OpenVMS The following new features are added in Version 6.3 for DECnet/OSI for OpenVMS: o New cluster configuration options (see Section 1.1) o NET$MGMT now supports the full X.25 entity set. o Node synonyms can be added by defining logicals in the CDI$SYSTEM_TABLE logical name table. 1.2 Upgrading from DECnet/OSI Version 5.7 (Alpha Only) If you are upgrading from DECnet/OSI Version 5.7 to Version 6.0 and later on an OpenVMS Alpha system, the installation procedure removes DECnet/OSI identifiers from RIGHTSLIST.DAT. Although the installation procedure adds them again, all user accounts that had DECnet/OSI identifiers granted to them no longer have them. This could potentially be disruptive to the proper operation of applications. To rectify this problem, you can do one of the following: o Use AUTHORIZE to GRANT the identifiers after the upgrade. o Install ECO2 of DECnet/OSI Versionn 5.7 before upgrading to Version 6.0 or later. o Before you upgrade to Version 6.0 or later, edit the SYS$UPDATE:NET$PCSI_INSTALL.COM file and remove the following lines from that file: General Information 1-1 $ set default sys$system $ run sys$system:authorize revoke/id NET$MANAGE SYSTEM remove/id NET$EXAMINE remove/id NET$MANAGE remove/id NET$SECURITY remove/id NET$DIAGNOSE remove/id NET$DECLAREOBJECT remove/id NET$REGISTERDNSOBJECT remove/id NET$DECNETACCESS remove/id NET$POSTEVENT remove/id NET$TRACEALL remove/id NET$TRACEHEADERS remove/id NET$TRACEALLREMOTE remove/id NET$TRACEHEADERSREMOTE These lines can be found after: $! $! REMOVE function $! $ if p1 .eqs. "REMOVE" $ then 1.3 Reverse Path Caching Routing has been improved to cache information about the paths that it uses to reach remote nodes. In some cases, this improves network performance. 1.4 DEC X.25 Client (Alpha Only) If you are upgrading to DECnet/OSI from DECnet Phase IV and have the DEC X.25 Client for OpenVMS Alpha Systems product installed, there are two X.25 products for OpenVMS Alpha systems. DEC X.25 Client is for DECnet Phase IV systems only. DEC X.25 is for DECnet/OSI systems only. If you upgrade to DECnet/OSI and wish to retain access to X.25, you should install the DEC X.25 product, which provides both client and native X.25 functionality. Refer to the DECnet/OSI Installation and Configuration manual for details on installing and configuring the DEC X.25 product. 1-2 General Information 1.5 Case-Sensitivity of Nodes Running Old Versions of DECnet-VAX Software Prior to the VMS Version 5.3-2 release, the DECnet-VAX software did not correctly process lowercase task names. Since the DECnet-VAX software stored object names in the database as uppercase, the comparison of a lowercase incoming task specification to the elements in object database would not find any matches. The DECnet-VAX software was modified to convert incoming task specifications to uppercase before searching for a match in the object database. When communicating with nodes running old versions of the DECnet-VAX software, uppercase task specifications should be specified on systems that preserve the case of outgoing task specifications. For example, use the following: $ TYPE NODE::"TASK=TEST" rather than $ TYPE NODE::"TASK=test". 1.6 OpenVMS Operating System Notes DECnet/OSI Version 6.3 for OpenVMS requires OpenVMS Version 6.2. 1.6.1 DECnet Option Required When Installing OpenVMS Alpha Version 6.1 (Alpha Only) When installing OpenVMS Alpha Version 6.1, DECnet/OSI requires the selection of the DECnet (Phase IV) option. This may be confusing since DECnet/OSI does not require DECnet Phase IV, however the DECnet option contains some images that are required by DECnet/OSI. Digital plans to correct this problem in a future release. 1.6.2 Upgrading OpenVMS from Version 1.5 (Alpha Only) If you are upgrading an OpenVMS Alpha Version 1.5 system and have DECnet/OSI installed on OpenVMS Version 1.5, the upgrade disables the DECnet/OSI software. Once you install the current version, your previous DECnet/OSI configuration is retained. It is not necessary to reconfigure the DECnet/OSI software. However, if you want to configure DECnet/OSI to use X.25 or HDLC, you must reconfigure. General Information 1-3 After you upgrade OpenVMS Alpha, you see boot-time error messages involving the files NET$MESSAGE.EXE and LES$LES_ V30.EXE. This is normal and the messages cease once you install the current version. Consult the OpenVMS Alpha Version 6.1 operating system release notes for further details. 1.6.3 OpenVMS Operating System Monitor Utility The OpenVMS monitor utility function, MONITOR DECnet, shows the arriving and departing local packet rate, as well as the count of available LRPs. The fields Arriving Transit Packet Rate, Transit Congestion Loss Rate, and Receive Buffer Failure Rate are not used. 1.7 VAX P.S.I. DTE X.121 Mapping (VAX Only) If your system is running the VAX Message Router X.400 Gateway V2.3 (MRX) and you upgrade to DECnet/OSI Version 5.7A or later, you need to either reconfigure the MTA dictionary used by MRX or use a PSI$L3CS.EXE image that does not perform X.121 mapping. 1.7.1 To Reconfigure the MTA Dictionary Used by MRX With the introduction of X.121 mapping in DECnet/OSI, the incoming DTE address seen by MRX is an NSAP preceded by a digit count. For inbound call verification to work correctly, you need to add a new /NETWORK_ADDRESS to each MTA record that contains a DTE address in its existing /NETWORK_ADDRESS. The new /NETWORK_ADDRESS must specify the NSAP as the DTE address. The existing /NETWORK_ADDRESS is still used for outgoing calls, so do not modify or delete the existing /NETWORK_ ADDRESS. The NSAP is generated as follows. The DTE must be exactly 14 digits long. If it is less than 14 digits, it must be padded as follows: o If it begins with a 0, it must be padded with leading 1s. o If it begins with any number other than 0, it must be padded with leading 0s. 1-4 General Information The padded DTE is preceded by 1052 if it has been padded with 1s or began with a 0. It is preceded by 1036 if it has been padded with 0s or began with any digit other than a 0. Therefore, a DTE of 0123456789 appears to be a DTE of 105211110123456789 and a DTE of 1234567890 appears to be a DTE of 103600001234567890. For example, for an MTA with the MTA_NAME MTA_1 that currently has two /NETWORK_ADDRESSes of .ENG.X25_ QNET%0123456789 and .ENG.X25_QNET%1234567890, the following commands need to be entered: $ RUN SYS$SYSTEM:MRXMAN MRXMAN> SELECT MTA/MTA_NAME=MTA_1 MRXMAN> MODIFY MTA/NETNO=NEW/NETWORK=.ENG.X25_QNET%105211110123456789 MRXMAN> MODIFY MTA/NETNO=NEW/NETWORK=.ENG.X25_QNET%103600001234567890 MRXMAN> ADD MODIFIED MRXMAN> EXIT 1.7.2 To Use an Image That Does Not Perform X.121 Mapping Find the saveset DNVOSI058.S on your distribution media. Define the logical KIT_DIRECTORY to be the directory the saveset is on and perform the following backup command: $ backup KIT_DIRECTORY:DNVOSI058.S;2/save- /select=PSI$L3CS.EXE-X121-NSAP-MAPPING-DISABLED - sys$common:[sys$ldr]PSI$L3CS.EXE/log/new_version %BACKUP-S-CREATED, created SYS$COMMON:[SYS$LDR]PSI$L3CS.EXE;36 In the event of any difficulty, contact your Customer Support Center. 1.8 Use Default Integrated Routing Mode Use the default Integrated routing mode in a integrated routing environment where the routers can handle Phase IV to DECnet/OSI or DECnet/OSI to Phase IV packet format conversions. Not using the default causes cluster alias not to work properly. Use the Segregated routing mode only when the adjacent router(s) cannot perform Phase IV to DECnet/OSI or DECnet/OSI to Phase IV packet conversions. General Information 1-5 2 ________________________________________________________________ Installation and Configuration 2.1 New Cluster Configuration Options Two new options have been added to the ADVANCED configura- tion; configuring satellite nodes and configuring cluster script locations. They are both sub-menus of the Configure Cluster Alias option. In order to run either of these, the user must have successfully run NET$CONFIGURE ADVANCED and NET$CONFIGURE is executing on a cluster system. For more information, refer to the DECnet/OSI for OpenVMS Part 2: Applications Installation and Advanced Configuration guide, Modifying a Current Configuration chapter. Configuring satellite nodes scans the system disk for evidence of satellite nodes that have not yet been configured to run Phase V. Should it find one, it will create SYS$SPECIFIC:[SYS$STARTUP]NET$AUTOCONFIGURE.COM, which will cause the cluster member to automatically configure Phase V the next time it reboots. Configuring cluster script locations allows the sys- tem manager to make the network startup scripts for NET$APPLICATION_STARTUP, NET$MOP_CLIENT_STARTUP and NET$EVENT_STARTUP to be common for all cluster nodes. That is, a single copy of the script will be shared by all systems in the cluster. This allows a single configuration for those scripts to be common to all system, ensuring that all systems will have the same application, mop client and event logging configuration. It does this by copying the script from the SYS$SPECIFIC directory to the SYS$COMMON directory. Note that when it does so, it does not delete the script from the SYS$SPECIFIC directories for the other cluster systems. This must be done by rerunning the dialog for all cluster members. Installation and Configuration 2-1 2.2 PCSI Installation Used for VAX Before installing DECnet/OSI using PCSI for the first time on OpenVMS VAX Version 6.1, you should execute the following DCL command: $ PRODUCT REGISTER PRODUCT VMS/VERSION=V6.1/SOURCE=SYS$UPDATE This needs to be done only once in the life of the OpenVMS system; it makes a permanent entry in the PCSI database, so it remains effective across system boots and for all future software upgrades. If you do not perform this operation before installing DECnet/OSI, the installation recommends termination, due to the failure to locate the product "DEC VAXVMS VMS Version 6.1". Answer "Yes" to the question "Do you want to terminate?" and perform the product register command as in the above example. If you use the PCSI DECwindows interface to register OpenVMS, you should exit and re-enter the DECwindows PCSI interface before installing DECnet/OSI. This problem has been fixed in Version 6.2 of the OpenVMS operating system. 2.3 Reinvoke NET$CONFIGURE.COM After Installing DECnet/OSI After upgrading from a DECnet/OSI Version 5.X system to DECnet/OSI Version 6.X (where X stands for the release number), use NET$CONFIGURE.COM to reconfigure your node so that the directory services part is configured appropriately. You may either use Option 1 (perform full configuration) or Option 2 (Change node name/namespace name) to do this. As a result, the DECnet/OSI checksum file is upgraded for you and a new NCL script called SYS$MANAGER:NET$SEARCHPATH_STARTUP.NCL is created. 2-2 Installation and Configuration 2.4 Access to Transport Congestion Avoidance Values in NET$CONFIGURE The BASIC mode of NET$CONFIGURE now sets the default value for OSI Transport and NSP Congestion Avoidance characteristics to FALSE. The ADVANCED mode of NET$CONFIGURE allows you to set this value by your answer to an additional configuration question concerning operation in a multi-protocol network environment. After you are asked the following questions: * Do you want to replace the existing NSP transport script? [NO] : * Do you want to replace the existing OSI transport script? [NO] : You are asked a new question about multi-protocol networks: * Is this System operating in a Multi-Protocol Network? [YES] : If you take the default answer of YES, then the OSI Transport and NSP Congestion Avoidance characteristic will be set to FALSE. A NO answer to this question will set the characteristic to TRUE. Please note that currently NSP does not support the Congestion Avoidance attribute. For more details about OSI Transport Congestion Avoidance please refer to Section 3.5.2. 2.5 Message Displays After Reboot (VAX Only) After the installation of OpenVMS Version 6.1, but before the installation of DECnet/OSI Version 6.3, the following messages appear soon after a reboot: %SYSINIT-W- Failed to load LES comms executive %SYSINIT-E- Error loading LES$LES_V30.EXE status = 00002398 After the installation of DECnet/OSI Version 6.3, these messages no longer occur. Installation and Configuration 2-3 2.6 Use of /REMOTE With POLYCENTER Installation (Alpha Only) Although the POLYCENTER Software Installation Utility allows you to install software on a target system that is not the currently running system, this should not be done with DECnet/OSI. The DECnet/OSI installation procedure performs functions that affect the running system, so use of the /REMOTE qualifier is not supported. 2.7 DCL Symbol Problem Using long strings as descriptive names for data links and routing circuits in the NET$CONFIGURE.COM procedure reduces the number of definable data links and routing circuits. For maximum use of all possible data links and routing circuits, use the default values. 2-4 Installation and Configuration 3 ________________________________________________________________ Network Management 3.1 Known Problems, Restrictions and Workarounds The following sections discuss known network management problems and workarounds. 3.1.1 NET$SHUTDOWN Known Problems The following lists the known problems with NET$SHUTDOWN. o NET$SHUTDOWN.COM does not work properly on a remotely displayed DECterm window. If you use SYS$SYSTEM:SHUTDOWN.COM to shut down your system and you ask that it delay shutting down your system for a certain number of minutes, SHUTDOWN.COM calls NET$SHUTDOWN.COM to shut down the network five minutes prior to the time that you specified. This means that anyone connected to the system using DECnet/OSI is disconnected from the system five minutes earlier than expected. This problem will be corrected in the future. o The DELETE ROUTING CIRCUIT * command can hang during the network shutdown on multicircuit end systems with one or more FDDI circuits. To recover, type ^Y to continue the shutdown. The fix will be in the future release. We recommend removing the command in the NET$SHUTDOWN.COM as a workaround for now. 3.1.2 RECEIVE BUFFERS Attribute on HDLC LINK Entity (Alpha Only) The RECEIVE BUFFERS attribute of the HDLC LINK entity is not implemented in DECnet/OSI. An attempt to set the attribute results in the following message from NCL: Network Management 3-1 NCL>SET NODE 0 HDLC LINK HDLC-0 RECEIVE BUFFERS 8 Node 0 HDLC Link HDLC-0 at 1994-04-28-09:51:10.780-04:00I0.113 command failed due to: set list error Characteristics no such attribute ID: Receive Buffers = 8 This message is harmless. HDLC allocates the number of receive buffers that it requires; it is not settable through network management. 3.1.3 Outgoing Alias Enabled Defaults to TRUE The Active Server characteristic Outgoing Alias Enabled defaults to TRUE when the equivalent on Phase IV was FALSE. You can work around this problem by predefining the characteristic in the application database. For example, an active server defines itself to be called "BRYAN1" and it is necessary for it to have Outgoing Alias and Outgoing Proxy to be FALSE. Pre-define these characteristics in the application database by running NET$CONFIGURE. Configuration Options: [0] Exit this procedure [1] Perform an entire configuration [2] Change naming information [3] Configure Devices on this machine [4] Configure Transports [5] Configure Timezone Differential Factor [6] Configure Event Dispatcher [7] Configure Application database [8] Configure MOP Client database [9] Configure Cluster Alias 3-2 Network Management * Which configuration option to perform? [1] : 7 * Do you want to ADD or DELETE an Application? [ADD] : * What is the name of the Application? : bryan1 * What is the destination type for 'bryan1'? [NAME] : * What is the destination name for 'bryan1'? : bryan1 * Do you want to specify another application address? [NO] : * What is the name of the Client for 'bryan1'? : * What is the Image name for 'bryan1'? : * Incoming Alias for 'bryan1' enabled? [TRUE] : * Incoming Proxy for 'bryan1' enabled? [TRUE] : * Outgoing Alias for 'bryan1' enabled? [TRUE] : false * Outgoing Proxy for 'bryan1' enabled? [TRUE] : false * Require node synonym for 'bryan1' enabled? [TRUE] : * What is the Incoming OSI TSEL for 'bryan1'? : * What is the User Name for 'bryan1'? [BRYAN$SERVER] : * What UIC should 'bryan1' use? [[200,200]] : * Rights identifiers for 'BRYAN$SERVER'? : %NET$CONFIGURE-I-MAKEACCOUNT, this procedure creates user account BRYAN$SERVER * Do you want to generate NCL configuration scripts? [YES] : yes 3.1.4 Restrictions on Using DECdtm Services (VAX Only) If you are using DECnet/OSI, you cannot use DECdtm services on OpenVMS VAX Version 6.0. While DECdtm supports DECnet/OSI fullnames, Rdb and ACMS do not. Rdb and ACMS only work with node synonyms. 3.2 Routing Notes The following sections refer to routing. 3.2.1 Change to DNA ADDRESS FORMAT Attribute The DNA ADDRESS FORMAT attribute controls only the interpretation of PhaseIV addresses. It no longer controls autoconfiguration. An empty set of MANUAL NETWORK ENTITY TITLES attributes indicates the use of autoconfiguration. When non-empty, autoconfiguration does not take place. This routing attribute may only be changed from the empty set to the non-empty set or from the non-empty set to the empty set when the entity is in state off. These changes allow the end systems to disable autoconfiguration, but not form adjacencies to out of area PhaseIV addresses. Network Management 3-3 3.2.2 End System No Longer Requires Autoconfiguration for Cluster Alias The end system no longer requires autoconfiguration to use the cluster alias. It can now construct the NSAP address for the alias from the manual NETs. 3.2.3 Default PROBE RATE Raised The default PROBE RATE on multicircuit end systems has been raised from 20 to 1000 to avoid too frequent probing that could increase the network overhead and affect the performance on higher performance systems. The new default value is a tentative one. 3.3 Transition Notes The following sections discuss transition information. 3.3.1 Decimal Syntax DSPs Not Supported DECnet/OSI for OpenVMS supports only those IDPs (initial domain part) that specify the use of binary syntax DSPs (domain-specific part). IDPs that specify decimal syntax DSPs are not supported. 3.3.2 COLLECT Command and Addressing in DECNET_MIGRATE Commands Some connection errors might be reported for nodes with DECnet/OSI addresses that are not also Phase IV compatible. This occurs because the network management interface on OpenVMS cannot deal with connections to nodes by the explicit use of a DECnet/OSI address that is not also Phase IV compatible. If a DECnet/OSI node also has a Phase IV compatible address, information is collected for it using that address. 3.4 NSP Transport Notes The following sections discuss information relevant to NSP Transport. 3-4 Network Management 3.4.1 Transmit and Receive Window. Change of Default values NSP receiver's window is controlled by a combination of "Maximum Transport Connections", "Maximum Receive Buffers", and "Maximum Window". The receiver initial quota is determined by dividing "Maximum Receive Buffers" by "Maximum Transport Connections". During the life of the connection, the receiver quota fluctuates, using the value of "Maximum Receive Buffers" divided by "Currently Active Connections". The credit window sent to the remote transmitter may or may not be this quota value, depending on the value of "Maximum Window". If "Maximum Window" is set to less than the determined receiver quota, this value is used instead for the credit granted to the remote transmitter. The transmitter on an NSP connection uses the credit sent by the remote receiver as its transmit window, unless "Maximum Window" is a lower value. In that case, "Maximum Window" is used for the transmitter window. By controlling the transmitter's and receiver's window as above a dynamic balance of system resource consumption and network performance may be achieved and maintained. The new default values for these attributes more accurately match our observed customer environments. 3.4.2 Unsupported NSP Entity Attributes The NSP entity does not support the CONGESTION AVOIDANCE attribute. The NSP entity does not support a value of zero for the MAXIMUM REMOTE NSAPS attribute. 3.4.3 Requirements for Deleting and Creating the NSP Entity If the NSP entity is deleted and subsequently recreated, you must issue the following directives to inform DNA SESSION CONTROL that the NSP transport service is available: NCL> DELETE SESSION CONTROL TRANSPORT SERVICE NSP NCL> CREATE SESSION CONTROL TRANSPORT SERVICE NSP PROTOCOL %X04 You cannot DELETE SESSION CONTROL TRANSPORT SERVICE NSP while NSP PORT entities exist. Network Management 3-5 3.4.4 DISABLE Command Problem The DISABLE NSP command can hang at the NCL prompt. To recover, follow these steps: 1. Enter another NCL session and issue: NCL> SHOW SESSION CONTROL PORT * ALL 2. Delete each session in turn with: NCL> DELETE SESSION CONTROL session_port_name Do not try to re-enable NSP until the NCL prompt returns from the DISABLE NSP command. 3.5 OSI Transport Notes The following sections discuss OSI Transport information. 3.5.1 Connection to Non-Conformant Systems - Connection Failure By default, OSI Transport sends Preferred maximum TPDU size, Request Acknowledgment, and Implementation ID parameters in its CR TPDU. According to ISO 8073, OSI Transport providers should ignore unknown parameters while processing CR TPDU. However, some vendor implementations do not conform and do not ignore unknown parameters in CR TPDU. This results in Connection failure. The following example provides a way to prevent issuance of these parameters in CR TPDU. NCL> set osi transport template template-id - send Preferred maximum TPDU size FALSE NCL> set osi transport template template-id - send Request Acknowledgment FALSE NCL> set osi transport template template-id - send implementation ID FALSE 3-6 Network Management 3.5.2 OSI Transport Congestion Avoidance/Change of Default Value One feature of OSI Transport is the ability to use the "Congestion Experienced" field in the ConnectionLess Network Service (CLNS) routing header, and to implement a "Congestion Avoidance" scheme in heavily congested networks. The CLNS Congestion Experienced field is used by routers that support this feature (such as DECnis) to give an early indication of congestion. When OSI Transport receives data that passed through a network path where the "Congestion Experienced" bit is set, OSI Transport reduces the transmit rate of the sending end system to help alieviate network congestion. While this feature works well in networks where all protocols support "Congestion Avoidance" mechanisms, it has been noted that in some heavily congested multi- protocol networks this feature can negatively impact the performance of DECnet compared to other protocols. Digital recognizes that most of its customers have a multi- protocol network. In this environment, not all network protocols have "Congestion Avoidance" mechanisms. Therefore we have changed the default of this characteristic to be disabled. If you operate in an environment where you can take advantage of "Congestion Avoidance" mechanisms we recommend that you enable the feature again. To change Transport Congestion Avoidance values you must invoke NET$CONFIGURE in ADVANCED mode and use Option 4 (Configure Transports). You should answer NO to the question * Is this System operating in a Multi-Protocol Network? [YES] : 3.5.3 Transmit and Receive Window. Change of Default Values OSI Transport receiver's window is controlled by a combination of "Maximum Transport Connections", "Maximum Receive Buffers", and "Maximum Window". The receiver initial quota is determined by dividing "Maximum Receive Buffers" by "Maximum Transport Connections". During the life of the connection, the receiver quota fluctuates, using the value of "Maximum Receive Buffers" divided by Network Management 3-7 "Currently Active Connections". The credit window sent to the remote transmitter may or may not be this quota value, depending on the value of "Maximum Window". If "Maximum Window" is set to less than the determined receiver quota, this value is used instead for the credit granted to the remote transmitter. The transmitter on an OSI Transport connection uses the credit sent by the remote receiver as its transmit window, unless "Maximum Window" is a lower value. In that case, "Maximum Window" is used for the transmitter window. By controlling the transmitter's and receiver's window as above a dynamic balance of system resource consumption and network performance may be achieved and maintained. The new default values for these attributes more accurately match our observed customer environments. 3.5.4 Known Problems and Workaround The following lists the known OSI Transport problems and the workarounds. o If OSI Transport times out during data transfer mode because the remote end is unreachable, the error SS$_ CONNECFAIL may also be returned in the IOSB for the $QIO(IO$_READVBLK) or $QIO(IO$_WRITEVBLK) call. As a workaround, user code should be made to handle SS$_ TIMEOUT as well as SS$_CONNECFAIL. o When defining an RFC1006 address using the OSIT$NAMES logical name table, you must put a quotation mark around the address part. o The DISABLE OSI Transport command can hang at the NCL prompt. To recover, follow these steps: 1. Enter another NCL session and issue: NCL> SHOW SESSION CONTROL PORT * ALL 2. Delete each session in turn with: NCL> DELETE SESSION CONTROL session_port_name Do not try to re-enable OSI Transport until the NCL prompt returns from the DISABLE OSI Transport command. 3-8 Network Management o The prohibition against 0 and 1 as valid NSELs has been removed, but the following restrictions apply: o That the NSELs for OSI Transport must be the same in both transport partners if the packet is traversing a backbone containing Phase IV routers (as opposed to routing vector domains). o That cluster alias uses 2 ranges of NSELs; that to reduce the risk of a collision, it is recommended that values from those ranges not be chosen, or at least that the first few values in each range not be chosen. o Expedited data could be delivered before normal data on on SMP VAXstation 3250 that has more than one processor. o The OSI Transport entity does not support a value of zero for the maximum remote NSAPs attribute. The OSI Transport entity does not support a value of ANY for the template network service attribute. If this attribute is set to ANY, it is treated by OSI Transport as CLNS. 3.5.5 Configuring X.25 Access Filters for Use by OSI Transport (VAX Only) Create X.25 Access filters with the VAX P.S.I. configu- ration procedure, using the Declaring a Network Process Section, as follows: 1. On the introduction screen to Declaring a Network Process section, answer YES to the question: Do you want X.25 or X.29 programs to specify filter names in $QIO(IO$_ACPCONTROL) calls? 2. On the next screen, answer NO to the question: Do you want IO$_ACPCONTROL calls issued by your programs to name any dynamic filters? 3. On the next screen, answer YES to the question: Do you want IO$_ACPCONTROL calls issued by your programs to name any static filters? Network Management 3-9 4. On the following two screens you can set up the attributes for the X.25 Access filter. You are prompted to enter Network Process Filter information. You must complete the following fields: o Filter Name: OSI Transport o Call Data Value: for example, %X03010100 o Call Data Mask: for example, %XFFFFFFFF The Filter Name can be set to any name. However, the name used must match the name entered as the X.25 access Template Name and as the OSI Transport CONS template name. The OSI TRANSPORT TEMPLATE attribute CONS TEMPLATE is case sensitive and must match the OSI TRANSPORT attribute CONS FILTERS exactly. The Call Data Value and Call Data Mask entries are used by VAX P.S.I. to determine whether an inbound network connect should be passed to OSI transport. For other fields, use the default value provided. You can set up a security filter corresponding to this X.25 Access filter in the Incoming Security for Network Processes Section of the VAX P.S.I. configuration procedure. 3.5.6 Configuring CONS To configure CONS support, each element in the set of CONS Filters attribute of the OSI Transport entity must have a corresponding X25 access filter of the same name. By default the CONS Filters attribute of the OSI Transport entity is set to OSI Transport. Similarly, the CONS Template attribute of the OSI Transport Template sub- entity must contain a name which is a PSI filter and is contained in the set of CONS Filters of the OSI Transport entity. The default value of the CONS Template attribute of an OSI Transport Template sub-entity is OSI Transport. 3-10 Network Management 3.5.7 Requirements for Deleting and Creating the OSI Entity If the OSI entity is deleted and subsequently recreated, you must issue the following directives to inform DNA SESSION CONTROL that the OSI Transport service is available: NCL> DELETE SESSION CONTROL TRANSPORT SERVICE OSI NCL> CREATE SESSION CONTROL TRANSPORT SERVICE OSI PROTOCOL %X05 You cannot DELETE SESSION CONTROL TRANSPORT SERVICE OSI while OSI PORT entities exist. 3.5.8 Communications Between OSI Transport Systems and VOTS V2.0 Systems Using CLNS If you need communication between a VOTS V2.0 system and an OSI Transport system using the full Internet CLNS protocol, you must use an intermediate system (router). OSI Transport implements only the Internet protocol. An OSI Transport system has no way of finding another end system that does not support ES-IS without using an intermediate system. If a DEC WANrouter is used as an intermediate system, it must be configured as a link state router. If the VOTS V2.0 system and the DEC WANrouter reside on the same LAN subnetwork AND the VOTS V2.0 system is configured with a DECnet/OSI compatible NSAP address, the DEC WANrouter need only be configured as a level 1 router. If the VOTS V2.0 system does not have a Phase V DNA compatible NSAP address, or if the VOTS V2.0 system and the DEC WANrouter do not reside on the same LAN subnetwork, the DEC WANrouter must be configured as a level 2 router. When using a level 1 router, you must create a manual adjacency on the router for the VOTS V2.0 system. When using a level 2 router, you must create a reachable address on the router for the VOTS V2.0 system. See the DEC WANrouter configuration and management guides for details about how to configure manual adjacencies and reachable addresses. Network Management 3-11 OSI Transport systems and VOTS V2.0 systems on the same LAN can communicate without an intermediate system, using the Null Internet CLNS protocol. 3-12 Network Management 4 ________________________________________________________________ Programming 4.1 Applications Must Wait for Connect Accept to Complete Before Using a Connection In Phase IV, a program can accept an incoming request to establish a link with a no-wait $QIO (FUNC=IO$_ACCESS) call, followed immediately with a read or write operation on the channel. This behavior is not preserved with DECnet/OSI. In DECnet/OSI, your application must wait for the connect accept to complete before attempting to use the connection. 4.2 OpenVMS XTI Implementation OpenVMS XTI software is an implementation of XTI based on the 1992 specification, which is included in the X/Open Portability Guide issue 4 (XPG4). The X/Open Document number is XO/CAE/91/600. Because it is necessary to recognize anything unique regarding the transport interfaces on any particular system, this implementation is for OpenVMS only. To run XTI you need the next functional release of OpenVMS (later than Version 6.1). The supported transport protocols in this baselevel are TCP, UDP, DECnet, and OSI COTS. Internet protocol (TCP, UDP) support uses DEC TCP/IP Services, more usually known as UCX. You must have UCX V2.0 or a later version installed to use TCP or UDP. DECnet protocol support uses the QIO interface. You can use it with the Phase IV or Phase V DECnet software. DNA is supported through out the NET device - DNA session. OSI COTS is supported though the OS device VOTS and uses the default template. Programming 4-1 You should use the X/Open Portability Guide Issue 4 (XPG4) in addition to the DECnet/OSI for OpenVMS programmer's manual and the example programs which are located in sys$examples. The example programs were ported from an XPG3 XTI implementation on DEC OSF/1 and are listed as follows: SX.c - OSI server CX.c - OSI client SUBX.c - Common subroutine library nsaps.dat - Lookup file for nsaps XTIUTIL.c - OpenVMS specific subroutine library VMS_OSI.h - OpenVMS specific include file xti_examples.com - OpenVMS specific build using DECC The XTI routines are: int t_accept(int fd, int resfd, struct t_call *call); char *t_alloc(int fd, int type, int fields); int t_bind(int fd, struct t_bind *req, struct t_bind *ret); int t_close(int fd); int t_connect(int fd, struct t_call *sndcall, struct t_call *rcvcall); int t_error(char *errmsg); int t_free(char *ptr, int struct_type); int t_getinfo(int fd, struct t_info *info); int t_getprotaddr(int fd, struct t_bind *bound, struct t_bind *peer); int t_getstate(int fd); int t_listen(int fd, struct t_call *call); int t_look(int fd); int t_open(char *name, int oflag, struct t_info *info); int t_poll(struct xtipoll fds[], int nfds, int timeout); int t_optmgmt(int fd, struct t_optmgmt *req, struct t_optmgmt *ret); int t_rcv(int fd, char *buf, unsigned int nbytes, int *flags); int t_rcvconnect(int fd, struct t_call *call); int t_rcvdis(int fd, struct t_discon *discon); int t_rcvrel(int fd); int t_rcvudata(int fd, struct t_unitdata *unitdata, int *flags); int t_rcvuderr(int fd, struct t_uderr *uderr); int t_select(int nfds, int *rdfds, int *wrfds, int *exfds, - struct xtitimeval *timeout); int t_snd(int fd, char *buf, unsigned int nbytes, int flags); int t_snddis(int fd, struct t_call *call); int t_sndrel(int fd); int t_sndudata(int fd, struct t_unitdata *unitdata); 4-2 Programming char *t_strerror(int errnum); int t_sync(int fd); int t_unbind(int fd); All of these except t_poll and t_select are standard XTI functions. t_poll and t_select are supplied for event management, and allow you to wait for an event on one or more transport endpoints. For t_poll, the function parameters are: fds - array of polling structures: fds[i].fd - file descriptor number (-1 = skip this one) fds[i].events - mask of XTI events of interest (T_xxxxxx) fds[i].revents - on return, filled in with pending event mask nfds - number of elements in array timeout - timeout on wait period, in millisecs (-1 = infinite) t_poll returns the count of endpoints with outstanding events. Examine the "revents" member of each array element to determine which endpoints have events. t_poll is modeled on the System V function "poll", which POSIX prefers to "select". The two are fairly similar, differing mainly in parameter format. For t_select, the function parameters are: nfds - number of file descriptors (0 to nfds-1) rdfds - pointer to an array of ints, in which the N'th bit is set if fd #N is to be inspected for read events (T_DISCONNECT, T_LISTEN, T_CONNECT, T_DATA, T_EXDATA) wrfds - pointer to an array of ints, in which the N'th bit is set if fd #N is to be inspected for write events (T_GODATA, T_GOEXDATA) exfds - pointer to an array of ints, in which the N'th bit is set if fd #N is to be inspected for exception events (T_DISCONNECT, T_ORDREL, T_UDERR) timeout - pointer to struct xtitimeval specifying the timeout on waiting (NULL = infinite wait) Programming 4-3 t_select returns the count of endpoints with outstanding events. Examine the rdfds, wrfds, exfds bitvectors to determine which endpoints have events - bit N is set or cleared appropriately. t_select is similar to the Berkeley UNIX "select" system call t_poll is recommended when writing new code. ________________________Note ________________________ If the request (req) argument is the same structure as the return (ret) argument on a t_bind(), then the contents of the arguments are zeroed. Until this is fixed in the next release, use a different structure for each argument (req,ret). _____________________________________________________ 4.2.1 Hints for Using the XTI Library The following list includes hints for using the XTI library. o #include in your source files. o You should be able to use DEC C or VAX C to compile your program. XTI itself was compiled with DEC C, but you do not need DEC C on your system to use XTI. o To link your program, include the following in your options file: SYS$SHARE:XTI$XTILIB/SHARE o The transport provider name passed to t_open must be one of "dnet", "ucx/tcp", "ucx/udp", or "osi/cots". The case is important, although sometimes it might not look that way. The example file xtiutil.c in sys$examples contain examples of addressing for use in DEC OSF/1 porting and for OpenVMS only. o For the Internet protocols, a transport address must be in the form of a 'sockaddr_in', as defined in the file IN.H (which comes with UCX). Alternatively, you can use 'xtiaddr_in' from XTI.H, which is supposed to be identical. 4-4 Programming o For DECnet, a transport address is a string of the form node::"objnum=objnam", as used by the DECnet QIO interface. An 'xtiaddr_dn' structure is defined to be a string of maximal length for convenience in allocating storage, but actual parameters need not be that large. o For OSI Transport, a transport address must be in the form of a 'xtiaddr_osi'. This form is also defined in XTI.H. The structure contains an NSAP and a TSAP-id (TSEL). XTI always uses the DEFAULT transport template. To override transport characteristics, you must use XTI option management. The NSAP must be in binary form, that is, it must be packed. There are example routines that pack the NSAP in subx and in xtiutil.c. The file xtiutil.c contains example routines to format the osi, DNA and tcp/udp addresses. o Support of transport options may be limited by the transport provider; for example, none of the OSI quality-of-service options are supported. Non-support is indicated by a T_NOTSUPPORT status, as specified by XTI. When using the option READ-ONLY, options must be removed from the options buffer when passed to a call that tries to set them. A permission error (TACCES) is returned. This could happen if you supply a return options buffer to t_bind() and just pass the buffer to the t_accept() call. The read-only options would cause a TACCES error. You could remove the options from the returned buffer of the t_bind(), call t_ optmgmt to negotiate the options you want, or not pass return buffer to t_bind(). Consult the X/OPEN XPG4 XTI documentation for a discussion of the options. The support options for the OpenVMS XTI implementation are: - UCX Options: 1. The XTI_GENERIC level: o XTI_RCVBUF o XTI_RCVLOWAT Programming 4-5 o XTI_SNDBUF o XTI_SNDLOWAT o XTI_LINGER 2. The INET_IP level: o IP_BROADCAST o IP_DONTROUTE o IP_REUSEADDR o IP_TOS o IP_TTL 3. The INET_TCP level: o TCP_NODELAY o TCP_KEEPALIV o TCP_MAXSEG (read only) 4. The INET_UDP level: o UDP_CHECKSUM - OSI Supported Options are: o TCO_PREFCLASS o TCO_EXPD o TCO_CHECKSUM o TCO_EXTFORM (read only) o TCO_FLOWCTRL (read only) The option level is ISO_TP for OSI options. The file xtiutil.c contains an example of setting OSI options - vms_set_options(). This subroutine is used by the example program cx and sx. A partial extract of vms_set_options() follows: 4-6 Programming struct isoco_options *popts; /* defined in vms_osi.h */ popts->class.opthdr.len = sizeof(struct t_opthdr ) + 4; popts->class.opthdr.level = ISO_TP; popts->class.opthdr.name = TCO_PREFCLASS; popts->class.opthdr.status = T_SUCCESS; popts->class.value = class; The len field includes the size of the value field. - DNA Options: Currently there is no option support for the DECnet provider interface. When using TCP/IP, you can not accept an incoming connection on the same endpoint which received the incoming connection indication. This restriction arises from the way in which the UCX 'accept' function works. The OSF example programs are ported to OpenVMS. They are CX, SX and SUBX. For the OpenVMS implementation there are two additional files, vms_osi.h and xtiutil.c. The xtiutil.c contains example routines to format OSI addresses and set OSI options. The example client/server program was ported from the DEC OSF/1 XPG3 implementation. OpenVMS XTI is a XPG4 implementation, thus the option management is different. See the X/Open XTI documentation for a list of the differences between XPG4 and XPG3. The sockaddr_osi structure is used to emulate the DEC OSF/1 universal address structure. This structure is used in the OpenVMS ported helper routines which are defined in xtiutil.h. See the DEC OSF/1 programmers manual for a description of the helper routines. You can also examine the source file xtiutil.c and vms_osi.h. Programming 4-7 Under OpenVMS, the sockaddr_osi structure is a union of the various OpenVMS provider structures. OpenVMS XTI programmers do not have to use it; they can use the structures provided in xti.h directly. 4.2.2 OpenVMS Implementation Specific Information The following lists information specific to the OpenVMS implementation. o An "XTI file descriptor" is not related to an OpenVMS C RTL file descriptor, or any other file descriptor. Therefore, you cannot use any OpenVMS C RTL I/O routine to manipulate an XTI transport endpoint, select() included. o Transport endpoints cannot be passed across a fork() or vfork() operation. 4.2.3 Problems/Restrictions The following lists known XTI problems and restrictions. o No protection exists against calling an XTI routine while another XTI routine is active (that is, no re- entrancy). This could corrupt the endpoint. o Servers must be RUN; they cannot be automatically started by the network software, since there is no way to pass an existing connection indication (the one which caused the process to be started) to XTI. o There is no access control. This may be implemented in a future release using the option management mechanism. Since all servers must be RUN, this is not much of a restriction. o For TCP, t_sndrel() and t_rcvrel() do not leave the endpoint in a state suitable for establishing a further connection. Digital recommends that you close the endpoint after a connection has been released. o For TCP, the t_snddis() and t_rcvdis() functions have to deassign the channel to the UCX device. This loses any address binding, although the XTI state does not reflect that. You should close the endpoint after a connection has become disconnected. 4-8 Programming o Flow control events T_GODATA and T_GOEXDATA are never reported. o If a UDP datagram exceeds the size of the buffer specified in the t_rcvudata() call, then the excess is simply discarded. The T_MORE flag is never set. o When using non-blocking mode with DECnet or OSI Transport, calls to t_snd() may still block process execution. There is currently no way to implement the XTI semantics. All other XTI functions operate as expected in non- blocking mode. Programming 4-9 5 ________________________________________________________________ CDI 5.1 DECdns Control Program Limitation You cannot use the DECdns Control Program, dnscp, to manage information stored in the Local namespace. Instead, use the new decnet_register tool. 5.2 decnet_migrate Limitation The decnet_migrate tool only works for nodes using the DECdns name service. In particular, the decnet_migrate collect and show path commands do not work for nodes using the Local namespace and DNS/BIND. 5.3 Node Access Problem When a node is a DNS server, do not use NET$CONFIGURE.COM with Local as the primary name service (to be searched first) and DECdns as the secondary name service (to be searched after Local). When called by NET$CONFIGURE.COM during configuration, the decnet_register tool can return a node lookup failure due to the local node not having the proper access to read information stored in DECdns, the secondary name service. See the DECnet/OSI Installation and Configuration Guide for information. 5.4 Backtranslation Failures Over DOMAIN (DNS/BIND) Incoming connections over an IP network may not work with applications that require a Phase IV-style (6 character or less) node name unless Domain synonyms are set up as described in the DECnet/OSI for OpenVMS Installation guide. CDI 5-1 5.5 Problems with CDI$TRACE The following cdi$trace problems exist: o The cdi$trace output file may occasionally be missing the last few records of the trace. o cdi$trace has known problems when run during a LAT terminal session (on an LT device). A workaround is to issue the DCL spawn command first. 5-2 CDI 6 ________________________________________________________________ DECdns 6.1 Limitation For Number Of Members In A Single Group DECdns has an internal limitation for the number of members (principals) that may be stored in a single group. The result of this problem will be the server process can crash during the skulk procedure. This skulk does not have to happen immediately, and may occur up to 24 hours after the group size limit was exceeded. This can make diagnosis of the problem more difficult, due to the indirectness of the symptoms. This problem affects DECdns servers (VMS, ULTRIX and Digital UNIX) who use groups to control access to objects stored in their DECdns namespaces. It appears that there is 100 entry table used to hold the members of a group while the group is being validated to ensure that it does not contain members who are groups that contain the original group itself again. This places a 100 entry limit on the number of members in a group. The workaround for this problem is to limit the number of entries to less than 100. We recommend that no group contain more than 75 members so that this limitation is never reached. A simple way to limit the numbers of members of any one group is to create sub-groups which are members of the original group. For example, an administrator wants to create a group with 200 members who all have authorization to manage a certain directory in the namespace. The group will be called ".dir_admin". Two possible solutions are: o Create 3 groups called ".dir_admin_a_to_f", ".dir_ admin_g_to_l", and ".dir_admin_m_to_z". These three groups are entered as the only three members of DECdns 6-1 the group ".dir_admin". Each contains a part of the alphabetically sorted list of members. o Create sub-groups using some other partitioning algorithm, such as by site code, or group function instead of the alphabet as used in solution 1. 6.2 DECdns Server Software Is Not Available for Alpha Systems DECdns server software is not available for Alpha systems. All references to DECdns servers (and to their resident clearinghouses) throughout the remainder of these release notes apply to the DECdns servers in your namespace that are running on ULTRIX or OpenVMS VAX systems. 6.3 DNS$SHARE.EXE Not Supported DECnet/OSI for OpenVMS no longer supports SYS$LIBRARY:DNS$SHARE.EXE. The SYS$DNS[W] system service is resolved using SYS$PUBLIC_ VECTORS. No special link options are necessary. 6.4 DECdns Clerk Startup The DECdns clerk startup may output the following error message: Create Node 0 DNS Clerk Known Namespace CZ command failed due to: process failure A Known Namespace with this name or NSCTS already exists This is harmless. The DECdns clerk configuration procedure puts a create dns clerk known namespace command for the default namespace into the DECdns clerk NCL startup file. The command is there for the case when the DECdns cache file has been deleted or corrupted. 6-2 DECdns 6.5 DECdns Clerks and Servers May Require Additional PAGEDYN Resources DECdns clerk and server systems can require additional paged dynamic memory resources (PAGEDYN). For DECdns clerk systems, consider increasing the PAGEDYN resource on the node if you see the following errors: RESOURCEERROR or NONSRESOURCES (during skulk operations). Before you configure a system as a DECdns server, check that the system has at least 50,000 free bytes of paged dynamic memory. Insufficient paged dynamic memory on servers can cause configuration errors, skulk failures, and in some cases normal clerk operations can fail with either of the following errors: RESOURCEERROR or NONSRESOURCES. The DNS$SERVER.LOG file can also contain messages regarding failures due to this resource. Servers holding master replicas of directories that have many read-only replicas can also require additional paged dynamic memory. 6.6 New DNS$CLERK_STARTUP.COM The DNS$CLERK_STARTUP.COM procedure now calls SYS$STARTUP:DNS$NAMES.COM (if present). Use this file to define any system-local name abbreviations you want DECdns to use. Names should be defined with the following command: $ DEFINE/NOLOG/TABLE=DNS$SYSTEM name "equivalence" 6.7 DECdns Clerks Can Now Use the Outgoing Alias When Connecting to DECdns Servers With a change in DECnet/OSI Session Control, all DECdns requests from nodes in an OpenVMS cluster can now send the cluster alias address as the source address. The current behavior is to send the individual node address. To use this new feature, edit the file SYS$MANAGER:DNS$CLERK_ CLUSTER.NCL and set OUTGOING ALIAS = TRUE. DECdns 6-3 To affect the running system, use the following NCL command on all nodes in your cluster running this release of DECnet/OSI: NCL> SET SESSION CONTROL APPLICATION DNSCLERK OUTGOING ALIAS = TRUE ________________________Note ________________________ Implementing this new feature may require nontrivial changes to the current access control in your namespace since you are essentially changing the source address of DECdns clerk requests. _____________________________________________________ 6.8 Unknown LAN Device Types To configure DECdns over an unknown LAN device type, use the system logical name DNS$ETHERNET_DEVICE, where XY defines the new device type: $ DEFINE/SYSTEM DNS$ETHERNET_DEVICE "XYA0" At the present time, DECdns automatically configures over the following LAN devices: EC*, EF*, EL*, ER*, ES*, ET*, EW*, EX*, EY*, EZ*, FA*, FC*, FQ*, FR*, FW*, FX*, FZ*, IC*, IR*, XE*, XQ* 6.9 High Convergence Directories Not Recommended If any of your DECdns directories are set to high convergence (DNS$Convergence = high), Digital strongly recommends that you reset them to medium convergence. The high convergence setting is intended only for temporary use in limited, troubleshooting situations. Directories that are permanently set to high convergence can, in certain cases, cause extensive network and memory usage- possibly leading to a database corruption. Some elements of this behavior are defects that may be corrected in a future release of DECdns. Permanent use of the high convergence setting, however, will continue to be discouraged. 6-4 DECdns To set a directory's convergence to medium, use the following DNS$CONTROL command: dns> set directory DNS$Convergence = medium 6.10 Documentation Correction to Name Resolution Operations Section 2.4.1, How Node Synonyms Work, in the DECnet/OSI DECdns Management guide is incorrect. When DECnet/OSI Session Control receives a node name of 6 alphanumeric characters (one alphabetic character minimum) or fewer that does not contain a leading dot, it first uses local name mapping to resolve the name. If that method fails, Session Control tries to look up the name in the directory referenced by the attribute Session Control Node Synonym Directory, which is typically .DNA_NodeSynonym directory. 6.11 Documentation Correction to "Adding Group Access" Procedure In the DECnet/OSI DECdns Management guide, Section 5.3.2, Adding Access for Your Namespace Administrator Group, the first and second examples under "To Add Full Access" are incorrect. The as group qualifier must be specified as shown in the following corrected examples: dns> add directory . access .DNS_Admin as group for r,w,d,t,c dns> add directory . default access .DNS_Admin as group for r,w,d,t,c 6.12 Documentation Correction to "Denying Group Access" Example In the DECnet/OSI DECdns Management guide, Section 5.2.4, Using Null ACEs to Deny Access, the second example is incorrect. NULL ACEs are only valid for explicit principals. They are not valid for implicit or explicit groups. While it is possible to add such an invalid ACE using DNSCP, the ACS processing ignores it. DECdns 6-5 6.13 Documentation Correction to "Relocating a Clearinghouse" Procedure In the DECnet/OSI DECdns Management guide, Section 9.5, Relocating a Clearinghouse, you must grant the specified DECdns access to both the clearinghouse and the object. The first sentence of Step one, Part A should read as follows: For the dns$server principal on the server, grant read, write, delete, test, and control access to both the clearinghouse and the object. 6.14 Known DECdns Problems You may encounter the following problems: o DNS$Control may return "Syntax Error" if the clerk is disabled. o DNS$Control should not be used to modify the DNA_ NodeSynonym attribute on DECnet node objects. DNS$Control displays the attribute properly, but does not modify it properly. Use the appropriate DECnet node registration tools to modify DECnet data stored in DECdns. o Recreated entries retain the case of the original entry name. o On OpenVMS VAX systems, if you have trouble creating a clearinghouse, make sure that either the DNS$SERVER account (UAF entry) does not exist or its default directory does exist. 6.15 UNKNOWN and WORLD Pseudo-Namespaces The DECdns server now recognizes two predefined names- paces: UNKNOWN and WORLD. The UNKNOWN namespace provides principal names for nodes whose name cannot be determined. If a Phase IV node name cannot be determined with backtranslation, the server generates a name for the node in the form: UNKNOWN:.%Xnnnn 6-6 DECdns (where nnnn is the NSAP of the connecting node). The following is an example principal generated by this situation: UNKNOWN:.%X490004AA00000400FB1020.MCINTYRE The WORLD namespace is used solely in access control sets. The WORLD namespace matches the specified principal in any namespace presented to the server (including the UNKNOWN namespace). For example: FREDCO:.*... matches any principal in the FREDCO namespace. WORLD:.*... matches any principal in any namespace. WORLD and UNKNOWN are ignored by DNS Version 1 servers. They can display as hexadecimal NSCTSs on older DECdns implementations. 6.16 DNS Version 1 and DECdns Version 2 Server Incompatibility With DECdns Version 2 servers on ULTRIX and OpenVMS VAX systems, the DNS$CHDIRECTORIES attribute was added to a clearinghouse object to list the set of directories replicated at that particular clearinghouse. A problem arises when: o You have more than 200 directories stored in the DECdns Version 2 clearinghouse (for example, .eng.host_ch). o You have a DNS Version 1 server replicating the directory containing the clearinghouse object (for example, a DNS Version 1 server replicating the .eng directory). This causes the DNS$CHDIRECTORIES attribute to grow too large to be handled by DNS Version 1 servers. The directory fails to skulk with the following status: "Insufficient local resources at the server node" As a pre-emptive action, this release includes a switch to delete and disable updating of the DNS$CHDIRECTORIES attribute. This attribute is read-only and it in no way affects the proper running of a server. DECdns 6-7 To set the switch, create a file called DNS.CONF in the SYS$SYSDEVICE:[DNS$SERVER] directory and add the following line: dnsd.chdirectories_setting: # where # can be: 0 : Off - The current behavior of updating the DNS$CHDIRECTORIES attribute. 1 : Delete - Delete the DNS$CHDIRECTORIES attribute and never update it. 2 : Auto - Update DNS$CHDIRECTORIES until a size threshold is reached, then delete it. Since the DNS.CONF file gets read once during server startup, you need to stop and then restart the server to change the setting. 6.17 Message Text Change - BADCLOCK The text of the BADCLOCK error has been changed from "Server clocks not synchronized" to "Distributed update contained an invalid timestamp". Although unsynchronized clocks can certainly generate BADCLOCK errors, the problem may be the result of another problem (or the clocks may have been fixed after DECdns detected the problem). The SYS$MANAGER:DNS$SERVER.LOG file often contains additional information about the BADCLOCK error. 6.18 New DECdns Error Message - DNS-E-LOCALNAMEABBR There is a new error message, "DNS-E-LOCALNAMEABBR, Bad local name abbreviation translation". Explanation: A local name abbreviation translation is invalid because it contains invalid characters or because it causes a translation loop. User Action: For OpenVMS, review the logical names in the DNS$SYSTEM logical name table, where local name abbreviation translation is done. For DECnet-ULTRIX, review the /usr/var/dss/dns/dns-names file, which contains the local name abbreviation translations. 6-8 DECdns 6.19 Size and Creation of Clerk Cache File The DECdns clerk has been modified so that it no longer resizes the clerk cache file every time DECdns is started. The DECdns clerk now calculates the correct size for the cache file only when it finds no cache file and must create a new one. If the amount of physical memory available to a system has changed or if the GBLPAGFIL system parameter has been modified, check the SYS$MANAGER:DNS$ADVER_ERROR.LOG file. The DECdns clerk indicates in this file if it has calculated a new recommended cache size. When you see the message "Insufficient Global Page File Limit - no cache", there were fewer than 10 GBLPAGFILs available and the cache file was not created. When this happens, you need to increase GBLPAGFIL, run AUTOGEN, and reboot your system to get a functioning DECdns clerk. The formula to determine the size of the cache file is as follows: SIZE (in blocks) = MIN (1000, .5% Total memory) If SIZE exceeds 75 percent of the available GBLPAGFIL, then it is set to that figure, so as to not use up all of the available GBLPAGFIL. For OpenVMS systems, the maximum SIZE value is 512 MB. If the recommended change in the size of the cache file is substantial and you wish to have DECdns use the new cache size, then follow these steps: 1. Shut down DECdns. 2. Delete the existing cache files (SYS$SYSTEM:DNS$CACHE.*). 3. Reboot the system. Since the cache sizing algorithm must run on a fresh boot of OpenVMS, it is important to reboot the system without first restarting DECdns. 4. DECdns can be started during the reboot or at any time thereafter. DECdns 6-9 The first time DECdns Version 2 runs on a system (or if DECdns runs and finds the cache file missing), the ad- vertiser creates the file SYS$SYSTEM:DNS$CACHE.0000000001 (if it does not already exist). This file is the backing store file for the DECdns clerk cache. The backing store update interval is 30 minutes. The extension part of the file name (0000000001) is incremented by 1 at each interval and is updated in the associated file SYS$SYSTEM:DNS$CACHE.VERSION. If you want to start with an empty cache, delete both files with the following command before starting the clerk: $ DELETE SYS$SYSTEM:DNS$CACHE.* 6.20 Removing Obsolete DNS$CACHE Files Multiple obsolete copies of the DECdns clerk cache backing store file (SYS$SYSTEM:DNS$CACHE.000000000n) can, under unusual circumstances, accumulate and cause disk space problems on the system. The backing store file is updated every 30 minutes, at which time the extension part of the backing store file name (000000000n) is incremented by 1 and the backing store file name is updated in the associated file (SYS$SYSTEM:DNS$CACHE.VERSION). DECdns uses only the DNS$CACHE.VERSION file and the one or two DNS$CACHE.000000000n files referenced in DNS$CACHE.VERSION. DECdns normally deletes prior unreferenced versions of the file. If you perform a directory of the SYS$SYSTEM: directory and see more than one backing store file, type the DNS$CACHE.VERSION file to see which backing store files DECdns is currently using and delete all prior DNS$CACHE.000000000n files from the directory. 6.21 Clarification of WORLD Access in DNS and DECdns The DNS Version 1 principal expression *::* and the DECdns Version 2 principal expression .*... permit access to any user on any node, but only within the particular namespace in which the ACEs containing these expressions were created. 6-10 DECdns Because users are not required to enter a namespace nickname as part of a principal expression and, because DNS Version 1 does not display the namespace nickname associated with the principal expression of ACEs, many DNS Version 1 users have logically assumed that both *::* and .*... can be interpreted as any user, on any node, in any namespace. This is not the case. (See Section 6.15 of these release notes.) 6.22 Documentation Correction to DELETE CHILD Command Example The command example appearing on the reference page for the delete child command in Chapter 11 of the DECnet/OSI DECdns Management guide is incorrect and should read as follows: dns> delete child .sales.east No error message is displayed. 6.23 DECdns Servers Support DNS$SkulkStatus Attribute DECdns servers now support a directory attribute called DNS$SkulkStatus, which provides details on why a directory skulk failed. Use the SHOW REPLICA command, directed at the master replica's clearinghouse, to obtain this information. Information presented in this attribute is also recorded in the server's DNS$SERVER.LOG file. 6.24 Default Parameters for Process Limits on DECdns Servers This section describes several default parameters for process limits on NET$ACP and DNS$SERVER. o When FILLM is set to 100 on a DECdns server, it limits the number of DECdns clerks that can connect. This causes the DECdns clerk to log a USERREJECT error into the DNS$CHFAIL.LOG file when the limit of 100 connections is exceeded. You can raise this limit by modifying the line in SYS$STARTUP:DNS$SERVER_ STARTUP.COM which specifies /FILLM=100. o When the ASTLM on NET$ACP is set to 100, it limits the number of connection setup logical links NET$ACP can process at one time. DECdns 6-11 o When NET$ACP runs out of ASTs, FILLM on the NET$ACP is closely following ASTLM towards 0. Both parameters must be raised together. o The VIRTUALPAGCNT limit for nodes with DECdns servers must be approximately 10,000 blocks greater than the DECdns checkpoint file size in blocks. The page files on the node must also be sized accordingly. If the system has more than one page file, the individual page files must be at least as large as the checkpoint file. Since each OpenVMS process is assigned to a single page file, the total combined size of the page files is not useful to DECdns since it is only able to use the capacity of one of them when it reads the entire clearinghouse checkpoint file into memory. Note also that DECdns is not guaranteed the larger page file if one page file is sufficiently large and others are not. 6-12 DECdns 7 ________________________________________________________________ DECdts 7.1 Automatic Time Zone Changes on Rebooting Clusters If all members of a cluster are down when Daylight Savings Time takes effect, and automatic time zone changes are enabled, then members may reboot with the incorrect local time. If you anticipate that the cluster will be down during the change to or from Daylight Savings Time, you should disable automatic time zone changes and make the changes manually. 7.2 Unknown LAN Device Types DECdts automatically configures over the following LAN devices: EC*, EF*, ES*, ET*, EX*, EZ*, FC*, FX*, FZ*, XE*, XQ* To configure DECdts over any other device type, use the system logical name DTSS$ETHERNET_DEVICE, where XY defines the new device type: $ DEFINE/SYSTEM DTSS$ETHERNET_DEVICE "XYA0" 7.3 Configuring LANs with Global Servers Unreliable synchronizations can occur on LANs that contain a single global server and one or two additional local servers. The local servers on the same LAN as the global server can contact it twice: once using DECnet and again using LAN protocols. If the servers required value for the local servers is set to 3, the global server can contribute as many as two of three values used to compute a new time for a local server, thereby reducing fault tolerance and steering a local server's time. DECdts 7-1 To prevent this problem, add more local servers to the LAN, so that there is a minimum of four servers, including the global server; then set the servers required value to 4 on each server. 7.4 Corrections for CHANGE DTSS Command The syntax for the NCL CHANGE DTSS command is: ncl> change [node node-id] dtss epoch integer [, time absolute-time] Although the epoch argument is required, NCL does not check for its value. If the epoch argument is missing, NCL returns an "invalid itemlist" error. If you get this error message, reenter the CHANGE DTSS command and specify the epoch argument. Examples of the CHANGE DTSS command appearing in DECnet /OSI DECdts Management that involve changing both a server's epoch and time values are incorrect. The documentation fails to specify that you must include a comma between the epoch value and the time argument on the command line. The following example shows the correct syntax for this iteration of the CHANGE DTSS EPOCH command: ncl> change dtss epoch 1, time 1991-03-21-16:07:45.00-07:00I0.00 7.5 Advertising Global Servers When advertising a DTSS global server into the namespace, you need write access to the directory where the DTSS object is written. The following DECdns commands add access rights to the dtss global server directory. On DECdns servers at Version 2.0 and later, enter the following commands: dns> add directory WAK:.DTSS_GlobalTimeServers - access wak:nodename.DNA$SessCtrl for r,w,t,c dns> add directory WAK:.DTSS_GlobalTimeServers - access wak:nodename.system for r,w,t,c In these examples, "nodename" is the full name of your local system. 7-2 DECdts On DECdns servers before Version 2.0, enter the following commands: dns> add directory WAK:.DTSS_GlobalTimeServers - access wak:dns$iv.nodename.DNA$SessCtrl for r,w,t,c dns> add directory WAK:.DTSS_GlobalTimeServers - access wak:dns$iv.nodename.system for r,w,t,c In these examples, "nodename" is the node synonym of your local system. 7.6 Advertising Global Servers Document Change There is incomplete information in Section 3.5.2 of the DECnet/OSI DECdts Management guide. The passage reads: dns> add directory WAK:.DTSS_GlobalTimeServers - access .mynode.DNA$SessCtrl for r,w See Section 7.5 of these release notes for the correct wording. 7.7 Documentation Addition for SHOW DTSS Local and Global Server Commands When you enter the show dtss local server * command or the show dtss global server * command at a dtss local or global server, the list does not include the server itself. To verify what DECdts role the current node is running, enter the following command: ncl> show dtss type 7.8 Documentation Correction to SHOW DTSS Command Example The documentation (DECnet/OSI DECdts Management) shows an incorrect example of using the SHOW DTSS command to check the value of the synchronization hold down attribute. If you abbreviate the attribute name as shown in the example, (show dtss sync hold down), you receive an "unrecognized command" error message. To execute this SHOW command successfully, you must spell out the attribute name as follows: ncl> show dtss synchronization hold down DECdts 7-3 7.9 The DTSS Synchronization Completed Event Is No Longer Blocked by Default The dtss event, Synchronization Completed, is no longer blocked by default. (In previous releases this event was blocked during DTSS startup.) The block command has been added to the NET$EVENT_LOCAL.TEMPLATE file. This is consistent with the method used to block other events which may occur frequently. 7.10 Document Change - Interoperation with NTP The DECdts kit now contains two NTP time-provider programs: o dtss_ntp_provider.c for use on ULTRIX systems o dtss$ntp_provider.c for use on OpenVMS systems Appendix C (Interoperation with NTP) in DECnet/OSI DECdts Management explains how to use both DECdts and NTP in the same DECnet/OSI for ULTRIX network. The appendix applies as written for ULTRIX systems. With the time-provider program name dtss$ntp_provider.c substituted for dtss_ntp_ provider.c, the appendix applies for OpenVMS systems. 7.11 Using a Time-Provider on DECdts Server Nodes On a node with a DECdts server and a time-provider, you must protect the DECdts server against time faults introduced by the time-provider. If the time-provider returns an invalid time, the DECdts server modifies its time incorrectly. To improve the fault tolerance of the DECdts server, set the system logical name DTSS$_TP_MAXERROR to a value less than 300 seconds. For example: $ DEFINE/SYSTEM DTSS$_TP_MAXERROR 299 If the difference between the local time and the value returned by the external clock is greater than the interval represented by DTSS$_TP_MAXERROR, then the DECdts server ignores the value returned by the external clock. The DTSS$_TP_MAXERROR value depends on the type of external clock used. It should not exceed 300 seconds 7-4 DECdts because DECdns requires synchronization to within 300 seconds. The DECdts interface code examples in SYS$SYSROOT:[SYSHLP.EXAMPLES.DTSS] show how to use this and other time-provider logical names. The ACTS Provider example uses a command line interface rather than OpenVMS logical names. 7.12 Time-Provider Interface (TPI) Advisory Future versions of DECdts that support additional protocols will use a new TPI. To ease future porting of time-provider programs to new protocol versions, use the sample time-provider programs that are supplied with the kit, with as few modifications as possible. 7.13 Update to List of Supported Radio Receivers The following note updates information contained in Appendix B, Time-Providers and Time Services, in the DECdts Management guide. Table B-3, Radio Receiver Manufacturers, lists supported radio receivers by manufacturer. Update this list by replacing "Spectracom 8170" with "Spectracom Netclock /2". DECdts 7-5 8 ________________________________________________________________ FTAM 8.1 Installation Please read these notes and the DECnet/OSI for OpenVMS Installation and Configuration manual completely before performing the installation. 8.1.1 OSIF$ CONFIGURE.COM Procedure To assure that the proper accounts are on the system, execute the SYS$STARTUP:OSIF$CONFIGURE.COM procedure following the PCSI installation. This procedure gives you the option of running the Installation Verification Procedure (IVP). 8.1.2 Installation Verification Procedure (IVP) The FTAM/IVP is not run automatically by the installation procedure. To run the IVP, you must execute the following command: $ @sys$test:osif$ivp.com Or, you can run it by means of the SYS$STARTUP:OSIF$CONFIGURE.COM procedure. 8.2 Documentation Section 10.4 in DECnet/OSI FTAM and Virtual Terminal Use and Management shows the following incorrect command line: $ @sys$startup:osif$start.com ! osak start-up command file The correct command line is: $ @sys$startup:osak$start.com ! osak start-up command file FTAM 8-1 8.3 Size Restriction for FTAM-3 Fixed Files Both NIST phase 2 and phase 3 agreements and the ISO /IEC ISP 10607-3 have size restrictions. Therefore, if an FTAM-3 fixed file has records larger than 6.5K, it cannot be sent because fixed records cannot be segmented. As a result, save sets that have block sizes greater than 6.5K must be unwound and rewound with block sizes less than 7K. 8.4 DTE Address Logical For X.25 access, you must define a logical in the osit$names logical name table. For example, to define a logical called "REMOTE_DTE" in the osit$names table, enter: $ define/table=osit$names REMOTE_DTE 031346174301212 This logical, REMOTE_DTE, in the example provided, defines the DTE of the peer system. The logical is then specified in the NSAP field of the sys$system:isoapplications.dat file, in place of the actual DTE. An example of an alias definition in sys$system:isoapplications.dat using the example provided might be: FTAM_ALIAS :FTAM:::%x0001.%x0001.%x0001.REMOTE_DTE,provider=osi, template=osit$loop_x25: 8.5 DAP/Gateway There is currently no support for the append function in the DAP/FTAM gateway. 8.6 OpenVMS File Protection Assignment Upon File Creation The behavior in assigning of FTAM file protection on remote OpenVMS systems has been modified. In the past, when an FTAM user created a remote file on an OpenVMS system, the file protection was assigned by RMS in one of the following ways: o Using the protection assigned to an existing file of the same name o Using the default file protection of the directory 8-2 FTAM o Using the process-default protection FTAM no longer assigns file protection for the WORLD, GROUP, and SYSTEM bits. FTAM maps permitted-action bits against only the OWNER group in the following way: -------------------------------+--------------------------------------------- FTAM Permitted Action: | OpenVMS Filestore Protection (OWNER only) -------------------------------+--------------------------------------------- read | read read-attribute | traversal | reverse-traversal | random-order | -------------------------------+--------------------------------------------- insert | write replace | extend | erase | change-attribute | -------------------------------+--------------------------------------------- delete-file | delete -------------------------------+--------------------------------------------- 8.7 File Error Recovery The docket information maintained to perform an error recovery is now stored in sys$system:ftam_recovery.dat. This file should be truncated or deleted periodically by the OpenVMS system manager. This file maintenance should be done when no active FTAM responders are being used as part of FTAM associations. For Class-3 recoveries, the user has the option of defin- ing logicals to customize recovery-related functionality. The logicals and their defaults are listed as follows: FTAM 8-3 __________________________________________________________ Logicals______________Defaults____________________________ OSIF_REINIT_MAX_ Default is 5. The number of times RETRY that the initiating entity will "retry" to re-establish the association with the responding entity after a Class-3 failure. OSIF_REINIT_SLEEP Default is 180 seconds. The number of seconds that the initiating entity will "sleep" or wait after a Class-3 error is received and before attempting to recover the association. OSIF_REINIT_TIMEOUT Default is 120 seconds. The number of seconds that the initiating entity will wait for a response from the responding entity after attempting to recover the association by sending an f- initialize-request. OSIF_REDIRECT_ Default is 1500 seconds. The number TIMEOUT of seconds that the responding entity will wait for the initiating entity to recover the association ______________________before_timing_out_and_exiting.______ 8-4 FTAM 9 ________________________________________________________________ FTAM Application Programming Interface (API) 9.1 FTAM Application Programmer Interface (API) As of this version, FTAM includes support for the FTAM API component which was previously shipped as part of the OSI Application Developer's Toolkit. 9.2 Changed OSIF.H osif_ae_entry Structure With the FTAM V3.2 API, the osif_ae_entry structure has been enhanced to provide additional addressing capabilities. The change affects the osif_ae_entry structure, and adds two new fields to that structure: osif_nsap_queue osif_template_queue These changes require that programs written to earlier versions of the API be recompiled and relinked. However, no code changes are necessary unless you want to use the new fields. The FTAM API will check the nsap_queue[0].nsap.length field to determine which API format to use. If the value of 'length' is non-zero, then the API will assume that the FTAM V3.0 format is being used, and the new fields in the osif_ae_entry structure will be ignored. If the value of 'length' is zero, then the API will assume that the V3.2 format is being used, the nsap_queue array will be ignored, and the API will look for information in the new fields. The FTAM V3.2 format provides the ability to disassociate specific NSAPs from specific templates (that is, there is no longer a one to one correlation between NSAP and template as required by the V3.0 interface). The user is expected to simply provide a list of potential NSAPs, FTAM Application Programming Interface (API) 9-1 along with the type of network service that each NSAP is expected to use. The OSAK constants OSAK_C_CLNS, OSAK_C_CONS or OSAK_C_ RFC1006 (note that OSAK_C_RFC1006 is only valid for use on DECnet/OSI for DEC OSF/1 or DECnet/OSI for OpenVMS Version 6.0 or later) may be used to indicate whether the NSAP is appropriate for a CLNS, CONS or RFC1006 network service. In addition to the list of NSAPs, the user also provides a list of potential transport templates. When the FTAM API passes the NSAP and Template lists to OSAK, OSAK attempts to establish an association with each appropriate NSAP /Template pair. For example, suppose two NSAPs and two templates are passed: NSAP list Template list %x21 (CLNS) OSIT$LOOP_CONS %x22 (CONS) OSIT$LOOP_CLNS OSAK matchs the first Template in the list with an appropriate NSAP (in this case, the second NSAP in the list), and constructs a final address to attempt an association. Using our example, the address looks something like: OSIT$LOOP_CONS%x22 If the association attempt fails with this particular template /NSAP pair, OSAK continues searching the NSAP list looking for another NSAP appropriate for a CONS connection. Once OSAK attempts all possible combinations within the NSAP list for the first template, OSAK then attempts an association with the next template in the template list, repeating the template/NSAP pairing operation until an association is established, or until all valid combinations of template/NSAPs have been attempted. 9.3 Documentation Notes The following section discusses issues specific to the documentation. 9-2 FTAM Application Programming Interface (API) 9.3.1 osif_deassign_port Incorrectly Documented The osif_deassign_port is incorrectly documented as having only three arguments. The example programs provided in the documentation show the correct usage of osif_deassign_ port. The osif_deassign_port call should be documented as follows: FTAM Application Programming Interface (API) 9-3 osif_deassign_port ________________________________________________________________ osif_deassign_port __________________________________________________________ Argument______________Data_Type__________Access___________ port_id unsigned longword read only buffer_list pointer write only port_flags unsigned longword read only error_code____________unsigned_longword__write_only_______ C Binding: osif_deassign_port( port_id, buffer_list, port_flags, error_code ) unsigned port_id; struct osif_buffer_list *buffer_list; unsigned port_flags; unsigned *error_code; Arguments port_id This argument is a reference to a communication port. buffer_list This argument contains a list of the buffers previously owned by the FTAM API that are being returned to the user upon deassignment of the port. port_flags This argument has a value of OSIF_ASSIGN_INITIATOR or OSIF_ASSIGN_RESPONDER and indicates if the intiator or the responder is using the osif_deassign_port call. This argument should be the same as the port_flags argument passed to the osif_assign_port call. 9-4 FTAM Application Programming Interface (API) osif_deassign_port error_code This argument provides further information if the status returned from the call is OSIF_FAILURE. FTAM Application Programming Interface (API) 9-5 9.3.2 FTAM Programming The FTAM Programming manual describes FTAM parameters that are part of attribute groups not supported in the FTAM API code. Parameters for unsupported functions should not be used when programming with the FTAM API. 9.3.3 Unsupported Functions The following list describes unsupported functions. o The use of abstract-syntax names and constraint set names causes unknown results and should not be used. o The osif_protocol_error vector and the osif_prot_error_count variable will not be filled in if OSIF_PROTOCOL_ERROR is returned by any function call. OSIF_PROTOCOL_ERROR is used to signal that an error has occurred at a lower layer. The osif_protocol_error vector is used to list all the errors that have occurred in the lower layers. This functionality will be added in a later release. o The FTAM API only supports a buffer list with one buffer. In other words, one P_DATA must be contained in one user buffer. For this release, the size of user buffers passed to the FTAM API must be at least 8K bytes. If the buffer is less than 8K, then the user receives the OSIF_NOBUFFS error for the osif_get_event function call. 9.3.4 Problems The following list describes known problems. o If a contents type list is not specified in the F-INITIALIZE-request primitive, the FTAM API sends all the supported document types. o The checkpoint window parameter will be defaulted to one even though the Recovery functional unit is not supported. o An error should be returned by the service provider when a universal class number is specified with FTAM-3 files on F-OPEN and F-CREATE requests. Currently, the universal class number information is ignored and no error is returned. 9-6 FTAM Application Programming Interface (API) o The osif_fadu_locking parameter of the F-OPEN-request primitive is specified in the documentation and the osif.h file, but it is not used by the FTAM API. 9.3.5 Suggestions The following list describes recommendations and suggestions. o Use the osif_give_buffer call before each call to osif_get_event. osif_give_buffer(...) osif_get_event(...) o Keep a copy of ISO 8571 nearby for quick reference. The FTAM API is a low-level API and assumes the developer has a good working knowledge of the FTAM standard. 9.4 FTAM API Example The example programs are in the files: sys$examples:osif_api_exam.c sys$examples:osif_api_resp.c There is also a makefile in the file: sys$examples:osif_api_bld.com The example programs can be compiled and linked by issuing the command: @sys$examples:osif_api_bld.com The example programs will create a file on the remote system. The following variables must be changed to match information specific to your systems: LOCAL_PSAP This should be set to your local presentation address. REMOTE_PSAP This should be set to the presentation address of the remote system. init_id This should be set to the initiator identity required by the remote system. FTAM Application Programming Interface (API) 9-7 fs_passwd This should be set to the filestore password required by the remote system. 9.4.1 Access to the Contents Type Database FTAM must be able to find the Contents Type Database. This database is contained in the file SYS$SYSTEM:OSIF$OIDS.TXT. You may either create the logical FTAMOIDS that points to the database, or copy the database to the file FTAMOIDS (in the directory where the API application is run). 9.4.2 FTAM API Message Files To access the FTAM message files, enter the commands: $ SET COMMAND SYS$LIBRARY:OSIF$FMSG_MF.EXE $ SET COMMAND SYS$LIBRARY:OSIF$ASN1_MF.EXE 9.4.3 Privileges Required to Use OSAK You must have the following privileges turned on when you run an FTAM API program, otherwise OSAK will not run: NETMBX,TMPMBX,SYSNAM,SYSLCK,PRMMBX 9-8 FTAM Application Programming Interface (API) 10 ________________________________________________________________ Virtual Terminal 10.1 Local Command Mode The following sections discusses issues specific to local command mode. 10.1.1 CTRL-@ The SET command will not accept CTRL-@ as a valid value for the break, command, or disconnect characters. 10.1.2 Amode Repertoire The SEND command may incorrectly indicate that a character is not in the Amode-default repertoire. 10.2 Initiator The /trace option is not supported. 10.3 Responder The Virtual Terminal responder may stop accepting connections after several connections have already been established and aborted. If you encounter this symptom, you can remedy the problem by stopping and restarting VT. To stop VT, enter: $ @sys$manager:vt_stop.com To start VT, enter: $ @sys$startup:vt_start.com Virtual Terminal 10-1 10.4 Gateways The following sections discuss issues specific to the gateways. 10.4.1 VT/LAT Gateway Will Hang The VT/LAT gateway will hang if an unknown LAT service is provided at the following prompt: Enter LAT Service name: If the VT/LAT gateway hangs for this reason, it is best to stop the VT/LAT gateways and restart them. To stop the VT/LAT gateways, enter: $ @sys$startup:vt_stop lat To restart the VT/LAT gateways, enter: $ @sys$startup:vt_start lat 10.4.2 Starting VT/LAT and Telnet Gateways (Alpha Only) To start the gateways while the VT responder is running, execute the following commands. To start the VT/LAT and LAT/VT gateways, enter: $ @sys$startup:vt_start lat To start the VT/TELNET and TELNET/VT gateways, enter: $ @sys$startup:vt_start telnet 10.5 Interoperability with DECnet/OSI Virtual Terminal Version 1.0 for ULTRIX The following sections discuss interoperability with ULTRIX systems. 10.5.1 SEND VT-BREAK A Virtual Terminal association with a VAX ULTRIX system will hang if you attempt to log out after issuing a SEND VT-BREAK command. The association can be terminated by using the QUIT command from Local Command Mode. 10-2 Virtual Terminal A Virtual Terminal responder on MIPS ULTRIX will abort the Virtual Terminal connection if it receives an incoming vt-break request. 10.5.2 SEND SYNCH The SEND SYNCH command will not work over a Virtual Terminal association with a VAX ULTRIX system. The following message displays instead: %OSAK-E-INVFUNC, the call is invalid 10.6 Interoperability with DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX The following sections discuss interoperability with OpenVMS VAX systems. 10.6.1 SEND SYNCH DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX does not properly handle updates to the SY control object. The DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX responder will abort the Virtual Terminal Connection if it receives and SY control object update. 10.6.2 VT-BREAK DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX does not support the vt-break service as a responder. The DECnet/OSI Virtual Terminal Version 1.0 for OpenVMS VAX responder will abort the Virtual Terminal association if it receives a vt-break indication. Virtual Terminal 10-3 11 ________________________________________________________________ OSAK This chapter describes issues specific to this version of the DECnet[TM]/OSI[R] OSAK software. 11.1 New features This section contains information about new features in the OSAK software and programming interfaces. 11.1.1 OSAK Application Programming Interface (API) This version of the DECnet[TM]/OSI[R] OSAK software includes support for the OSAK API, which previously shipped in the OSI Application Developer's Toolkit. 11.1.2 New OSI Session Programming Interface This version of the software includes a new programming interface to the OSI session layer (the SPI). This interface is a replacement for the existing backwards- compatible interface to OSAK Version 1.1. More information about this interface is given in the books OSAK Programming and OSAK SPI Programming Reference. 11.2 Known Problems and Restrictions This section contains details of known problems and restrictions in the OSAK software and the OSAK programming interfaces. 11.2.1 OSAK Software OSAK 11-1 11.2.1.1 Session Disconnect Timer Not Supported This version of the OSAK software does not support the session disconnect timer. 11.2.1.2 NCL Does Not Display Form 1 AE-Titles Correctly NCL does not display a Form 1 AE-Title correctly. Instead, it displays an object identifier. 11.2.1.3 Enumerated Data Types Not Decoded The OSAKtrace utility does not decode enumerated data types. 11.2.1.4 OSAKtrace Output Alignment Problem The trace analyser does not correctly align its output when tracing an AE-title in Form 1 format. However, no information is missing from the output. 11.2.1.5 Use of NCL for Remote Management of OSAK Software This version of the OSAK software does not support NCL management of OSAK from remote DECnet/OSI systems. If you attempt to use NCL to find out information about the OSAK component on another DECnet/OSI host system the command will fail and the following NCL error message will be returned: command failed due to: return data corrupt or incorrectly encoded on remote system Examples of NCL commands that will fail include:- NCL> show node osak protocol versions NCL> show node osak all where is a remote DECnet/OSI host system. 11.2.2 OSAK API and SPI Programming Interfaces 11-2 OSAK 11.2.2.1 Incorrect Decoding of SET The OSAK API interface does not always correctly decode the mode selector 'SET' in a CP-PPDU (A-ASSOCIATE indication) or a CPA-PPDU (A-ASSOCIATE-ACCEPT confirm). If '[0] IMPLICIT Mode-selector' comes after '[2] IMPLICIT SEQUENCE' the OSAK interface does not decode the mode selector, but passes it to your application as user data. 11.2.2.2 Session Segmentation Not Supported This version of the OSAK interface does not support session segmentation. This does not hinder segmentation by the user. For an explanation of the two sorts of segmentation, see the manual OSAK Programming. 11.2.2.3 Multiple Upper Layer Addreses Not Allowed on a Transport Selector You should not use the same transport selector (TSEL) on more than one process. Any TSEL that your application uses should be unique. Re-use of a TSEL results in one of two secondary status codes in the status_block parameter. The primary status in each case is OSAK_S_INVAEI. The two possible secondary codes are: o OSAK_S_TSELINUSE Indicates that a TSEL in the local_aei or calling_aei parameter is already being used on another port or by another application. o OSAK_S_MULTADDR, multiple upper layer addresses for t-selector Indicates that you have opened more than one OSAK responder port within the same process using the same TSEL, but a different SSEL or PSEL. This is not allowed. If you want to specify a different SSEL or PSEL, you should also specify a different TSEL. OSAK 11-3 11.2.2.4 Support for Programming Languages 11.2.2.5 Receiving Odd Length NSAPs If the OSAK interface passes to the application an NSAP preceded by a zero, the zero can be ignored. This additional digit is added during the translation process if a NSAP has an odd number of characters. 11-4 OSAK