home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rexx / rxsock / rxsock.doc < prev    next >
Text File  |  1993-03-10  |  16KB  |  453 lines
  1.  
  2.  
  3.                                  rxSock
  4.  
  5.          Rexx Function Package for TCP/IP Sockets for OS/2 2.0
  6.  
  7.                            by Patrick Mueller
  8.  
  9.    (c) Copyright International Business Machines Corporation 1993.
  10.    All rights Reserved.
  11.  
  12. ----------------------------------------------------------------------
  13. what is rxSock?
  14. ----------------------------------------------------------------------
  15.  
  16. rxSock is a REXX function package providing access to the OS/2
  17. TCP/IP socket API as provided by the IBM TCP/IP product, version
  18. 1.2.1.
  19.  
  20. The function reference below is minimalistic.  It is assumed you
  21. are already familiar with the basic socket APIs, and can reference
  22. the OS/2 specific ones.  A widely available book on the basic socket
  23. APIs is "Internetworking with TCP/IP Volume I: Principals, Protocols,
  24. and Architecture" by Douglas Comer.
  25.  
  26. This function package requires the OS/2 TCP/IP product, version 1.2.1
  27. or higher.
  28.  
  29. ----------------------------------------------------------------------
  30. installation and removal
  31. ----------------------------------------------------------------------
  32.  
  33. The rxSock rexx function package is contained in the file rxSock.dll.
  34. This file needs to be placed in a directory along your LIBPATH.  To get
  35. access to the functions in the rxSock function package, execute the
  36. following rexx code:
  37.  
  38.    rc = RxFuncAdd("SockLoadFuncs","rxSock","SockLoadFuncs")
  39.    rc = SockLoadFuncs()
  40.  
  41. To unload the DLL, you should first call the SockDropFuncs()
  42. function, then exit all CMD.EXE shells.  After exiting all the
  43. command shells, the DLL will be dropped by OS/2 and can be deleted
  44. or replaced.
  45.  
  46. ----------------------------------------------------------------------
  47. Parameters and Return Values
  48. ----------------------------------------------------------------------
  49.  
  50. Return values for most functions are the same as the C equivalents,
  51. unless otherwise noted.
  52.  
  53. There are a number of standard parameters types referenced in the
  54. function reference.
  55.  
  56.   o socket
  57.     This is a socket value.  It is an integral number.
  58.  
  59.   o address
  60.     This is the 'stem' of a stemmed variable with the following values:
  61.  
  62.        o address.family
  63.          should always be "AF_INET"
  64.  
  65.        o address.port
  66.          a port number
  67.  
  68.        o address.addr
  69.          a dotted decimal address, or where appropriate, "INADDR_ANY"
  70.  
  71.     When this parameter is needed you should set it the name of a stem
  72.     variable for the function to set (or that the function will read
  73.     from).  For example, if you passed the string "xxx.!" as a
  74.     parameter, the variables
  75.  
  76.        "xxx.!family",
  77.        "xxx.!port", and
  78.        "xxx.!addr"
  79.  
  80.     will be set by the function, or queried by the function.
  81.  
  82.   o dotAddress
  83.     the standard dotted decimal address.  For example, the string
  84.     "9.23.19.63" is a valid address.
  85.  
  86.   o host
  87.     This is the 'stem' of a stemmed variable with the following values:
  88.  
  89.     o host.name
  90.       the standard name of the host
  91.  
  92.     o host.alias.0
  93.       number of aliases for this host
  94.  
  95.     o host.alias.1
  96.       First alias for this host
  97.  
  98.     o host.alias.n
  99.       n'th alias for this host
  100.  
  101.     o host.addrtype
  102.       should always be "AF_INET"
  103.  
  104.     o host.addr
  105.       a dotted decimal address
  106.  
  107.    When this parameter is needed you should set it the name of a stem
  108.    variable for the function to set (or that the function will read
  109.    from).  For example, if you passed the string "xxx.!" as a
  110.    parameter, the variables
  111.  
  112.        "xxx.!name",
  113.        "xxx.!alias.0",
  114.        "xxx.!alias.1" ... "xxx.!alias.n",
  115.        "xxx.!addrtype"
  116.        "xxx.!addr"
  117.  
  118.    will be set by the function, or queried by the function.
  119.  
  120. ----------------------------------------------------------------------
  121. Special note on stemmed variables
  122. ----------------------------------------------------------------------
  123.  
  124. The address and host type of parameters are stemmed variable names.
  125. Traditionally, you would pass a string like "addr." as a parameter,
  126. and expect to have the variables addr.family, addr.port, and addr.addr
  127. set by the function.  In the examples above though, I showed using
  128. a stem like "addr.!".  The exclamation point helps to distinguish the
  129. tail values, so they won't get mis-used as normal variables.  For
  130. instance, look at the following code:
  131.  
  132.    port = 923
  133.    sNew =  SockAccept(sOld,"addr.")
  134.    say addr.port
  135.  
  136. You might expect the say statement to write the port number of the
  137. accept'ed socket.  Instead it writes the value of the variable
  138. addr.923, since the port variable is SET to a value.
  139.  
  140. Since you probably don't normally use exclamation points in your
  141. variables, it's unlikely that you will be using the variable "!port"
  142. in your program.
  143.  
  144. Also note, some folk prefer other characters, including "_", "0", and
  145. "1" (the digits are allowed to prefix tail values and are very
  146. secure against this kind of accidental misuse - I don't use them
  147. because the characters are hard to distinguish from O, I, and l.
  148.  
  149. ----------------------------------------------------------------------
  150. Variables set
  151. ----------------------------------------------------------------------
  152.  
  153.   o errno
  154.  
  155.     The errno variable is set after every rxSock function call.  It
  156.     will have one of the following values (or a numeric value if the
  157.     number isn't one of these values, probably indicating an errno
  158.     value the compiler that the tcp/ip product was written in).  Note
  159.     the value is set even if the function that was called does not
  160.     neccessarily set the variable, in which case the value has no
  161.     meaning.
  162.  
  163.       "EWOULDBLOCK"
  164.       "EINPROGRESS"
  165.       "EALREADY"
  166.       "ENOTSOCK"
  167.       "EDESTADDRREQ"
  168.       "EMSGSIZE"
  169.       "EPROTOTYPE"
  170.       "ENOPROTOOPT"
  171.       "EPROTONOSUPPORT"
  172.       "ESOCKTNOSUPPORT"
  173.       "EOPNOTSUPP"
  174.       "EPFNOSUPPORT"
  175.       "EAFNOSUPPORT"
  176.       "EADDRINUSE"
  177.       "EADDRNOTAVAIL"
  178.       "ENETDOWN"
  179.       "ENETUNREACH"
  180.       "ENETRESET"
  181.       "ECONNABORTED"
  182.       "ECONNRESET"
  183.       "ENOBUFS"
  184.       "EISCONN"
  185.       "ENOTCONN"
  186.       "ESHUTDOWN"
  187.       "ETOOMANYREFS"
  188.       "ETIMEDOUT"
  189.       "ECONNREFUSED"
  190.       "ELOOP"
  191.       "ENAMETOOLONG"
  192.       "EHOSTDOWN"
  193.       "EHOSTUNREACH"
  194.       "ENOTEMPTY"
  195.  
  196.   o h_errno
  197.  
  198.     The h_errno variable is set after every rxSock function call.  It
  199.     will have one of the following values (or a numeric value if the
  200.     number isn't one of these values).  Note the value is set even if
  201.     the function that was called does not neccessarily set the
  202.     variable, in which case the value has no meaning.
  203.  
  204.       "HOST_NOT_FOUND"
  205.       "TRY_AGAIN"
  206.       "NO_RECOVERY"
  207.       "NO_ADDRESS"
  208.  
  209.  
  210. ----------------------------------------------------------------------
  211. Functions Reference
  212. ----------------------------------------------------------------------
  213.  
  214. Each of the functions below correspond to their like-named C functions
  215. available in the OS/2 TCP/IP socket library (except SockLoadFuncs and
  216. SockDropFuncs).
  217.  
  218.    -------------------------------------------------------------------
  219.    SockLoadFuncs
  220.    -------------------------------------------------------------------
  221.  
  222.       rc = SockLoadFuncs()
  223.  
  224.       Loads all the functions in the rxSock package.
  225.  
  226.       If ANY parameters are passed to this function, it will bypass
  227.       the program/author/copyright information normally displayed.
  228.       All parameters are ignored (except to determine whether or not
  229.       to bypass displaying the information).
  230.  
  231.    -------------------------------------------------------------------
  232.    SockDropFuncs
  233.    -------------------------------------------------------------------
  234.  
  235.       rc = SockDropFuncs()
  236.  
  237.       Drops all the functions in the rxSock package.
  238.  
  239.    -------------------------------------------------------------------
  240.    SockAccept          - implements C function accept()
  241.    -------------------------------------------------------------------
  242.  
  243.       socket = SockAccept(socket,address)
  244.  
  245.    -------------------------------------------------------------------
  246.    SockBind            - implements C function bind()
  247.    -------------------------------------------------------------------
  248.  
  249.       rc = SockBind(socket,address)
  250.  
  251.    -------------------------------------------------------------------
  252.    SockConnect         - implements C function connect()
  253.    -------------------------------------------------------------------
  254.  
  255.       rc = SockConnect(socket,address)
  256.  
  257.    -------------------------------------------------------------------
  258.    SockGetHostByAddr   - implements C function gethostbyaddr()
  259.    -------------------------------------------------------------------
  260.  
  261.       rc = SockGetHostByAddr(dotAddress,host)
  262.  
  263.       Returns 0 for success, 1 for error.
  264.  
  265.    -------------------------------------------------------------------
  266.    SockGetHostByName   - implements C function gethostbyname()
  267.    -------------------------------------------------------------------
  268.  
  269.       rc = SockGetHostByName(nameAddress,host)
  270.  
  271.       nameAddress should be the textual name of a host, for example
  272.       "pmuellr.vnet.ibm.com".
  273.  
  274.       Returns 0 for success, 1 for error.
  275.  
  276.    -------------------------------------------------------------------
  277.    SockGetHostId       - implements C function gethostid()
  278.    -------------------------------------------------------------------
  279.  
  280.       dotAddress = SockGetHostId()
  281.  
  282.    -------------------------------------------------------------------
  283.    SockGetPeerName     - implements C function getpeername()
  284.    -------------------------------------------------------------------
  285.  
  286.       rc = SockGetPeerName(socket,address)
  287.  
  288.    -------------------------------------------------------------------
  289.    SockGetSockName     - implements C function getsockname()
  290.    -------------------------------------------------------------------
  291.  
  292.       rc = SockGetSockName(socket,address)
  293.  
  294.    -------------------------------------------------------------------
  295.    SockGetSockOpt      - implements C function getsockopt()
  296.    -------------------------------------------------------------------
  297.  
  298.       value = SockGetSockOpt(socket,option)
  299.  
  300.       Not yet implemented.
  301.  
  302.    -------------------------------------------------------------------
  303.    SockInit            - implements C function sock_init()
  304.    -------------------------------------------------------------------
  305.  
  306.       rc = SockInit()
  307.  
  308.    -------------------------------------------------------------------
  309.    SockIoctl           - implements C function ioctl()
  310.    -------------------------------------------------------------------
  311.  
  312.       rc = SockIoctl(socket,cmd,data)
  313.  
  314.       Not yet implemented.
  315.  
  316.    -------------------------------------------------------------------
  317.    SockListen          - implements C function listen()
  318.    -------------------------------------------------------------------
  319.  
  320.       rc = SockListen(socket,backlog)
  321.  
  322.    -------------------------------------------------------------------
  323.    SockRecv            - implements C function recv()
  324.    -------------------------------------------------------------------
  325.  
  326.       rc = SockRecv(socket,var,len<,flags>)
  327.  
  328.       var is the name of a rexx variable the data should be received into.
  329.       len is the maximum amount of data to read.
  330.       flags can be one of "MSG_OOB" or "MSG_PEEK".
  331.  
  332.       Returns the return code from the recv() function.
  333.  
  334.    -------------------------------------------------------------------
  335.    SockSelect          - implements C function select()
  336.    -------------------------------------------------------------------
  337.  
  338.       ready = SockSelect(reads,writes,excepts)
  339.  
  340.       Not yet implemented.  Looking for ideas on what the parameters
  341.       and return values should be.
  342.  
  343.    -------------------------------------------------------------------
  344.    SockSend            - implements C function send()
  345.    -------------------------------------------------------------------
  346.  
  347.       rc = SockSend(socket,data<,flags>)
  348.  
  349.       data is a string of text to be sent on the sock.
  350.       flags may be one of"MSG_OOB" or "MSG_DONTROUTE".
  351.       Returns the return code from the send() function.
  352.  
  353.    -------------------------------------------------------------------
  354.    SockSetSockOpt      - implements C function setsockopt()
  355.    -------------------------------------------------------------------
  356.  
  357.       rc = SockSetSockOpt(socket,opt,value)
  358.  
  359.       Not yet implemented.
  360.  
  361.    -------------------------------------------------------------------
  362.    SockShutDown        - implements C function shutdown()
  363.    -------------------------------------------------------------------
  364.  
  365.       rc = SockShutDown(socket,how)
  366.  
  367.    -------------------------------------------------------------------
  368.    SockSocket          - implements C function socket()
  369.    -------------------------------------------------------------------
  370.  
  371.       socket = SockSocket(domain,type,protocol)
  372.  
  373.       domain must be "AF_INET".
  374.       type may be one of "SOCK_STREAM", "SOCK_DGRAM", or "SOCK_RAW"
  375.       protocol may be one of "IPPROTO_UDP", "IPPROTO_TCP", or "0"
  376.  
  377.    -------------------------------------------------------------------
  378.    SockSoClose         - implements C function soclose()
  379.    -------------------------------------------------------------------
  380.  
  381.       rc = SockSoClose(socket)
  382.  
  383. ----------------------------------------------------------------------
  384. Utilities Provided
  385. ----------------------------------------------------------------------
  386.  
  387.    killsock.cmd
  388.    ------------
  389.  
  390.    This program takes socket numbers and closes them.  Useful for
  391.    terminating a stubborn server, or cleaning up after accidents.
  392.  
  393.    Use "netstat -s" to get a list of currently open sockets.
  394.  
  395.  
  396.    rnr.cmd
  397.    -------
  398.  
  399.    A very basic news reader.  Used to demonstrate a fairly complex
  400.    application using rxSock functions.
  401.  
  402.  
  403.    test_h.cmd
  404.    ----------
  405.  
  406.    A test program testing address to hostname conversions.
  407.  
  408.  
  409.    test_c.cmd
  410.    test_s.cmd
  411.    ----------
  412.  
  413.    These program are test client/server programs.  Start test_s.cmd
  414.    in one session, and then test_c.cmd in another.  The programs
  415.    exchange data and print some timing information before quitting.
  416.    The server and client can run across two different hosts.  Pass
  417.    the host name of the server as a parameter to test_c.cmd
  418.  
  419.  
  420. ----------------------------------------------------------------------
  421. Signal Handling
  422. ----------------------------------------------------------------------
  423.  
  424. Due to the many interfaces involved in the rxSock package (REXX,
  425. tcp/ip), it's hard to determine who is handling signal exceptions,
  426. and if they are being handled appropriately.  Signal exceptions
  427. are generated for Ctrl-C, Ctrl-Break keys, or having DosKillProcess()
  428. run specifying the current process.
  429.  
  430. rxSock can provide it's own signal exception handling, so that you can
  431. break out of blocked function calls.  Currently this is implemented by
  432. returning an 'invalid' return code from the external function.  REXX
  433. interprets this as an 'incorrect call to routine', so don't be too
  434. suprised when you see this as the result of pressing ctrl-c or ctrl-break
  435. while one of the rxSock functions is executing.
  436.  
  437. The SockException() function can be used to change and query this
  438. behaviour.  Invoking SockException() with no parameters returns
  439. "ON" or "OFF" indicating whether exceptions are handled by rxSock
  440. ("ON") or not ("OFF").  The string "ON" or "OFF" can be passed to
  441. SockException to change the behaviour.  The previous value is
  442. returned in this case.
  443.  
  444. The initial value is "OFF", meaning rxSock does nothing special for
  445. signal exception handling (leaving it up to REXX and/or tcp/ip and/or
  446. CMD.EXE).  This is a process-persistant value, so calling
  447. SockException() will cause the setting to be used in the next REXX macro
  448. using rxSock running under the same CMD.EXE process.
  449.  
  450. The default value ("OFF") works fine for me on OS/2 2.0 with the
  451. Service Pack installed.
  452.  
  453.