VS TCP/IP Services Release 1.85.00 TCP Application Programming Interface Customer Software Release Notice Copyright, Wang Laboratories, Inc., 2000 Disclaimer of Warranties and Limitation of Liabilities ______________________________________________________ The staff of Wang Laboratories, Inc., has taken due care in preparing this document. However, nothing contained herein modifies or alters in any way the standard terms and conditions of the Wang purchase, lease, or license agreement by which the product was acquired, nor increases in any way Wang's liability to the customer. In no event shall Wang or its subsidiaries be liable for incidental or consequential damages in connection with or arising from the use of the product, the accompanying document, or any related materials. Software Notice _______________ All Wang Program Products (software) are licensed to customers in accordance with the terms and conditions of the Wang Standard Software License. No title or ownership of Wang software is transferred, and any use of the software beyond the aforesaid license, without the written authorization of Wang, is prohibited. CONTENTS PREFACE CHAPTER 1 INTRODUCTION Hardware and Software Prerequisites ........................ 1-1 CHAPTER 2 SPECIAL CONSIDERATIONS Migration Issues for PLOWSHARE (NAI+) Users ................ 2-2 CHAPTER 3 PROBLEMS CORRECTED CHAPTER 4 MEDIA CONTENTS CHAPTER 5 INSTALLATION TABLES Table 4-1 Media Contents ............................................. 4-2 iii PREFACE This Customer Software Release Notice (CSRN) provides information specific to Release 1.85.00 of VS TCP Application Programmer's Interface (API). This notice is intended for system and networking administrators who will maintain the Release 1.85.00 VS TCP API software, and for programmers who will use the API to network-enable their applications. There are sections that give an overview of the product, discuss its hardware and software requirements, discuss special considerations and restrictions for its use, and list the product's media contents. The following publication is suggested as prerequisite reading. - VS TCP API Programmer's Guide, Release 1.6 (715-4620) - VS TCP/IP Operations Guide, Release 1.6 (715-0915B) - VS TCP/IP Configuration Guide, Release 1.8 (715-0900C) - VS TCP/IP Stack, Release 1.85 Customer Software Release Notice iv CHAPTER 1 INTRODUCTION The VS TCP Application Programming Interface (API) is part of the VS TCP/IP Services, Release 1.85 product. The VS TCP API allows you to develop your own distributed applications for data exchange across a TCP/IP network to another VS or non-VS system. The VS TCP API consists of a set of access routines that you can link to an application. The TCP API provides access routines for establishment, negotiation, and termination of application-to-application connections and for the transfer of data. VS TCP API 1.85.00 has been compiled and linked using year 2000 compliant compilers and linker. HARDWARE AND SOFTWARE PREREQUISITES The VS TCP API software is customer installable. VS TCP API requires that VS TCP/IP Stack, Release 1.85.00 or greater is installed. Refer to the VS TCP/IP Stack, Release 1.85 CSRN if you have questions about its hardware or software requirements. 1-1 CHAPTER 2 SPECIAL CONSIDERATIONS This chapter lists considerations and restrictions that apply to the configuration, operation, and administration of systems running the VS TCP API, Release 1.85.00 software. The considerations are notes of special interest, and the restrictions are descriptions of either hardware or software limitations. 1. Buffer sizes are limited to a maximum of 12,288 bytes. 2. If the user is returned an Event Control Block (ECB) on a NETEVWAIT call and the connection ID value is -1, then all NETLISTENs for this mailbox are invalid. 3. Numeric constant definitions for ECB parameter values and error codes may be found in the header files supplied with the software. 4. Table 4-3 in the VS TCP API Programmer's Guide contains a definition for the completion-status parameter. The name of the include file referenced there should be TCP$ERR, TCPERRH, or TCPCBINC (for PL/I, C, or COBOL, respectively), rather than NAIDDNSR. 5. The data-area-length parameter for NETSEND can be any number of bytes up to and including the negotiated send buffer size. 6. Error code 1205 returned from a call to NETOPEN or NETLISTEN indicates that the maximum number of sessions has been reached. This condition is not fatal for existing sessions. 2-1 7. For ECBs returned on calls to NETLISTEN and NETOPEN, the negotiated receive and send buffer sizes will not be larger than what was requested, but both could be smaller. The negotiated size returned in the ECB for the NETLISTEN and NETOPEN completion MUST be used for all NETDESIGNATEs and NETSENDs. Refer to the VS TCP API, Release 1.6 Programmer's Guide for more information on these access routines. 8. The VS TCP API is limited to a maximum of 17 ports when using NETLISTEN calls. The first NETATTACH calls preceding the NETLISTEN calls must specify a connection limit of 32. NETOPEN does not have this restriction. 9. TCP/IP can send credits in multiple event control blocks. It may be possible to increase the performance of your application by repeatedly calling NETEVWAIT until all network events have been returned to your application, and then calling NETSEND. This allows you to receive multiple credits and then do multiple sends (as opposed to sending as soon as you receive a single credit). 10. When the UNIX system sends a release request, the VS goes into a CLOSE WAIT state (run SESSTRC in @TCPIP@ to monitor the states of the connection). The VS TCP/IP Stack will wait approximately 2 minutes for the VS TCP/IP application to send a release response or more data. If the VS TCP/IP application does neither, then when the timer expires, the VS TCP/IP application will receive a CLOSE NETWORK. Only then will the buffers be returned. If the VS TCP/IP application sends a CLOSE Request Response (NETRLRSP), the application buffers will be returned immediately. 11. When linking with the TCPAPI library file, CLCRASH will be undefined. This entry is called whenever there is a severe problem within the TCP API routines. Entering the nonexistent routine will cause a dump to be created with information about the problem. 12. TCP API application may have problems linking with Wang OFFICE APIs greater than 2.05.50. Typically the application will link cleanly, however there may be problems running the application as calls to APQUERY, for example, will receive error "ERROR ND01 REPORTED BY NDIO INVALID DIRECTORY ID PASSED TO NDIO." This occurs because Wang OFFICE calls are satisfied by pointers in the TCPAPI file (lower level of Wang OFFICE). This can be circumvented by functionally separating the program into modules. 13. It is important that a TCP API application calls NETEVWAIT often. This allows the TCP API to complete the requested operations and to report events to your application. The application will obtain all the data the session partner has sent and prevent the Event Wait List from exceeding the application's memory area. 2-2 MIGRATION ISSUES FOR PLOWSHARE (NAI+) USERS PLOWSHARE applications will not run over the VS TCP/IP Stack, Release 1.6 and above software. When migrating your PLOWSHARE applications, most of the source code can remain unchanged. However, - Recompile and relink all PLOWSHARE programs. - Use the include files distributed with the VS TCP API, Release 1.8, rather than the PLOWSHARE include files. - Do not use the NETCEXIT access routine. This routine is no longer supported in the VS TCP API, Release 1.6 and higher products. - Do not use the "OB" keyword (optimum-buffer-size) on NETCONNINFO calls. This keyword is no longer supported in the VS TCP API, Release 1.6 and higher products. - The 'priority' and 'max-buffer-size' fields no longer exist in the ECB. 2-3 CHAPTER 3 PROBLEMS CORRECTED The following problem has been corrected in VS TCP API Release 1.85.00: Internal Year 2K: Components were recompiled and relinked with the Year 2000 compilers and linker. The following problems were corrected in VS TCP API Release 1.80.00: G200021644 2K buffers are lost during data transfer. Internal A new version of a Connection Layer Interface (CLIF) related module CLEVT 3.00.25 has been linked into TCPAPI. M200021477 2K buffers are lost during timer events. Internal A new version of the Connection Layer Interface (CLIF 3.00.31) has been linked into TCPAPI. 3-1 CHAPTER 4 MEDIA CONTENTS This section provides a list of the files contained in Release 1.85.00 of the VS TCP API. The VS TCP/IP Stack software is available on the following media types: Designation Media Type (-7) 9-track tape (-G) Streamer cartridge (-Q) 4 mm dat Table 4-1 lists the release media contents. In the table, Protection Class represents the value of the file on the tape. Changes to the protection classes of these files may affect the operational characteristics of the VS TCP APIs. After installation, the files reside in the library TCPAPI. To verify the version numbers, run DISPLAY and specify the appropriate file, library, and volume. The version number and date will be visible in the first or second records displayed. 4-1 Table 4-1. Media Contents File Version Description -------------------------------------------------------------------------- Library = TCPAPI BLDCSMP 01.85.00 Procedure to compile and link C sample programs BLDCBSMP 01.85.00 Procedure to compile and link Cobol sample programs CLIENT 01.85.00 C sample client program CLIENTCB 01.85.00 COBOL sample client program. SERVER 01.85.00 C sample server program. SERVERCB 01.85.00 COBOL sample server program. TCP$DCL 01.85.00 PL/I data structure definitions TCP$ERR 01.85.00 PL/I symbolic references TCP$EXT 01.85.00 PL/I External declarations TCPAPI 01.85.00 Runtime object TCPCBINC 01.85.00 Cobol Include File TCPDCLH 01.85.00 C data structure definitions TCPERRH 01.85.00 C Symbolic definition include file TCPEXTH 01.85.00 C External definitions Library = CSRNLIB TCPAPI 01.85.00 VS TCP/IP TCP API CSRN 1.85.00 -------------------------------------------------------------------------- 4-2 CHAPTER 5 INSTALLATION This chapter provides you with a procedure for installing the VS TCP API, Release 1.85 software. To install the VS TCP API, Release 1.85 software on your system, follow these steps: NOTE: You must have VS security administrator rights on the system you are installing to. 1. VS TCP/IP Stack Release 1.85.00 or higher should already be installed on the target system. 2. Log on the system as a VS Security Administrator. 3. Mount the tape containing the TCP API software, and set the following values based on whether you received the VS TCP/IP 1.85 Upgrade or the VS TCP/IP Services package (check the tape label): Set Volume = UPGRD or SRVCE Label = NL (for TAPE) or SL (for DISK) Mode = EX 4. Run BACKUP with Function = RESTORE and Dupfiles = SCRATCH on the release tape to copy all files from the release tape to library TCPAPI on the TCP/IP (output) volume. If you are upgrading, you may wish to backup the existing TCPAPI library. The output volume must be mounted on the system from which the BACKUP function is run. 5. When the procedure completes, dismount the input volume. 5-1