home *** CD-ROM | disk | FTP | other *** search
/ Inside Multimedia 1995 February / IMM0295.ISO / share / os2 / tcpipos2 / pgmgcsd.doc < prev    next >
Encoding:
Text File  |  1994-06-13  |  12.5 KB  |  428 lines
  1.  
  2.             *************************************
  3.    ********* UN57887 CORRECTIVE SERVICE DISKETTE *********
  4.             *************************************
  5.  
  6.   TCP/IP 2.0 for OS/2 Corrective Service Diskette Information
  7.  
  8.   This README file for the corrective service diskette (CSD)
  9.   reflects new and changed functions for TCP/IP 2.0 for OS/2,
  10.   and corrections to the information.  This CSD applies to the
  11.   Programmer's Toolkit only.
  12.  
  13.  1.0  TCP/IP 2.0 for OS/2 Programmer's Toolkit
  14.  
  15.      Topics included in this CSD are:
  16.  
  17.         1.1  Installing this CSD
  18.         1.2  Previous CSD Information
  19.         1.3  Obtaining CSDs Electronically
  20.  
  21.         2.0  Functions Changed
  22.         2.1  Programming Support
  23.         2.1.1  REXX File Transfer Protocol API
  24.         2.1.2  REXX Socket Support
  25.         2.2  New FTP API Calls
  26.         2.2.1  ftptrcoff()   Stops tracing
  27.         2.2.2  ftptrcon()    Starts tracing
  28.         2.2.3  ftpver()      Returns the version number
  29.         2.3  Packet Size Restriction
  30.         2.4  Performance Considerations
  31.  
  32.         3.0  APAR Fixes
  33.  
  34.   ----------------------------------------------------------------
  35.  
  36.  
  37.  1.1  Installing this CSD
  38.  
  39.   To install this CSD from a diskette at your workstation,
  40.   insert the diskette into your A: drive and enter:
  41.  
  42.              A:>TCPINST
  43.  
  44.   ---------------------------------------------------------------------
  45.  
  46.  
  47.  1.2  Previous CSD Information
  48.  
  49.   This CSD incorporates the corrective service and new functions
  50.   that were previously released in CSD UN54155.  Please see the file
  51.   README.PRG in the <tcpip>\DOC directory for a description of the
  52.   functions that were originally released in UN54155.
  53.  
  54. ----------------------------------------------------------------
  55.  
  56.  
  57.  1.3  Obtaining CSDs Electronically
  58.  
  59.   You can obtain Corrective Service Diskettes (CSDs)
  60.   electronically by:
  61.  
  62.   o Using FTP to access SOFTWARE.WATSON.IBM.COM as Anonymous.
  63.  
  64.     NOTE:  Fixes for TCP/IP for OS/2 are located in the
  65.            pub\tcpip\os2 directory.
  66.  
  67.   o Establishing a modem connection to the NCSBBS bulletin
  68.            board at 1-919-517-0001.
  69.  
  70.     NOTE:  Set your modem settings to: none,8,1.
  71.  
  72.   The latest CSDs for TCP/IP Version 2.0 for OS/2 are shown
  73.   in the following table:
  74.  
  75.   +----------------------------+---------------------------+
  76.   | KIT NAME                   | PACKAGE NAME              |
  77.   +----------------------------+---------------------------+
  78.   | Applications Kit           | APP20CSD.PKG              |
  79.   +----------------------------+---------------------------+
  80.   | Base Kit                   | TCP20CSD.PKG              |
  81.   +----------------------------+---------------------------+
  82.   | Domain Name Server Kit     | DNS20CSD.PKG              |
  83.   +----------------------------+---------------------------+
  84.   | DOS/Windows Access Kit     | DOS20CSD.PKG              |
  85.   +----------------------------+---------------------------+
  86.   | Extended Networking Kit    | XNT20CSD.PKG              |
  87.   +----------------------------+---------------------------+
  88.   | Network File System Kit    | NFS20CSD.PKG              |
  89.   +----------------------------+---------------------------+
  90.   | OSF/Motif Kit              | MOT20CSD.PKG              |
  91.   +----------------------------+---------------------------+
  92.   | Programmer's Toolkit       | PGM20CSD.PKG              |
  93.   +----------------------------+---------------------------+
  94.   | X Window System Client Kit | XCL20CSD.PKG              |
  95.   +----------------------------+---------------------------+
  96.   | X Window System Server Kit | PMX20CSD.PKG              |
  97.   +----------------------------+---------------------------+
  98.  
  99.         *************************************************
  100. ******** UN57887 CORRECTIVE SERVICE DISKETTE STARTS HERE *********
  101.         *************************************************
  102.  
  103.   ----------------------------------------------------------------
  104.  
  105.  
  106.  2.0  Functions Changed
  107.  
  108.       None.
  109.  
  110.   ----------------------------------------------------------------
  111.  
  112.  2.1  Programming Support
  113.  
  114.   The REXX File Transfer Protocol API and the REXX Socket
  115.   Support are included in the Base Kit CSD.
  116.  
  117.  
  118.  2.1.1  REXX File Transfer Protocol API
  119.  
  120.   The REXX File Transfer Protocol (FTP) Application Program
  121.   Interface (API) package provides access to the OS/2 TCP/IP FTP
  122.   API's.  It is assumed you are familiar with the basic FTP. The
  123.   REXX FTP API function names are similar to the FTP subcommands.
  124.  
  125.   For more information and installation instructions,
  126.   type:  view RXFTP   at an OS/2 command line after installing
  127.   the Base Kit CSD or select the REXX FTP API icon in the
  128.   TCP/IP folder.
  129.  
  130.  
  131.  2.1.2  REXX Socket Support
  132.  
  133.   The REXX Socket Support package provides access to the OS/2
  134.   TCP/IP socket API's.  It is assumed you are familiar with the
  135.   basic socket APIs and that you can reference the OS/2 specific
  136.   ones.  For more information and installation instructions,
  137.   type:  view RXSOCKET  at an OS/2 command line after installing
  138.   the Base Kit CSD or select the REXX Sockets API icon in the
  139.   TCP/IP folder.
  140.  
  141.  
  142.  
  143. 2.2  New FTP API Calls
  144.  
  145.    ftptrcoff()      Stops tracing
  146.    ftptrcon()       Starts tracing
  147.    ftpver()         Returns the version number
  148.  
  149.  
  150. 2.2.1 >>>>>>>>>>>>>>>>>>> ftptrcoff() <<<<<<<<<<<<<<<<<<<
  151.  
  152. ftptrcoff() Call
  153.  
  154.  
  155. Syntax for ftptrcoff()
  156.  
  157.   #include <ftpapi.h>
  158.  
  159.   int ftptrcoff(void)
  160.  
  161.  
  162. Parameters
  163.  
  164.   none
  165.  
  166.  
  167. Return Values
  168.  
  169.   The ftptrcoff() always return a value of 0.
  170.  
  171.  
  172. Description
  173.  
  174.   The ftptrcoff() closes the trace file and stops
  175.   tracing of the command and reply sequences sent
  176.   over the control connection between the local
  177.   and remote hosts.
  178.  
  179.  
  180. Example
  181.  
  182.   int rc;
  183.   rc = ftptrcoff();
  184.  
  185.  
  186. 2.2.2 >>>>>>>>>>>>>>>>>>>> ftptrcon() <<<<<<<<<<<<<<<<<<<
  187.  
  188. ftptrcon() Call
  189.  
  190.  
  191. Syntax for ftptrcon()
  192.  
  193.   #include <ftpapi.h>
  194.  
  195.   int ftptrcon(fileSpec, mode)
  196.   char *fileSpec;
  197.   int mode;
  198.  
  199.  
  200. Parameters
  201.  
  202.   fileSpec  Identifies the name of the trace file.
  203.  
  204.   mode      Specifies the trace mode as overwrite or append.
  205.  
  206.             M_OVERLAY  -  trace data overwrites previous
  207.                           information
  208.  
  209.             M_APPEND   -  trace data appends to previous
  210.                           information
  211.  
  212.  
  213. Return Values
  214.  
  215.   There are three possible return values for ftptrcon():
  216.  
  217.     0 when successful
  218.  
  219.     TRCMODE indicates the value set into mode was invalid
  220.  
  221.     TRCOPEN indicates the trace file could not be opened
  222.  
  223.  
  224. Description
  225.  
  226.   The ftptrcon() call opens the trace file specified and
  227.   starts tracing of the command and reply sequences
  228.   sent over the control connection between the local
  229.   and remote hosts.  The trace file can be written
  230.   over or appended to.
  231.  
  232.   No notification is provided if writing of trace data
  233.   fails.
  234.  
  235.   Telnet command and reply sequences are not traced
  236.   nor are command and reply sequences between the
  237.   local host and a proxy host.
  238.  
  239.  
  240.  
  241. Example
  242.  
  243.   To write the trace data into a file named api.trc
  244.   in the C:\WORK directory, use:
  245.  
  246.  
  247.   int rc;
  248.   rc = ftptrcon("c\\work\\api.trc", M_OVERLAY);
  249.  
  250.  
  251.   If the file already existed, the new trace data
  252.   overwrites the previous trace data (overlay mode).
  253.  
  254. 2.2.3 >>>>>>>>>>>>>>>>>>>> ftpver() <<<<<<<<<<<<<<<<<<<
  255.  
  256. ftpver() Call
  257.  
  258.  
  259. Syntax for ftpver()
  260.  
  261.   #include <ftpapi.h>
  262.  
  263.   int ftpver(buf, buflen)
  264.   char *buf;
  265.   int buflen;
  266.  
  267.  
  268. Parameters
  269.  
  270.   buf     Identifies the buffer to store the version
  271.           string.
  272.  
  273.   buflen  Specifies the length of the buffer.
  274.  
  275.  
  276.  
  277. Return Values
  278.  
  279.    0  when successful
  280.  
  281.   -1  when the complete version string could not be
  282.       copied because the buffer length was too small.
  283.  
  284.  
  285. Description
  286.  
  287.   The ftpver() call stores the string containing the
  288.   FTP API version.  The string is truncated to fit into
  289.   the buffer if it is longer than the buffer length.
  290.   The returned string is always null-terminated.
  291.  
  292.  
  293. Example
  294.  
  295.   int rc;
  296.   rc = ftpver(verBuf, bufLen);
  297.  
  298.  
  299.   After the ftpver() call, the buffer contains the
  300.   following:  2.0.1
  301.  
  302.  
  303. 2.3  Packet Size Restriction
  304.  
  305.    The packet size for sending and receiving data is limited
  306.    to 32K of data.  When the data sent or received is
  307.    greater that 32K, the programmer must divide up the data
  308.    so that no packet exceeds 32K.
  309.  
  310.    This restriction applied to all socket calls.
  311.  
  312.    For example, to handle this restriction for the send()
  313.    function:
  314.  
  315.     int SendData(int socket, void *buffer, int len, int flags)
  316.     {
  317.       int rc;
  318.       char *temp    = (char *)buffer;
  319.       int  templen  = len;
  320.       int  errno    = 0;
  321.       do {
  322.          /* Never send more than 32K */
  323.          rc = send(socket, temp, min(templen,0xfff), flags);
  324.          if(rc > 0) {
  325.            temp     += rc;
  326.            templen  -= rc;
  327.          } /* endif */
  328.       } while (rc > 0) && templen); /*enddo */
  329.  
  330.       if(templen) {                    /* If there is still data, then  */
  331.         if(rc) errno = -sock_errno();  /*  1. there was an error        */
  332.         else   errno = EPIPE;          /*  2. the connection was closed */
  333.       } /* endif */
  334.  
  335.       return(errno);
  336.     }
  337.  
  338.  
  339.  
  340. 2.4  Performance Considerations
  341.  
  342.    The TCP/IP device drivers will only accept 16-bit aligned
  343.    pointers.  The sockets DLL deals with this problem by
  344.    allocating temporary memory and copying the corresponding
  345.    data.  To prevent this additional overhead, do not call
  346.    the socket DLL with pointers that cross a 64K boundary.
  347.    For calls that do not send or receive data, this is
  348.    generally not a problem.  It is suggested that the
  349.    programmer allow the sockets DLL to deal with 16-bit
  350.    boundaries in these situations.
  351.  
  352.    For send and receive type calls, the programmer should
  353.    avoid passing pointers that cross 64K boundaries to
  354.    prevent the sockets DLL from copying the data.
  355.  
  356.    For example, to handle this for the send() function:
  357.  
  358.     int SendData(int socket, void *buffer, int len, int flags)
  359.     {
  360.       int rc;
  361.       char *temp    = (char *)buffer;
  362.       int  templen  = len;
  363.       int  errno    = 0;
  364.  
  365.       do {
  366.          /* Never send across a 64K boundary, and  */
  367.          /* never send more than 32K               */
  368.          rc = send(socket, temp, min(min(templen,0xffff-(temp&0xffff)+1), 0x7fff), flags);
  369.  
  370.          if(rc > 0) {
  371.            temp     += rc;
  372.            templen  -= rc;
  373.          } /* endif */
  374.  
  375.       } while (rc > 0) && templen);    /*enddo */
  376.  
  377.       if(templen) {                    /* If there is still data, then  */
  378.         if(rc) errno = -sock_errno();  /*  1. there was an error        */
  379.         else   errno = EPIPE;          /*  2. the connection was closed */
  380.       } /* endif */
  381.  
  382.       return(errno);
  383.     }
  384.  
  385.  
  386.  
  387.  
  388.   ----------------------------------------------------------------
  389.  
  390.  
  391.  3.0  APAR Fixes
  392.  
  393.   The following is a list of APARs fixed in this CSD.
  394.  
  395.   +---------+-------------+-------------------------------+
  396.   | APAR    | MODULES     | DESCRIPTION                   |
  397.   | NUMBER  | AFFECTED    |                               |
  398.   +---------+-------------+-------------------------------+
  399.   | PN47687 | SO32DLL.DLL | Fixed: All calls to SO32DLL   |
  400.   |         | TCP32DLL.DLL| and TCP32DLL are now          |
  401.   |         |             | reentrant.                    |
  402.   +---------+-------------+-------------------------------+
  403.   | PN50502 | FTPAPI.DLL  | Fixed: Proper return code     |
  404.   |         |             | for FTPPUT() with AS/400      |
  405.   |         |             | member files.                 |
  406.   +---------+-------------+-------------------------------+
  407.   | PN50587 | RPC.DLL     | Fixed: General Protection     |
  408.   |         |             | Failure occurs when executing |
  409.   |         |             | SVC GETARGS().                |
  410.   +---------+-------------+-------------------------------+
  411.   | PN51060 | RPCHOUT     | Fixed: RPCGEN generates a     |
  412.   |         |             | syntactically incorrect .H    |
  413.   |         |             | file.                         |
  414.   +---------+-------------+-------------------------------+
  415.  
  416.   The following APAR was fixed in CSD UN54155.  This
  417.   change is included in this CSD as well.
  418.   +---------+-------------+-------------------------------+
  419.   | PN50077 | PRCGEN.EXE  | Fixed:                        |
  420.   |         | SNMP_DPI.H  | IOCTL(SIOCADDRT/SIOCDELRT) did|
  421.   |         | SOCKET.H    | not work when linking to      |
  422.   |         | SO32DLL.LIB | 32-bit dll                    |
  423.   +---------+-------------+-------------------------------+
  424.  
  425.  
  426.  
  427. --------------------------- End of Document --------------------
  428.