DECnet/OSI for Digital UNIX Release Notes August 1997 Revision/Update Information: This is a new document. Operating System: Digital UNIX Operating System V3.2 Software Version: DECnet/OSI V3.2C for Digital UNIX © Digital Equipment Corporation 1997. All Rights Reserved. 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. The following are trademarks of Digital Equipment Corporation: DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DEC WANrouter, DECwindows, DIGITAL, DNA, OpenVMS, PATHWORKS, POLYCENTER, 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 Co. Ltd. All other trademarks and registered trademarks are the property of their respective holders. ________________________________________________________________ Contents 1 Introduction 1.1 Problems Resolved............................... 1-2 1.1.1 Problems Resolved in Version 3.2A ............ 1-2 1.1.2 Problems Resolved in Version 3.2B ............ 1-3 1.1.3 Problems Resolved in Version 3.2C ............ 1-4 1.2 Changes in Version 3.2B......................... 1-5 1.3 Network Management Graphical User Interface..... 1-5 1.4 DECdns Server................................... 1-6 1.5 DECnet over TCP/IP.............................. 1-6 1.5.1 Configuration Steps for DECnet/OSI over TCP/IP........................................ 1-7 1.5.2 Disabling DECnet/OSI over TCP/IP ............. 1-7 1.5.3 DOTI Tracing Support Added to CTF ............ 1-7 1.6 FDDI Circuits................................... 1-7 1.7 Dynamic Kernel and SMP Support.................. 1-7 1.8 Header Files for OSAK and ROSE Moved............ 1-8 2 Installation Notes 2.1 Using DECnet with Enhanced Security............. 2-1 2.2 Installation Message............................ 2-1 2.3 Before Upgrading the Digital UNIX Operating System.......................................... 2-1 2.4 RIS Installation Issues......................... 2-2 2.5 Restart Xserver to Display X Window System Applications.................................... 2-3 2.6 Removing the DECnet/OSI Software................ 2-3 2.7 NSAPs Using Decimal DSP Syntax.................. 2-3 2.8 Kernel rebuild if using X.25.................... 2-3 iii 3 Network Management 3.1 NCL CMIP Routines............................... 3-1 3.2 Using Wildcards May Cause NCL to Hang........... 3-1 3.3 Event Logging-Disabling the Event Dispatcher.... 3-1 3.4 MOP Known Problem............................... 3-2 4 General Software Notes 4.1 REMUSER Environment Variable.................... 4-1 4.2 OBJECT Environment Variable..................... 4-1 4.3 No Default Object............................... 4-1 4.4 Problems with the DECwindows Session Manager.... 4-2 4.5 Using the DECnet-Internet Gateway............... 4-2 4.5.1 PWD and XPWD Commands Not Implemented ........ 4-2 4.5.2 Telnet ....................................... 4-2 4.5.3 Using the Gateway for Remote Login ........... 4-2 5 Programming Issues 5.1 Using the getnodename Subroutine................ 5-1 5.2 XTI Known Problems.............................. 5-1 6 Unsupported Utilities 6.1 Unsupported Utilities Subset.................... 6-1 6.2 tell............................................ 6-1 6.3 nfi............................................. 6-2 6.4 gatewayd........................................ 6-4 6.5 WWW (World Wide Web) gateway to DECnotes........ 6-4 6.5.1 Configuring webnotesd ........................ 6-5 6.5.2 Using webnotesd .............................. 6-5 6.6 DECnotes Clients................................ 6-6 6.7 Poor Man's Routing (PMR) for Mail-11/CTERM/DAP.. 6-7 6.7.1 Mail-11 ...................................... 6-7 6.7.2 CTERM ........................................ 6-7 6.7.3 DAP .......................................... 6-7 6.8 Converting node::user to user@fullname.dnet..... 6-8 iv 7 DECdns 7.1 DECdns Changes for Version V3.2B................ 7-1 7.1.1 DECdns Server Changes for Version 3.2B ....... 7-1 7.1.2 DECdns Clerk Changes for Version 3.2B ........ 7-2 7.2 DECdns Server Joining Existing Namespace........ 7-3 7.3 Limitation for Number of Members in a Single Group........................................... 7-3 7.4 Location of DECdns Sockets...................... 7-4 7.5 Location of DECdns Clerk Backing File........... 7-4 7.6 DECdns Clerk Software on Nodes with Extended Addresses....................................... 7-4 7.7 Problem with dump dns clerk cache Command....... 7-5 7.8 High Convergence Directories Not Recommended.... 7-5 7.9 Documentation Correction to Name Resolution Operations...................................... 7-5 7.10 Documentation Correction to "Adding Group Access" Procedure............................... 7-6 7.11 Documentation Correction to "Denying Group Access" Example................................. 7-6 7.12 Replicating the DECnet/OSI Directories.......... 7-6 7.13 Show Clearinghouse Command Can Produce Errors... 7-7 7.14 Clear Clearinghouse Command Gives Spurious Error........................................... 7-7 7.15 Clerk Not Enabled Error Message................. 7-7 7.16 Clarification of "World" Access in DNS and DECdns.......................................... 7-7 7.17 Documentation Additions to Clearinghouse Creation Procedure.............................. 7-8 7.18 Documentation Correction to delete child Command Example......................................... 7-8 8 DECdts 8.1 Changing the Time Differential Factor (TDF)..... 8-1 8.2 Time-Provider Interface (TPI) Advisory.......... 8-1 8.3 Starting a Time-Provider........................ 8-2 8.4 Update to List of Supported Radio Receivers..... 8-2 v 9 FTAM and Virtual Terminal 9.1 FTAM............................................ 9-1 9.1.1 Property List Support ........................ 9-1 9.1.2 Responder Logging Support .................... 9-2 9.2 Virtual Terminal................................ 9-3 10 OSAK 10.1 New features.................................... 10-1 10.1.1 OSAK Application Programming Interface (API)......................................... 10-1 10.1.2 New OSI Session Programming Interface ........ 10-1 10.1.3 Listen on Both RFC1006 and OSI Transport ..... 10-1 10.2 Programming Interface Changes................... 10-2 10.2.1 Called_aei Parameter on A-ASSOCIATE and S-CONNECT Indication Events................... 10-2 10.2.2 New Status Code .............................. 10-2 10.2.3 ROSE Minimum Workspace Increased ............. 10-2 10.3 Problems Resolved............................... 10-3 10.3.1 Wrong NSAP No Longer Output to OSAKtrace File.......................................... 10-3 10.3.2 Transport Template Settings Honored .......... 10-3 10.3.3 Transport Congestion Problems Relieved ....... 10-3 10.4 Known Problems and Restrictions................. 10-3 10.4.1 Incorrect Information May Be Logged To OSAKtrace..................................... 10-4 10.4.2 Closing Port After a Redirect Request ........ 10-4 10.5 Documentation Corrections....................... 10-4 10.5.1 Using OSAK over RFC1006 ...................... 10-4 10.5.2 Compiling API, ROSE, and SPI Applications .... 10-5 10.5.3 Linking API, ROSE, and SPI Applications ...... 10-5 vi 1 ________________________________________________________________ Introduction The DECnet/OSI V3.2 for Digital UNIX AXP software product is an end-node implementation of the Digital Network Architecture (DNA) for the Digital UNIX operating system. Digital has renamed its UNIX-based product from DEC OSF/1 to Digital UNIX. Any documentation or software references to DEC OSF/1 are synonymous with the term Digital UNIX. New functionality in this release includes: o Network Management Graphical User Interface o DECdns Server o DECnet over TCP/IP - Domain Name Service - Applications - CTF support The following section provides release notes for mandatory update (MUP) Version 3.2A: - Section 1.1.1 for problems resolved The following sections provide release notes for mandatory update (MUP) Version 3.2B: - Section 1.1.2 for problems resolved - Section 1.2 for changes - Section 2.1 for enhanced security installations - Section 7.1 for DECdns changes - Chapter 9 for FTAM changes Introduction 1-1 The following section provides release notes for mandatory update (MUP) Version 3.2C: - Section 1.1.3 for problems resolved 1.1 Problems Resolved 1.1.1 Problems Resolved in Version 3.2A o Routing Packet fragmentation was not being done correctly. This would cause "Bad Packets Received, Incorrect Checksum" events to be generated, and also would prevent data from being transferred over links that required the use of fragmentation. Routing was not working over Token Ring circuits. Both routing items have been fixed. o RFC 1006 The TPDU size negotiated with remote systems would sometimes be incorrect. o Token Ring It was not possible to set a Token Ring station address using ncl. This has been corrected. o NCL If ncl is invoked with a single command (e.g. ncl show nsp), it will now exit with a status of 0 if the command can be succesfully parsed, and a status of 1 if it cannot. Previously it would always exit with a status of 0. Ncl could core dump when attempting to process very large integers. On occasion, ncl would fail to display some of the error information associated with a failed command. These problems have been fixed. o dna_decdns_createns This utility has been changed so that user root on the local node is now added automatically to the DNA Register access control group in any new name space that is created. 1-2 Introduction o DECdns Both a memory leak and a memory corruption problem have been fixed. 1.1.2 Problems Resolved in Version 3.2B o RFC 1006 There was a memory corruption problem that would have caused system crashes. The typical stack trace had some mbuf manipulation on the stack. There was a memory leak that led to large amounts of system memory to be tied up in mbufs. Certain other implementations of RFC 1006 could not consistently connect to a DIGITAL-UNIX system. The success or failure depended on how the packet fragmentation was done. o DOTI (DECnet over TCP/IP) There was a problem during the system boot related to the timing of certain kernel events. o OSI Transport The system could crash if DECnet were shut down and restarted while X.25 was running. The system could crash while attempting to log connection-refusal events from CONS (X.25). This crash was indicated by the routine tp_log_refused_ cons_connection being on the stack. The system could crash while trying to log an rsp deleted event. This crash would be marked by the routine tposi_event_deleted_rsp being on the stack. o DTSS A problem with DTSS has been corrected to allow dtssd to run on TruCluster systems. Introduction 1-3 1.1.3 Problems Resolved in Version 3.2C o RFC 1006 The subroutine xti_ipgetaddr returned random values for the peer port number. It now returns the actual value. Multiprocessor systems could crash with a "kernel memory fault" when using RFC 1006. o OSI Transport A system crash (in tposi_dotimeout) when running over X.25 has been corrected. A system memory leak has been eliminated. When multiplexing multiple TP2 connections over X.25 there would sometimes be unnecessary delays in the transfer of data. Data corruption sometimes occurred during data transfer. (This problem has only been seen when communicating with a particular specialized piece of hardware that made unusual use of zero-credit acks). The maximum number of connections has been increased from 1024 to 65535. o DECdns The DECdns clerk was able to connect only to servers that had at least one nsap starting with 49:. DECdns would not work, or would work sporadically, when servers were located off the LAN. The severity of the problem depended on the amount of delay in reaching the servers. The dnsadv log file is now in /var/dss/dns rather than in /tmp. o Network Management Multiprocessor systems could crash with a "kernel memory fault" if a user cancelled an ncl command (using ^C) which was generating a large amount of output. NCL now accepts INET addresses (as well as names) when using TCP/IP as the transport (for example: ncl> show node 16.20.16.1). 1-4 Introduction Counter values reported by CSMA-CD entities were corrected. o Event Logging Changing the sink type of an event dispatcher sink while the sink is active could cause dnaevld to core dump. dnaevld would core dump when creating a second outbound stream The event dispatcher was not accepting inbound streams from remote DECnis routers. o MOP Up-line dumps could sometimes fail with the following error in the syslog file: "MOP[xxx]: Dump for 08-00-2b-a1-12-93 failed, open file ()" Down-line loads of the WANrouter 90 would sometimes fail. 1.2 Changes in Version 3.2B While retaining the functionality of RFC 1006, Version 3.2B includes the following changes: o There is no longer any RFC 1006 daemon process rfc1006d. o There is no longer a separate RFC 1006 kernel module dna_rfc1006.mod. 1.3 Network Management Graphical User Interface Included in this release is a new graphical user interface for network management.The dna_mgmt utility provides a hierarchical graphical approach to the management of DECnet/OSI. The manageable components of DECnet/OSI (modules, entities and subentities) are represented in a tree-like structure below the icon that represents the node you are managing. dna_mgmt provides an easy way to familiarize yourself with the organization of these manageable entities. If you choose to enable the Introduction 1-5 displaying of NCL commands from the Default Actions pulldown, dna_mgmt can also help familiarize you with NCL syntax. In addition to issuing NCL commands on your behalf, dna_ mgmt can also perform task-oriented functions which involve many NCL commands or are complex in some way. The currently supported dna_mgmt tasks are: show known links show known node counters check transports For further information, see the DECnet/OSI for Digital UNIX Installation and Configuration and the DECnet/OSI Network Managment books. 1.4 DECdns Server The Digital Distributed Name Service (DECdns) server enables a DECnet/OSI system to function as a DECdns server or a DECdns distributed name space. See Section 7.1 for the changes to the DECdns clerk and server software in Version 3.2B. See Section 7.2 of these release notes for restrictions for using the DECdns Server. 1.5 DECnet over TCP/IP With this release of DECnet/OSI for Digital UNIX, DECnet applications can now run over an IP network backbone. The new DECnet over TCP/IP feature allows traditional DECnet applications such as mail, cterm and fal to now accept IP host names. When an IP name is specified, it is translated from and defined in the local TCP/IP product already installed on your system. DECnet over TCP/IP uses RFC1006 plus, which is an Internet Draft. It defines how to implement ISO 8073 Transport Class 2 Non-use of Explicit Flow Control on top of TCP. Hosts that implement RFC1006 plus are required to listen on well-known TCP port 399. 1-6 Introduction When you are running DECnet/OSI, use the following command: dlogin remotehst6.companyx.com Both the source and target nodes must support DECnet over TCP/IP for this connection to work. You can configure the system to allow use of synonyms (PhaseIV style names) instead of the IP host fullname. The explicit use of IP addresses on the command line is not supported. 1.5.1 Configuration Steps for DECnet/OSI over TCP/IP If you want to use DECnet over TCP/IP, you must invoke decnetsetup advanced. 1.5.2 Disabling DECnet/OSI over TCP/IP To disable DECnet/OSI over TCP/IP, issue the following command: ncl> delete session control transport service doti 1.5.3 DOTI Tracing Support Added to CTF Support has been added to trace all PDUs transmitted and received by DOTI applications. See Appendix A in the CTF User's Guide for a list of events that are recognized at this tracepoint. 1.6 FDDI Circuits FDDI routing circuits will be configured as CSMA-CD type circuits with the corresponding data link block size. The script /var/dna/start_routing.ncl contains the commands to enable FDDI circuit support and the large packet support. Segregated mode is the default setting for all routing circuits. 1.7 Dynamic Kernel and SMP Support DECnet/OSI for Digital UNIX supports the Digital UNIX features of symmetric multiprocessing (SMP) and the dynamic loading of kernel components. This dynamic loading capability avoids the requirement to do a kernel build after the layered product has been installed. Static kernel modules for DNA Network Management and Datalink Introduction 1-7 Management are included for use by kernel layered products that still require kernel rebuilds. 1.8 Header Files for OSAK and ROSE Moved Some OSAK and ROSE header files that had shipped in the /usr/include directory for the OSI Toolkit were moved to /usr/include/osi when these were placed on the DECnet/OSI for Digital UNIX kit. This will have an impact on anybody compiling OSI application sources against the Version 3.2 kit. The compiler option "-I/usr/include/osi" can be specified (on the command line, or via a Makefile) in order to avoid explicit changes to source code. 1-8 Introduction 2 ________________________________________________________________ Installation Notes This chapter describes some details you should be aware of before installing the DECnet/OSI for Digital UNIX software. 2.1 Using DECnet with Enhanced Security If enhanced security is enabled on a system running DECnet, users may no longer be able to log into that system remotely via dlogin . This is because enhanced security expires all accounts when it is enabled, including the daemon account, which is the default account used by DECnet for remote logins. To re-enable dlogin, either activate the daemon account by resetting the password or change the default account on the "session control application cterm" entity to an active account. 2.2 Installation Message The following message may occur when configuring DECnet /OSI via decnetsetup and can be safely ignored: CTF: Error, another CTF Daemon is already running 2.3 Before Upgrading the Digital UNIX Operating System There are several system-specific files created or modified by DECnet/OSI that you should save before you upgrade the operating system. A Digital UNIX installation will reinitialize the partition on which the /var file system is located, you should back up these directories (using your standard backup procedure) before installing a new version of Digital UNIX: Installation Notes 2-1 __________________________________________________________ Directory Description __________________________________________________________ /var/dss/dns DECdns clerk and server data files /var/dna DECnet data files __________________________________________________________ _______________________ Note ________________________ Shut down DECnet/OSI before you run the backup procedure. _____________________________________________________ Also back up any customized DECnet initialization NCL scripts in the /var/dna/scripts directory. The standard initialization files are created by the decnetsetup utility when configuring DECnet. 2.4 RIS Installation Issues You should consider the following issues when using Remote Installation Services (RIS) to load DECnet/OSI for Digital UNIX and related products onto RIS client systems. 1. There are dependencies among products that are handled correctly when installing from CDROM, but that can cause error messages when installing from a RIS server. When using CDROM, each product is installed separately; when using RIS, all available subsets of all available products are offered at once. The suggested workaround when loading these products from a RIS server is to explicitly list the subsets to be loaded, and to load only one product at a time. The suggested order of product loading is: DECnet/OSI for Digital UNIX DEC X.25 for Digital UNIX 2. There is a restriction in the Digital UNIX RIS software that occurs when two subsets with the same name, but different contents, are available to a RIS client. One subset is loaded onto the client system, but the individual files are verified against the second subset. This can occur with the DNANETMAN321 subset, which is shipped with two different Digital UNIX layered products: DECnet/OSI and X.25. The only available workaround is to not duplicate the subset. 2-2 Installation Notes 2.5 Restart Xserver to Display X Window System Applications After installing DECnet/OSI on a workstation, you cannot display remote X Window System applications using DECnet/OSI until the Xserver is restarted. This can be accomplished by rebooting. 2.6 Removing the DECnet/OSI Software Be aware of these considerations when deleting DECnet/OSI software from your system: o If you are removing more than one subset from your system, make sure that you specify the network management subset, DNANETMAN321, last. Without the network management subset still installed, you cannot delete other subsets. o Other Digital software products require the DNANETMAN321 software subset. Before deleting DNANETMAN321, make sure that it is not needed by other products you have installed. For example, the DEC X.25 for Digital UNIX product requires this subset. See the other Digital software product documentation to determine if they require DNANETMAN321. 2.7 NSAPs Using Decimal DSP Syntax DECnet/OSI for does not support the configuration of NSAPs that use Decimal DSP syntax for DNA Routing (CLNP). However, X.121 format NSAPs (AFI=36) are supported for the use of OSI Transport over the Connection-oriented Network Service (CONS), which requires the DEC X.25 product. 2.8 Kernel rebuild if using X.25 If X.25 is installed on your system, the installation script may fail to correctly indicate the necessary steps to properly configure DECnet. To use X.25 with DECnet, after installing, perform the following steps: - Build a new kernel by executing the command: # /usr/sbin/decnetsetup KERNEL - Reboot the system to use this new kernel Installation Notes 2-3 - Configure or reconfigure DECnet/OSI by executing the command: # /usr/sbin/decnetsetup [basic|advanced] When decnetsetup is executing, it may indicate the need to rebuild the kernel. If you have followed the steps outlined above, you may disregard the message. If you have not run decnetsetup KERNEL, then you MUST do so before you will be able to successfully rebuild the kernel. 2-4 Installation Notes 3 ________________________________________________________________ Network Management This chapter describes special considerations that network managers need to understand before installing DECnet/OSI for Digital UNIX. Management issues for DECdns or DECdts are discussed in Chapters 4 and 5. 3.1 NCL CMIP Routines In this release, the ncl CMIP encoding/decoding routines have been rewritten. If you experience ncl commands failing for no apparent reason, it may be due to a bug in these routines. To work around this you can invoke the old code by defining an environmental variable called "NCL_OLD_CMIP" before invoking ncl. 3.2 Using Wildcards May Cause NCL to Hang Using wildcards to show all sub-entities, when there are no sub-entities to be displayed, may cause NCL to hang. To return to the ncl> prompt if this occurs, press . 3.3 Event Logging-Disabling the Event Dispatcher To disable the event dispatcher entity, first disable all the children/subentities, that is, outbound stream, phase IV relay and sink subentities. For example, ncl> disable event disp If any one of these subentities is enabled, the disable event dispatcher directive fails. The error message displayed states, Outbound Stream entities still enabled. Other subentities might also be enabled, not only outbound stream ones. Network Management 3-1 3.4 MOP Known Problem MOP does not perform Loop requests over HDLC. MOP will return the following error: FAILED IN DIRECTIVE: Loop DUE TO: Error Specific to this entity's class Reason: Timeout Description: Operation has timed-out 3-2 Network Management 4 ________________________________________________________________ General Software Notes This chapter describes special considerations and undocumented software features. 4.1 REMUSER Environment Variable The REMUSER environment variable used by the Session Control application spawner to pass information to the spawned application in DECnet/OSI has a different format from DECnet Phase IV. In DECnet/OSI, the environment variable is given as an end user specification. For example: DECnet-ULTRIX Phase IV: karen DECnet/OSI for Digital uic=[0,0]karen UNIX: 4.2 OBJECT Environment Variable The application spawner now sets the OBJECT environment variable to the name of the session control application subentity corresponding to the invoked application. For example, OBJECT=CTERM is the environment variable for a network terminal connection. 4.3 No Default Object The Session Control application spawner in DECnet/OSI does not support the notion of the default object. General Software Notes 4-1 4.4 Problems with the DECwindows Session Manager When using the security dialog menu of the DECwindows session manager on DECnet/OSI, Phase IV addresses are accepted but ignored by the X server. In addition, the DECwindows session manager and xhost both assume that nodes have only one network address. When using xhost, be sure to specify each network address for the node, using %x; for example, %x49000cAA000400503021. 4.5 Using the DECnet-Internet Gateway The following notes refer to the gateway. 4.5.1 PWD and XPWD Commands Not Implemented The PWD and XPWD FTP commands are not implemented for use through the FTP to DECnet part of the DECnet-Internet Gateway for this release. 4.5.2 Telnet If you are logged on to a Digital UNIX system and you want to use the DECnet-Internet Gateway that is installed on another Digital UNIX system, you must use the telnet -l option to specify the login name. The -l option should be specified after the hostname. 4.5.3 Using the Gateway for Remote Login If you are using the DECnet-Internet Gateway for remote login from DECnet/OSI to Internet and if the remote Internet system is a Digital UNIX or other telnetd implementation that accepts the USER environment variable, it attempts to log you in on the remote Internet system as user daemon. Simply press at the password: prompt to get a new login prompt. 4-2 General Software Notes 5 ________________________________________________________________ Programming Issues This chapter describes special considerations for network application programming in the DECnet/OSI for Digital UNIX environment. 5.1 Using the getnodename Subroutine The getnodename(3dn) subroutine uses getnodeent(3dn) internally; therefore, the nodename must be copied into a local structure if it is to be preserved. Because DECnet/OSI for Digital UNIX uses a distributed naming service instead of the local nodes database used for Phase IV, the getnodeent(3dn) subroutine call always returns NULL. The corresponding getnodebyname(3dn) and getnodebyaddr(3dn) calls still function as before. 5.2 XTI Known Problems This section lists known problems with XTI. o If data cannot be sent on a non-blocking xti connection because TFLOW has been returned by the t_snd() call, a call to any xti routine other than t_rcv() or t_look() will never return. o If the xti endpoint is flow-controlled off, a call to t_snddis() will not complete until all data has been read by the remote side or until the remote side disconnections the connection. o t_getstate() does not always return the most current state. To ensure that the state is current, call t_ sync() before calling t_getstate(). Programming Issues 5-1 6 ________________________________________________________________ Unsupported Utilities This chapter describes utilities that Digital Equipment Corporation supplies on an "as-is" basis. These utilities are furnished for general customer use. However, support is not offered for these utilities, nor are they covered under any of Digital's support contracts. 6.1 Unsupported Utilities Subset The unsupported utilities provided with DECnet/OSI for Digital UNIX software are contained in their own subset, DNAUTIL321. 6.2 tell The tell utility lets you execute commands on a remote DECnet/OSI for Digital UNIX or DECnet/OSI for OpenVMS node or any Phase IV or Phase V call supporting tell. If the remote DECnet/OSI for OpenVMS system does not have tell, copy the file /usr/examples/decnet/TELL.COM. (The username and password give you the access and privileges you need to execute the remote command.) You can use the tell command in this format: tell node-id[/username/password] command where node-id is the DECnet node name or DECnet node address of the remote node at which you want to execute the command, username is the name for a remote user account, password is the password for a remote user account, and command is the remote command that executes on the remote node. Unsupported Utilities 6-1 In this example, the SHOW TIME command executes on the VMS node TUPELO: tell tupelo sho time 10-MAR-1992 10:25:15 To execute more than one command on a remote system simply type tell. The tell utility prompts you for a node name or address and then for the commands that you want to execute. When you finish entering commands, press CTRL/D to return to the local shell. You can enter a local command during a tell session by beginning the command with a (~) and RETURN, which puts you in local mode. You receive this prompt when you enter local mode (~LOCAL>) where LOCAL is the name of the local node. For a list of local commands, type a question mark (?). _______________________ Note ________________________ With tell you can use only single line commands that generate output. The tell utility does not let you pass control to another program, such as mail. If you use tell to run a program and the program issues a read request, the request fails. Also, you cannot use tell to run cursor-manipulating programs. _____________________________________________________ 6.3 nfi The nfi utility tests network programs. This utility accepts commands that let you do the following: o Connect to a program on a remote system o Bind a name to a socket and wait for a connection o Build and send data and interrupt messages o Receive and display data and interrupt messages o Close the connection You can use nfi to debug pairs of programs that use a protocol; you can debug each end of the protocol separately. 6-2 Unsupported Utilities To display the nfi commands, enter nfi and type help: NFI (Network Functions Interface) V1.01 25-Apr-92 Local node: dec:.foo.bar (%x49000108002b2e2d2e20) nfi> help ***nfi (network functions interface) V1.01 *** ABORT [data {data}..] ACCEPT [DEFER] {wait_time} BIND "objnam" | objnum CONNECT node[["access"][::]] OBJECT {"objnam"|objnum} ... [data {data}..] CONNECT {REJECT | ACCEPT} [data {data}..] CONVERT data DISCONNECT [data {data}..] EXIT HELP | ? RECEIVE [WAIT seconds] SEND DATA [data..] SEND INTERRUPT data [data..] (16 bytes maximum) SET DISPLAY DECIMAL | OCTAL | HEXADECIMAL | BINARY ... | ASCII | RAD50 SET RECEIVE ON | OFF SET SOCKET socknum | OPTION |DOMAIN | TYPE | PROTOCOL| ... |BLOCKING | NONBLOCKING SHOW LAST SEND | RECEIVE SHOW RECEIVE | SOCKET | DISPLAY node: area.node | node_name @'filename' - command file data: decimal | .decimal | \octal | #binary | %rad50 ... | $hex | "ascii string" nfi> exit Exiting... % Note that nfi polls for both normal and out-of-band messages when you use the recv command. Unsupported Utilities 6-3 6.4 gatewayd The gatewayd utility lets you use a Digital UNIX system as a gateway to swap transports for an application protocol. For example, a client on a TCP/IP-only UNIX system might want to communicate with a server on a DECnet-only OpenVMS system. Even if client and server both use the same protocol (for example, X11), the lack of a common underlying transport prevents communication. However, if you insert a Digital UNIX system with both DECnet/OSI and TCP/IP between the two, it can act as a gateway. The Digital UNIX system acting as gateway must run some program that swaps application data from DECnet to Internet and vice versa. The gatewayd utility performs such a function. The gatewayd utility employs two sockets, one in the DECnet domain and one in the Internet domain. Once the necessary connections are established, gatewayd simply reads whatever is available on the DECnet socket and writes it to the Internet socket. Similarly, gatewayd reads whatever is available on the Internet socket and writes it to the DECnet socket. There are two types of connections, as follows: Connection Client System Server System VMS to UNIX VMS UNIX UNIX to VMS UNIX VMS See the README file in /usr/examples/decnet/gatethru/README for further details. 6.5 WWW (World Wide Web) gateway to DECnotes DECnet/OSI V3.2C for Digital UNIX includes webnotesd, an unsupported application that allows WWW (World Wide Web) Clients access to DECnotes conferences on the same network as the DECnet/OSI system. 6-4 Unsupported Utilities 6.5.1 Configuring webnotesd To enable this gateway, choose a TCP/IP port for webnotesd's use. Since webnotesd is a HTTP server, a reasonable choice would be the HTTP port (port 80) unless that port is already being used by another HTTP server. Add the following line to /etc/services (we are using an example port of 8080): webnotesd 8080/tcp # WWW --> DECnotes gateway Then to /etc/inetd.conf, add the following line: webnotesd stream tcp nowait guest /usr/lbin/webnotesd webnotesd Note that "guest" can be changed to another login. See the inetd.conf(4) manpage for more details. Then notify inetd.conf of the changed /etc/inetd.conf: # kill -HUP `cat /var/run/inetd.pid` At this point webnotesd should be enabled. 6.5.2 Using webnotesd All URLs understood by webnotesd have a common format. All such URLs are of the form "http://hostname:port/local- part" where "hostname" is the name of the system acting as the WWW to DECnotes gateway, "port" is the port webnotesd is using, and "local-part" is the webnotesd specific string that tells it what action to perform. For example, if "hostname" is "www-notes.some.bogus.com" and the port is 8080 (as used in the example above), then the URL (minus the local-part) would be "http:/ /www-notes.some.bogus.com:8080/". The local part of the URL is composed of 1 or more tokens, each separated by a '/'. The most common forms are: Example Description Unsupported Utilities 6-5 anode Perform listing of conferences in NOTES$LIBRARY: on "anode". anode/notes%24sample Show summary of "notes$sample" conference on "anode". anode/notes%24sample/1.0 Show note 1.0 in "notes$sample" conference on "anode". Note that %24 is the URL represententation for the "$" in "notes$sample". The first token is always the DECnet/OSI node name or TCP/IP hostname on which the conference resides. (If it refers to a TCP/IP hostname, then the first character of the name must be an '@'). The second token in always the conference name. By de- fault, the conference is assumed to be in NOTES$LIBRARY:. However, a full file name may be given, though the standard rules for special characters (including, but not limited to, any character in "[]$:<>") in URLs need to be used. The third token must be either a note-id that refers to a single note (such as "1.0" or "last.0") or a range of notes ("1-last"). So after combining the examples URLS parts, one would have: http://www-notes.some.bogus.com:8080/anode http://www-notes.some.bogus.com:8080/anode/notes%24sample http://www-notes.some.bogus.com:8080/anode/notes%24sample/1.0 Finally, when webnotesd displays a note, it makes any recognized URLs embedded in the text of the note active. 6.6 DECnotes Clients Two DECnotes clients are provided. One is an OSF/Motif X-window-based client (xnotes) and the other is a video terminal curses-based client (decnotes). These programs provide interfaces to NOTES files. Decnotes has the same style as VAXnotes, but xnotes does not. Both are experimental and have numerous restrictions, but show the feasibility of NOTES clients on DEC OSF/1. 6-6 Unsupported Utilities To use xnotes, see the file /usr/doc/xnotes.README after installing the utility software subset. To use decnotes, see the file /usr/doc/decnotes.README after installing that subset. 6.7 Poor Man's Routing (PMR) for Mail-11/CTERM/DAP The following sections explain support status for Poor Man's Routing (PMR). PMR allows you to get from a DECnet /OSI for Digital UNIX node that does not have a Phase IV-compatible address to a Phase IV node and vice versa. 6.7.1 Mail-11 DECnet/OSI for Digital UNIX now has Poor Man's Routing (PMR) support for Mail-11, for example: mail> send To: DECOSF::"user@nodename.dnet" -or- To: DECOSF::nodesynonym::user 6.7.2 CTERM DECnet/OSI for Digital UNIX has Poor Man's Routing (PMR) support for CTERM. To enable it, use the following command: touch /var/dna/PMRenabled Once enabled this functionality is very similar to CTERM=>TELNET access. Simply dlogin or SET HOST to the PMR gateway and at the login prompt, type: login: nodename:: CTERM PMR support is enabled separately from the Internet Gateway. 6.7.3 DAP DECnet/OSI for Digital UNIX has Poor Man's Routing (PMR) support for DAP. To enable it, use the following command: touch /var/dna/PMRenabled Unsupported Utilities 6-7 It is enabled whenever the Internet Gateway is enabled. The use is similar to the DAP=>FTP mechanism. Instead of supplying a username/password for access control, you supply a username@nodename/password. For example: $ DIR TIGGER"user@nodename.dnet password":: Note the .dnet to key it off to do DAP=>DAP instead of DAP=>FTP. Also, .dnet is the pseudo domain used by sendmail to indicate a DECnet host. A username/password need not be specified if accessing the default DECnet account, for example: $ DIR TIGGER"@nodename.dnet":: In this implementation the PMR gateway node simply forwards DAP messages between client and server unchanged. This way there are no problems going VMS=>Digital UNIX=>VMS like there is going Digital UNIX=>VMS=>Digital UNIX. The only message this gateway may not pass unchanged is the DAP config messages which contain the DAP buffer size being negotiated. If the client or server tries to negotiate a buffer size greater than the max TSDU size, the gateway lowers the requested buffer size. 6.8 Converting node::user to user@fullname.dnet A shell script exists that converts all occurrences of the form node::user in a file to the form user@fullname.dnet where node is a known node synonym and fullname is the corresponding fullname. It is named /usr/field/caliases (for "Convert ALIASES") because if given no filename for arguments, it defaults to operating on /var/adm/sendmail /aliases. 6-8 Unsupported Utilities 7 ________________________________________________________________ DECdns This chapter discusses DECdns naming service considera- tions. 7.1 DECdns Changes for Version V3.2B This section describes changes to the DECdns server and clerk contained in the mandatory update (MUP) 3.2B. 7.1.1 DECdns Server Changes for Version 3.2B The DECdns server software includes the following changes: o All DECnet directories were created with insufficient rights access to be replicated later on another server. This problem has been corrected. o Removing the last record caused the server to crash. This problem has been corrected. o Background skulks caused the DECdns server to crash due to the stack being too small. This problem has been corrected. o For large namespaces, the server image used excessive amounts of memory over a period of a few days. This problem was caused by a memory leak in the link_handler and has been corrected. o Creating an additional clearinghouse/server for a namespace is now done through dnsconfigure instead of dna_decdns_createns. DECdns 7-1 7.1.2 DECdns Clerk Changes for Version 3.2B The DECdns clerk software includes the following changes: o The clerk was looping due to intermittent incorrect behavior of the dthread_get_expiration() call. This problem has been corrected. o Memory corrupted and the clerk or advertiser looped when attempting to insert or read an attribute. This problem has been corrected. o The clerk sometimes looped when there was a failed connection to DECdns servers. This problem has been corrected. o Connection handling by the DECdns clerk tended to use too much memory. This problem has been corrected, and the DECdns clerk now requires less memory. o Previously, if you specified in dnsclerk.events or dnsd.events that you wanted all events to be captured, event log files and clerk trace log files dnsclerk_pid_ *.trace would fill up the disk quickly. A new feature allows you to limit the size of these log files by specifying the number of records. When there are more than x number of records written to either of these files, they are purged of records for a fresh start. To limit the size of the file to contain no more than 10,000 records, put the following two lines in the file dnsclerk.events or dnsd.events. * 10000 The asterisk specifies that all events should be captured. The 10000 specifies the maximum number of records written before the event and trace log files are overwritten. o The clerk events log file is no longer placed in the /tmp directory. Instead, it is now placed in /var/dss /dns/dnsclerk. 7-2 DECdns 7.2 DECdns Server Joining Existing Namespace To join an existing namespace, the new server system must be configured as a clerk in the namespace and the following items must be verified. o It has a node object registered in the namespace, for example: dnscp show obj ns:.newsrv o The node object has the correct addressing information, for example: dnscp show obj .newsrv dna$towers The output should match output of ncl show addr. o The DECdns server with the master replica of the directory to be joined should be registered in the namespace, should have correct addressing information, and each system should be able to connect to the other (for example, dlogin). 7.3 Limitation for Number of Members in a Single Group DECdns has an internal limitation of 100 for the number of members (principals) that may be stored in a single group. This means 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) that use groups to control access to objects stored in their DECdns namespaces. To ensure a limit of 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". DECdns 7-3 Two possible solutions are: o Create three 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 the group .dir_admin. Each contains a part of the alphabetically sorted list of members. o Create sub-groups that use some other partitioning algorithm, such as by site code, or group function instead of the alphabet as used in solution 1. 7.4 Location of DECdns Sockets DECdns sockets are located in /var/dss/dns. 7.5 Location of DECdns Clerk Backing File The backing file on disk for the DECdns clerk cache is located in: /var/dss/dns/dns_cache To delete the cache and restart the clerk: # dnscp disable dns clerk # dnscp delete dns clerk # rm /var/dss/dns/dns_cache # dnscp create dns clerk # dnscp enable dns clerk 7.6 DECdns Clerk Software on Nodes with Extended Addresses Clerks on nodes with extended addresses (without DECnet Phase IV-compatible addresses) can communicate only with DECdns Version 2 servers, not with DNS Version 1 servers (which are DECnet Phase IV nodes). You need a DECnet Phase IV-compatible address to communicate with a DECnet Phase IV node. 7-4 DECdns 7.7 Problem with dump dns clerk cache Command You may not be able to use the dump dns clerk cache command more than once during an invocation of the DECdns control program: dns> dump dns clerk cache A symptom of this problem can be an error message indicating improper syntax, such as the following: dns> dump dns clerk cache usage: cadump -m Cacheid; or: cadump -n filename You can avoid this problem by entering the dump dns clerk cache command from the shell command line as follows: > dnscp dump dns clerk cache 7.8 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. To set a directory's convergence to medium, use the following dnscp command: dns> set directory DNS$Convergence = medium 7.9 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 six 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, DECdns 7-5 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. 7.10 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 7.11 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 will ignore it. 7.12 Replicating the DECnet/OSI Directories The following are specific guidelines for replicating the directories that contain node object entries, node synonyms, and backtranslation soft links: o If a directory contains node object entries, locate at least one replica (preferably the master) on the same LAN as the nodes the entries describe. o Locate at least one replica of the .DNA_NodeSynonym directory on every LAN that includes DECnet/OSI nodes. o Locate the master replica of each .DNA_BackTranslation area directory in the area it is named after, if that area contains DECnet/OSI nodes. Also replicate an area directory in other areas likely to communicate most frequently with the nodes whose addresses it contains. 7-6 DECdns o In a solely WAN environment, try to replicate every directory so that it can be reached reliably by any DECnet/OSI system that needs it. 7.13 Show Clearinghouse Command Can Produce Errors The show dns server clearinghouse ch-name all command can return error 3216 on some or all attributes. The reason is probably that a network failure occurred after a clearinghouse was created but before it finished adding its attributes. To solve the problem, stop and restart the server on the system where the clearinghouse exists. 7.14 Clear Clearinghouse Command Gives Spurious Error When you issue a clear dns server clearinghouse command on a system where only one clearinghouse exists, you receive a spurious data_corruption error even if the command works. 7.15 Clerk Not Enabled Error Message If you delete the DECdns clerk shared memory segment (shared memory key is of the form 57xx), you receive clerk not enabled error messages when clerk operations are attempted. However, the command dnscp show dns clerk all shows that the clerk is enabled. To fix the problem, run /var/dna/scripts/stop_dns, and then /var/dna/scripts/start_dns. 7.16 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. 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 DECdns 7-7 .*... can be interpreted as any user, on any node, in any namespace. This is not the case. 7.17 Documentation Additions to Clearinghouse Creation Procedure The following information supplements the existing documentation in Section 10.4.2, Configuring a Server, and Section E.3.2, Allowing a Directory to Store Clearinghouse Object Entries, in the DECnet/OSI DECdns Management guide. If you specify an initial replica directory other than the parent directory of the clearinghouse name (the default), you must set the DNS$InCHName attribute to TRUE on that directory as well (even if you do not intend to store clearinghouse object entries in it). Details on clearinghouse creation failures can now be found in the DECdns server log file /var/dss/dns/dnsd /dnsd_nnnn.log. 7.18 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 Note that no error message is displayed. 7-8 DECdns 8 ________________________________________________________________ DECdts This chapter discusses considerations for the DECdts time service. 8.1 Changing the Time Differential Factor (TDF) The DECdts NCL management interface does not offer a command for modifying TDF information because the operating system performs this function. Digital UNIX maintains all internal time values in Coordinated Universal Time (UTC); UTC values are converted to local time values for display or output. UTC-to-local-time conversions follow rules defined by the file /etc/zoneinfo/localtime. This file points to the database that maintains local time information for the system. For example, if the system is located on the east coast of the U.S.A., the file /etc/zoneinfo/localtime points to /etc/zoneinfo/US/Eastern; if the system is in Germany, /etc/zoneinfo/localtime points to /etc/zoneinfo /CET (Central Europe). To change the current TDF, modify the localtime file to point to the time zone file that matches the system location. If DTSS is running, delete and re-create DTSS for the change to become effective. 8.2 Time-Provider Interface (TPI) Advisory Future versions of DECdts that support additional protocols will use a new Time-Provider Interface (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. The sample time-provider programs are located in: /usr/examples/dtss. DECdts 8-1 8.3 Starting a Time-Provider A known bug in the DECdts Time-Provider Interface (TPI) requires that you use the following procedure to start a time-provider program. To start a time-provider, follow these steps: 1. Stop DECdts by entering the following two commands: % ncl disable dtss % ncl delete dtss 2. Start DECdts manually by entering the following three commands: % dtssd & % ncl create dtss type server % ncl enable dtss set clock true 3. Start the appropriate time-provider program as shown in the following example command: % dtss_provider_spec -d/dev/tty02 & In this example, tty02 is the port to the external time provider source. 8.4 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. Please update this list by replacing "Spectracom 8170" with "Spectracom Netclock /2". 8-2 DECdts 9 ________________________________________________________________ FTAM and Virtual Terminal This chapter indicates any issues specific to this release for FTAM and Virtual Terminal on Digital UNIX systems. Please read these notes and the DECnet/OSI for Digital UNIX Installation and Configuration manual completely before performing the installation. 9.1 FTAM This section indicates issues specific to FTAM for this release. 9.1.1 Property List Support This version of FTAM implements property lists to store information related to the FTAM document type. Because this information is now stored transparently rather than as part of the file data, it is no longer necessary to use the ftamconvert utility for files transferred with this version of FTAM. The ftamconvert utility has been modified to convert old format FTAM files into the property list format. Therefore, you should convert any old format FTAM files to the property list format. Failure to do this will result in FTAM sending the old file header as part of the file data. Property lists are not supported over NFS. Therefore, FTAM files copied to NFS mounted disks will not have associated property lists, and document structure information will be lost. In addition, the attempt to set the property list on an NFS mounted disk will cause the responder to log an unaligned access error, which may be ignored. FTAM and Virtual Terminal 9-1 9.1.2 Responder Logging Support This version of FTAM provides limited support for the logging of file transfer operations that involve the FTAM daemon. When acting as a responder, the FTAM daemon, ftamd, logs messages to daemon.log regarding file OPEN access and file CLOSE access. An example of an OPEN message is: Jul 30 10:55:52 bedrck ftamd[18029]: OPEN access (30) from , user=fred, directory=/usr/users/fred, filename=/usr/users/fred/barney.rubble The (30) is a hexadecimal representation of the FTAM processing mode used to open the specified file. In this case, the file was opened with Replace and Extend, which usually indicates that a new file was copied to the system. The following constants are taken from osif.h (which is supplied with the FTAM API) for the processing mode: #define OSIF_PM_READ 0x80 #define OSIF_PM_INSERT 0x40 #define OSIF_PM_REPLACE 0x20 #define OSIF_PM_EXTEND 0x10 #define OSIF_PM_ERASE 0x08 In addition to the OPEN access message, ftamd also generates a message when the file is closed. An example of a CLOSE message is: Jul 30 10:55:52 bedrck ftamd[18029]: CLOSE access (success) from , user=fred, directory=/usr/users/fred, filename=/usr/users/fred/barney.rubble For the CLOSE message, ftamd indicates whether the F- CLOSE-REQUEST had a status of success or failure. Note that a CLOSE message may not be generated for every OPEN message. For example, if the FTAM association is aborted during file transfer, a CLOSE message is not generated. The from field in both the OPEN and CLOSE messages is currently left empty. Support for from may be provided in a future release of FTAM. 9-2 FTAM and Virtual Terminal 9.2 Virtual Terminal There are no release notes for Virtual Terminal for this release. FTAM and Virtual Terminal 9-3 10 ________________________________________________________________ OSAK This chapter describes issues specific to this version of the DECnet[TM]/OSI[R] OSI Application Kernel (OSAK) software and API and SPI programming interfaces. 10.1 New features This section contains information about new features in the OSAK software and programming interfaces. 10.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. 10.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 version of the software also includes SPI example programs, as follows: /usr/examples/osak/spi_example_init.c /usr/examples/osak/spi_example_resp.c More information about this the SPI interface is given in the books OSAK Programming and OSAK SPI Programming Reference. 10.1.3 Listen on Both RFC1006 and OSI Transport With this version of the OSAK software, an OSAK API or SPI application can listen for both RFC 1006 and OSI transport connections with one osak_open_responder or spi_open_ responder call. OSAK 10-1 In order to open a responder to listen for RFC1006 as well as an OSI transport type, set up the parameter block as usual on the osak_open_responder or spi_open_responder call to listen for OSI transport connections, plus specify the TCP port you want (usually 102) in the rfc1006_port parameter. If you want to listen for any type of connection requests, specify a template with transport type ANY and fill in the rfc1006_port parameter. The same application also runs on VMS since the rfc1006_port parameter is ignored on VMS. 10.2 Programming Interface Changes 10.2.1 Called_aei Parameter on A-ASSOCIATE and S-CONNECT Indication Events For A-ASSOCIATE indication events in the OSAK API, and S-CONNECT indication events in the SPI, the nsap field of the called_aei parameter is no longer filled in by OSAK. Previously, the called_aei.paddress.nsap structure contained the values specified in the local_ aei.paddress.nsap parameter on the osak_open_responder or spi_open_responder call. However, these values are not used by osak_open_responder or spi_open_responder and may not contain correct information about the received connection (for example, the transport type). 10.2.2 New Status Code The routines osak_send_more and spi_send_more can now return a status code of OSAK_S_NODATA which indicates that there is no data remaining. In previous versions the status code OSAK_S_INVFUNC may have been returned when this error occurred. 10.2.3 ROSE Minimum Workspace Increased The minimum required size for the parameter block workspace for ROSE has increased. If your ROSE application is using the old minimum workspace size, you will now get a bad parameter error. It is recommended that your application use the constant ROSE_WS_SIZE defined in osak_ api.h to get the correct minimum workspace size. 10-2 OSAK 10.3 Problems Resolved 10.3.1 Wrong NSAP No Longer Output to OSAKtrace File The OSAK software now correctly outputs to the OSAKtrace file the NSAP address which it successfully connected to when a list of NSAPs is given to osak_associate_req or spi_connect_req. 10.3.2 Transport Template Settings Honored All items set in the transport template are now honored by OSAK when establishing a connection. In particular, OSAK no longer always asks for expedited data. Instead, it uses whatever the transport template setting is. 10.3.3 Transport Congestion Problems Relieved OSAK applications may experience transport congestion problems. That is, the system may get the following errors logged: Event: Local Transport Disconnection Reason: Remote transport entity congestion at connect request time DNA error: Insufficient resources This version of the OSAK software has relieved most of this congestion. Most applications will now run without problems. If you are still experiencing problems with this version of OSAK, try increasing the value of one of the following kernel variables to a value of 20 or larger. tposi_info.tp_entity.ea_somaxconn somaxconn 10.4 Known Problems and Restrictions This section contains details of known problems and restrictions in the OSAK software and the OSAK programming interfaces. OSAK 10-3 10.4.1 Incorrect Information May Be Logged To OSAKtrace The OSAKtrace utility may output incorrect transport options on issuing a T_CONNECT request. Compare the information to that provided in the OSI transport traces. If there is any difference, use the output from the OSI transport trace. There is no corresponding problem with received T_CONNECT confirmation. 10.4.2 Closing Port After a Redirect Request After issuing a successful osak_redirect or spi_redirect call, an application can only close the port with the destructive_flag parameter set to OSAK_C_DESTRUCTIVE. 10.5 Documentation Corrections 10.5.1 Using OSAK over RFC1006 On the initiator side, to make a connection over RFC1006, specify as the NSAP the IP address as a 6-byte nibble packed hex value including the port number in the first 2 bytes. For example, the address of 16.36.112.142 on port 102 would be encoded as follows: 102 16.36.112.142 | | | | | 0066 10 24 70 8E In this case, the NSAP would be 00661024708E (hex). Specify the NSAP type as OSAK_C_RFC1006. For the transport template, specify either the pseudo-template "1006" or no template at all. OSAK uses a default template of "1006" if the NSAP type is OSAK_C_RFC1006. On the responder side, to listen for RFC1006 connections, specify as the transport template the pseudo-template "1006". 10-4 OSAK 10.5.2 Compiling API, ROSE, and SPI Applications When compiling your application code that makes calls to OSAK API, ROSE, or SPI routines, the cc command line requires the following: -I/usr/include/osi This is because the OSAK include files are in this directory. For example: /bin/cc -c -I/usr/include/osi -o osak_example_init.o osak_ example_init.c 10.5.3 Linking API, ROSE, and SPI Applications The information in the OSAK Programming book regarding linking OSAK API, ROSE API, and SPI applications on Digital UNIX systems has some errors in it. For all programming interfaces, the list of libraries to be linked against is incorrect. The documentation should read: o (Section 4.9) OSAK API applications should link with: /usr/shlib/libosak.so For example: /bin/cc -o osak_example_init osak_example_init.o -losak o (Section 5.4) ROSE applications should link with: /usr/shlib/libosak.so /usr/shlib/librose.so For example: /bin/cc -o rose_application rose_application.o -lrose -losak o (Section 6.9) SPI applications should link with: /usr/shlib/libosak.so For example: /bin/cc -o spi_example_init spi_example_init.o -losak OSAK 10-5