VS TCP/IP Services Release 1.85.00 FTP 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 ENHANCEMENTS AND SPECIAL CONSIDERATIONS 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 the VS FTP Application Programmer's Interface (API). This notice is intended for system and networking administrators who will maintain the Release 1.85.00 VS FTP API software, and for programmers who will use the API to FTP-enable their applications. There are sections that give an overview of the product, discuss its hardware and software requirements, discuss special considerations, restrictions, and conditions for its use, list the product's media contents, and provide installation information. The following publications are suggested as prerequisite reading: - VS FTP API Programmer's Guide, Release 1.6 (715-5090) - VS TCP/IP FTP/SMTP User's Guide, Release 1.6 (715-0899B) - VS TCP/IP 1.8 Enhancements (715-5292) - VS TCP/IP Stack, Release 1.8 Customer Software Release Notice - VS TCP/IP FTP/SMTP, Release 1.8 Customer Software Release Notice iv CHAPTER 1 INTRODUCTION The VS FTP Application Programming Interface (API) is part of the VS TCP/IP Services, Release 1.85 product. The VS FTP API allows you to develop applications that can access the File Transfer Protocol (FTP) services available through VS TCP/IP Services. The VS FTP API consists of a set of access routines that can be used with a variety of programming languages (Assembler, C, COBOL, PL/I, and VS Procedure languages) to enable applications to perform high-level FTP operations. FTP supports the transfer of file data between systems that support TCP/IP. The four available access routines allow an application to queue transfer requests, delete queued transfer requests, provide status information about transfer requests, and convert received files to usable formats. The FTP API is able to initiate FTP file transfer requests from remote systems that are not configured in the local configuration file. The API is able to use either IP addresses or host domain names to address remote systems. VS TCP/IP FTP API 1.85 is year 2000 compatible. HARDWARE AND SOFTWARE PREREQUISITES VS FTP API requires that VS FTP/SMTP, Release 1.85 be installed. Refer to the VS FTP/SMTP, Release 1.85 CSRN if you have questions about its hardware or software requirements. 1-1 CHAPTER 2 ENHANCEMENTS AND SPECIAL CONSIDERATIONS This chapter lists the enhancements made to this version of the VS TCP/IP Release 1.85 FTP API and discusses special considerations that apply to the configuration, operation, and adminstration. The enhancements are the major improvements that have been made to the product since its previous release. The special considerations are notes of special interest about the software or required hardware. ENHANCEMENTS The following section lists the enhancement made to Release 1.85.00 of VS TCP/IP FTP API. VS TCP/IP FTP API 1.85.00 has been compiled and linked using year 2000 compliant compilers and linker. The following section lists the enhancements made to Release 1.80.00 of VS TCP/IP FTP API. Support for a rename on successful transfer of a file. To use this option add the following 2 parameters to the FTPREQ call: - Rename flag (1 byte) - must be set to 'Y' to allow for rename - Rename path (64 bytes) - set to the name the file will be renamed to after successful file transfer. CONSIDERATIONS AND RESTRICTIONS This section lists restrictions and special considerations that apply to the configuration, operation, and administration of the VS TCP/IP FTP API, Release 1.85. The considerations are notes of special interest. The restrictions are descriptions of either hardware or software limitations. 1. Refer to the VS FTP/SMTP, Release 1.85 CSRN for information about restrictions and special considerations for that product. 2-1 2. When compiling and linking the FTPAPI sample Cobol program, SAM$CB, it is necessary to include the @SYSSERV SSL, otherwise MSAMP and MSUNMAP will show up as undefined symbols. @SYSSERV is entered on the Linker Aliases Screen (LALIASES). Enter @SYSSERV for one of the ten aliases listed on that screen ( for example ALIAS1 = @SYSSERV). To get to this screen, the following compile/link options should be set to yes: RESOLVE UNDEFINED EXTERNAL SYMBOLS INTERACTIVELY? RESOLVE = YES SSL SYMBOLS AND ASSIGNED ALIASES? SSLSYMB = YES REVIEW AND ASSIGN ALIASES TO SSL SYMBOLS ALIAS = YES 2-2 CHAPTER 3 PROBLEMS CORRECTED The following problem was corrected in VS FTP API Release 1.85.00 Internal EXPORTS file not needed. Cleared up undefined references. M200023691 When using FTPREQ and specifying IP addresses, the queue entry and the log file could display a blank in the source and/or destination host name. . Internal If FTPREQ receives an error code 'duplicate key error' when updating the queue file, FTPREQ will retry the update. . M200023661 FTPREQ does not allow a '0' when specifying an IP address. . M200023664 FTPREQ cancels when a non-valid host name is entered. The following problems were corrected in VS FTP API Release 1.80.00 M200023499 Program addressing exception occurs when requesting a file residing on a remote system to be sent to the local VS using the FTPREQ API. M8000025123 EXPORTS file missing from 1.70.00 M8000023238 No return code issued when FTPREQ names a file that does not exist. M8000025297 Consecutive calls to FTPDEL could result in a loop within FTPDEL. M2000023161 If the FTP server task is having a problem transfering a file and enters more than one entry into the FTP Log for the problem transfer, the FTPSTAT API will report status for the first occurance of the entry only. M2000023462 If a request is on the queue and is presently being transferred, FTPSTAT will return component = 20, code = 2 (as documented). If a request is on the queue and is not presently being transferred, FTPSTAT will return component = 20, code = 3 (as documented). If a request is presently being transferred, the request may not be deleted. FTPDEL will return component = 3, code = 3 (as documented). 3-1 CHAPTER 4 MEDIA CONTENTS This section provides a list of the files contained in Release 1.85.00 of the VS FTP API. The software is available on the following media types: Designation Media Type (-7) 9-track tape (-G) Streamer cartridge (-Q) 4 mm dat The release tape contains the library FTPAPI, which contains all of the software files. 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 FTP APIs. After installation, the files reside in the library FTPAPI. 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 = FTPAPI $FTPCNVT 01.85.00 Procedure to invoke FTPCONVT $FTPDEL 01.85.00 Procedure to invoke FTPDEL $FTPREQ 01.85.00 Procedure to invoke FTPREQ $FTPSTAT 01.85.00 Procedure to invoke FTPSTAT DRIVER 01.85.00 Procedure which invokes $FTPCNVT, $FTPDEL, $FTPREQ, $FTPSTAT FTP$DCL 01.85.00 API declarations in PL/I FTP$ERR 01.85.00 API error and component codes in PL/I FTP$EXT 01.85.00 API external function declarations in PL/I FTPCBINC 01.85.00 API declarations, error and component codes in COBOL FTPCONVT 01.85.00 File conversion routine FTPDCLH 01.85.00 API declarations in C FTPDEL 01.85.00 Delete file transfer request routine FTPERRH 01.85.00 API error and component codes in C FTPEXTH 01.85.00 API external function declarations in C FTPREQ 01.85.00 File transfer request routine FTPSTAT 01.85.00 File transfer status routine INTFTP 01.85.00 Procedure that performs transfer request, then checks transfer status LIBSEND 01.85.00 Procedure that requests that an entire VS Library be transferred. SAMP$C 01.85.00 API sample program in C SAMP$CB 01.85.00 API sample program in COBOL SAMP$PLI 01.85.00 API sample program in PL/I LIBRARY = CSRNLIB FTPAPI 01.85.00 VS TCP/IP FTP API CSRN --------------------------------------------------------------------------- 4-2 CHAPTER 5 INSTALLATION The VS FTP API, Release 1.85 software is customer installable. This chapter provides you with a procedure for installing the software on your system. To install the software, follow these steps: NOTE: You must have VS security administrator rights on the system you are installing to. 1. VS TCP/IP Stack and VS TCP/IP FTP/SMTP 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 release tape containing the FTP 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 library FTPAPI on the TCP/IP (output) volume. If you are upgrading, you may wish to backup the existing FTPAPI 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