home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / RXSOCK.ZIP / rxsock.doc < prev    next >
Text File  |  1993-08-05  |  20KB  |  574 lines
  1.  
  2.  
  3. rxSock -Rexx Function Package for TCP/IP Sockets for OS/2 2.0
  4.  
  5.    by Patrick Mueller (pmuellr@vnet.ibm.com)
  6.  
  7. (c) Copyright International Business Machines Corporation 1993.
  8. All rights Reserved.
  9.  
  10. ----------------------------------------------------------------------
  11. what is rxSock?
  12. ----------------------------------------------------------------------
  13.  
  14. rxSock is a REXX function package providing access to the OS/2
  15. TCP/IP socket API as provided by the IBM TCP/IP product, version
  16. 1.2.1.
  17.  
  18. The function reference below is minimalistic.  It is assumed you are
  19. already familiar with the basic socket APIs, and can reference the OS/2
  20. specific ones.  A widely available book with information on the basic
  21. socket APIs is "Internetworking with TCP/IP Volume I:  Principals,
  22. Protocols, and Architecture" by Douglas Comer.
  23.  
  24. This function package requires the OS/2 TCP/IP product, version 1.2.1
  25. or higher.
  26.  
  27. ----------------------------------------------------------------------
  28. installation and removal
  29. ----------------------------------------------------------------------
  30.  
  31. The rxSock rexx function package is contained in the file rxSock.dll.
  32. This file needs to be placed in a directory along your LIBPATH.  To get
  33. access to the functions in the rxSock function package, execute the
  34. following rexx code:
  35.  
  36.    rc = RxFuncAdd("SockLoadFuncs","rxSock","SockLoadFuncs")
  37.    rc = SockLoadFuncs()
  38.  
  39. To unload the DLL, you should first call the SockDropFuncs()
  40. function, then exit all CMD.EXE shells.  After exiting all the
  41. command shells, the DLL will be dropped by OS/2 and can be deleted
  42. or replaced.
  43.  
  44. ----------------------------------------------------------------------
  45. Parameters and Return Values
  46. ----------------------------------------------------------------------
  47.  
  48. Return values for most functions are the same as the C equivalents,
  49. unless otherwise noted.
  50.  
  51. There are a number of standard parameters types referenced in the
  52. function reference.
  53.  
  54.   o socket
  55.     This is a socket value.  It is an integral number.
  56.  
  57.   o domain
  58.     This is a domain value.  The only currently supported domain is
  59.     "AF_INET".
  60.  
  61.   o address
  62.     This is the 'stem' of a stemmed variable with the following values:
  63.  
  64.        o address.family
  65.          should always be "AF_INET"
  66.  
  67.        o address.port
  68.          a port number
  69.  
  70.        o address.addr
  71.          a dotted decimal address, or where appropriate, "INADDR_ANY"
  72.  
  73.     When this parameter is needed you should set it the name of a stem
  74.     variable for the function to set (or that the function will read
  75.     from).  For example, if you passed the string "xxx.!" as a
  76.     parameter, the variables
  77.  
  78.        "xxx.!family",
  79.        "xxx.!port", and
  80.        "xxx.!addr"
  81.  
  82.     will be set by the function, or queried by the function.
  83.  
  84.   o dotAddress
  85.     the standard dotted decimal address.  For example, the string
  86.     "9.23.19.63" is a valid address.
  87.  
  88.   o host
  89.     This is the 'stem' of a stemmed variable with the following values:
  90.  
  91.     o host.name
  92.       the standard name of the host
  93.  
  94.     o host.alias.0
  95.       number of aliases for this host
  96.  
  97.     o host.alias.1
  98.       First alias for this host
  99.  
  100.     o host.alias.n
  101.       n'th alias for this host
  102.  
  103.     o host.addrtype
  104.       should always be "AF_INET"
  105.  
  106.     o host.addr
  107.       a dotted decimal address (default address)
  108.  
  109. |   o host.addr.0
  110. |     number of addresses for this host
  111. |
  112. |   o host.addr.1
  113. |     First address for this host
  114. |
  115. |   o host.addr.n
  116. |     n'th address for this host
  117.  
  118.    When this parameter is needed you should set it the name of a stem
  119.    variable for the function to set (or that the function will read
  120.    from).  For example, if you passed the string "xxx.!" as a
  121.    parameter, the variables
  122.  
  123.        "xxx.!name",
  124.        "xxx.!alias.0", "xxx.!alias.1" ... "xxx.!alias.n",
  125.        "xxx.!addrtype"
  126.        "xxx.!addr"
  127.        "xxx.!addr.0", "xxx.!addr.1" ... "xxx.!addr.n",
  128.  
  129.    will be set by the function, or queried by the function.
  130.  
  131. ----------------------------------------------------------------------
  132. Special note on stemmed variables
  133. ----------------------------------------------------------------------
  134.  
  135. The address and host type of parameters are stemmed variable names.
  136. Traditionally, you would pass a string like "addr." as a parameter,
  137. and expect to have the variables addr.family, addr.port, and addr.addr
  138. set by the function.  In the examples above though, I showed using
  139. a stem like "addr.!".  The exclamation point helps to distinguish the
  140. tail values, so they won't get mis-used as normal variables.  For
  141. instance, look at the following code:
  142.  
  143.    port = 923
  144.    sNew =  SockAccept(sOld,"addr.")
  145.    say addr.port
  146.  
  147. You might expect the say statement to write the port number of the
  148. accept'ed socket.  Instead it writes the value of the variable
  149. addr.923, since the port variable is SET to a value.
  150.  
  151. Since you probably don't normally use exclamation points in your
  152. variables, it's unlikely that you will be using the variable "!port"
  153. in your program.
  154.  
  155. Also note, some folk prefer other characters, including "_", "0", and
  156. "1" (the digits are allowed to prefix tail values and are very
  157. secure against this kind of accidental misuse - I don't use them
  158. because the characters are hard to distinguish from O, I, and l).
  159.  
  160. ----------------------------------------------------------------------
  161. Variables set
  162. ----------------------------------------------------------------------
  163.  
  164.   o errno
  165.  
  166.     The errno variable is set after every rxSock function call.  It
  167.     will have one of the following values (or a numeric value if the
  168.     number isn't one of these values, probably indicating an errno
  169.     value the compiler that the tcp/ip product was written in).  Note
  170.     the value is set even if the function that was called does not
  171.     neccessarily set the variable, in which case the value has no
  172.     meaning.  The value 0 indicates no error occurred.
  173.  
  174.       "EWOULDBLOCK"
  175.       "EINPROGRESS"
  176.       "EALREADY"
  177.       "ENOTSOCK"
  178.       "EDESTADDRREQ"
  179.       "EMSGSIZE"
  180.       "EPROTOTYPE"
  181.       "ENOPROTOOPT"
  182.       "EPROTONOSUPPORT"
  183.       "ESOCKTNOSUPPORT"
  184.       "EOPNOTSUPP"
  185.       "EPFNOSUPPORT"
  186.       "EAFNOSUPPORT"
  187.       "EADDRINUSE"
  188.       "EADDRNOTAVAIL"
  189.       "ENETDOWN"
  190.       "ENETUNREACH"
  191.       "ENETRESET"
  192.       "ECONNABORTED"
  193.       "ECONNRESET"
  194.       "ENOBUFS"
  195.       "EISCONN"
  196.       "ENOTCONN"
  197.       "ESHUTDOWN"
  198.       "ETOOMANYREFS"
  199.       "ETIMEDOUT"
  200.       "ECONNREFUSED"
  201.       "ELOOP"
  202.       "ENAMETOOLONG"
  203.       "EHOSTDOWN"
  204.       "EHOSTUNREACH"
  205.       "ENOTEMPTY"
  206.  
  207.   o h_errno
  208.  
  209.     The h_errno variable is set after every rxSock function call.  It
  210.     will have one of the following values (or a numeric value if the
  211.     number isn't one of these values).  Note the value is set even if
  212.     the function that was called does not neccessarily set the
  213.     variable, in which case the value has no meaning. The value 0
  214.     indicates no error occurred.
  215.  
  216.       "HOST_NOT_FOUND"
  217.       "TRY_AGAIN"
  218.       "NO_RECOVERY"
  219.       "NO_ADDRESS"
  220.  
  221.  
  222. ----------------------------------------------------------------------
  223. Function Reference
  224. ----------------------------------------------------------------------
  225.  
  226. Most of the functions below correspond to their like-named C functions
  227. available in the OS/2 TCP/IP socket library.
  228.  
  229.    -------------------------------------------------------------------
  230.    SockLoadFuncs
  231.    -------------------------------------------------------------------
  232.  
  233.       rc = SockLoadFuncs()
  234.  
  235.       Loads all the functions in the rxSock package.
  236.  
  237.       If ANY parameters are passed to this function, it will bypass
  238.       the program/author/copyright information normally displayed.
  239.       All parameters are ignored (except to determine whether or not
  240.       to bypass displaying the information).
  241.  
  242.    -------------------------------------------------------------------
  243.    SockDropFuncs
  244.    -------------------------------------------------------------------
  245.  
  246.       rc = SockDropFuncs()
  247.  
  248.       Drops all the functions in the rxSock package.
  249.  
  250. |  -------------------------------------------------------------------
  251. |  SockVersion         - returns version number
  252. |  -------------------------------------------------------------------
  253. |
  254. |     vers = SockVersion()
  255. |
  256. |     Prior to version 1.2, this function did not exist.  To check
  257. |     to see if a previous version of RxSock is installed, use the
  258. |     following code, after loading the function package with
  259. |     SockLoadFuncs().
  260. |
  261. |     /* oldVersion will be '1' if a version of RxSock < 1.2 is loaded */
  262. |     oldVersion = (1 = RxFuncQuery("SockVersion"))
  263.  
  264.    -------------------------------------------------------------------
  265.    SockAccept          - implements C function accept()
  266.    -------------------------------------------------------------------
  267.  
  268.       socket = SockAccept(socket<,address>)
  269.  
  270.    -------------------------------------------------------------------
  271.    SockBind            - implements C function bind()
  272.    -------------------------------------------------------------------
  273.  
  274.       rc = SockBind(socket,address)
  275.  
  276. |  -------------------------------------------------------------------
  277. |  SockClose           - implements C function soclose()/close()
  278. |  -------------------------------------------------------------------
  279. |
  280. |     rc = SockClose(socket)
  281. |
  282. |     Exactly the same as SockSoClose()
  283.  
  284.    -------------------------------------------------------------------
  285.    SockConnect         - implements C function connect()
  286.    -------------------------------------------------------------------
  287.  
  288.       rc = SockConnect(socket,address)
  289.  
  290.    -------------------------------------------------------------------
  291.    SockGetHostByAddr   - implements C function gethostbyaddr()
  292.    -------------------------------------------------------------------
  293.  
  294.       rc = SockGetHostByAddr(dotAddress,host<,domain>)
  295.  
  296.       Returns 1 for success, 0 for error.
  297.  
  298.    -------------------------------------------------------------------
  299.    SockGetHostByName   - implements C function gethostbyname()
  300.    -------------------------------------------------------------------
  301.  
  302.       rc = SockGetHostByName(nameAddress,host)
  303.  
  304.       nameAddress should be the textual name of a host, for example
  305.       "pmuellr.vnet.ibm.com".
  306.  
  307.       Returns 1 for success, 0 for error.
  308.  
  309.    -------------------------------------------------------------------
  310.    SockGetHostId       - implements C function gethostid()
  311.    -------------------------------------------------------------------
  312.  
  313.       dotAddress = SockGetHostId()
  314.  
  315.    -------------------------------------------------------------------
  316.    SockGetPeerName     - implements C function getpeername()
  317.    -------------------------------------------------------------------
  318.  
  319.       rc = SockGetPeerName(socket,address)
  320.  
  321.    -------------------------------------------------------------------
  322.    SockGetSockName     - implements C function getsockname()
  323.    -------------------------------------------------------------------
  324.  
  325.       rc = SockGetSockName(socket,address)
  326.  
  327. |  -------------------------------------------------------------------
  328. |  SockGetSockOpt      - implements C function getsockopt()
  329. |  -------------------------------------------------------------------
  330. |
  331. |     rc = SockGetSockOpt(socket,level,optVar,optVal)
  332. |
  333. |     The only valid value for level is "SOL_SOCKET"
  334. |
  335. |     optVar may be one of the following:
  336. |
  337. |        "SO_BROADCAST"
  338. |        "SO_DEBUG"
  339. |        "SO_DONTROUTE"
  340. |        "SO_ERROR"
  341. |        "SO_KEEPALIVE"
  342. |        "SO_LINGER"
  343. |        "SO_OOBINLINE"
  344. |        "SO_RCVBUF"
  345. |        "SO_RCVLOWAT"
  346. |        "SO_RCVTIMEO"
  347. |        "SO_REUSEADDR"
  348. |        "SO_SNDBUF"
  349. |        "SO_SNDLOWAT"
  350. |        "SO_SNDTIMEO"
  351. |        "SO_TYPE"
  352. |        "SO_USELOOPBACK"
  353. |
  354. |     optVal is the value of the option.  Most of the options' values
  355. |     are integral.  The exceptions are:
  356. |
  357. |        "SO_LINGER" - expects two blank delimited integers - the first
  358. |                      is the l_onoff value, the second is the l_linger
  359. |                      value.
  360. |        "SO_TYPE"   - a string of either "STREAM", "DGRAM", or "RAW"
  361. |
  362.  
  363.    -------------------------------------------------------------------
  364.    SockInit            - implements C function sock_init()
  365.    -------------------------------------------------------------------
  366.  
  367.       rc = SockInit()
  368.  
  369.       SockInit() is not strictly needed, as initialization is done
  370.       for each RxSock function if initialization has not yet occurred.
  371.  
  372. |  -------------------------------------------------------------------
  373. |  SockIoctl           - implements C function ioctl()
  374. |  -------------------------------------------------------------------
  375. |
  376. |     rc = SockIoctl(socket,ioctlCmd,ioctlData)
  377. |
  378. |     ioctlCmd is the ioctl command to perform.  Valid commands are:
  379. |
  380. |        "FIONBIO"
  381. |        "FIONREAD"
  382. |
  383. |     ioctlData is the command specific value.  Values are:
  384. |
  385. |        "FIONBIO"   - "1" or "0"
  386. |        "FIONREAD"  - name of a variable to contain number of immediately
  387. |                      readable bytes
  388.  
  389.  
  390.    -------------------------------------------------------------------
  391.    SockListen          - implements C function listen()
  392.    -------------------------------------------------------------------
  393.  
  394.       rc = SockListen(socket,backlog)
  395.  
  396.    -------------------------------------------------------------------
  397.    SockRecv            - implements C function recv()
  398.    -------------------------------------------------------------------
  399.  
  400.       rc = SockRecv(socket,var,len<,flags>)
  401.  
  402.       var is the name of a rexx variable the data should be received into.
  403.       len is the maximum amount of data to read.
  404.       flags is a blank delimited list of options: "MSG_OOB", "MSG_PEEK".
  405.  
  406.       Returns the return code from the recv() function.
  407.  
  408. |  -------------------------------------------------------------------
  409. |  SockSelect          - implements C function select()
  410. |  -------------------------------------------------------------------
  411. |
  412. |     rc = SockSelect(reads,writes,excepts<,timeout>)
  413. |
  414. |     reads, writes, and excepts are stem variables which are queried
  415. |     and set by this function.  The stem.0 variable should contain the
  416. |     number of sockets, stem.1 the first socket, etc.  Upon return,
  417. |     the stem variables will be reset to the sockets which are ready.
  418. |     For instance,
  419. |
  420. |         r.0 = 2
  421. |         r.1 = 101
  422. |         r.2 = 102
  423. |         w.0 = 1
  424. |         w.1 = 103
  425. |         e.0 = 0
  426. |
  427. |         rc = SockSelect("r.","w.","e.")
  428. |
  429. |         do i = 1 to r.0
  430. |            say "socket" r.i "is ready for reading."
  431. |         end
  432. |
  433. |     timeout is the number of seconds to wait before timing out.
  434. |     0 should be used for polling behaviour (no waiting), and ""
  435. |     should be used to wait indefinitely.  If no timeout value is
  436. |     passed, "" is assumed.  The number must be integral (no fractional
  437. |     values) - if fractional values are required, this could be
  438. |     implemented - contact me.  Non-numeric and negative numbers are
  439. |     considered 0.
  440. |
  441. |     If any of the stem variables are "", or no parameter is passed,
  442. |     no sockets for that type will be checked.  For instance, the
  443. |     SockSelect() call above could have been invoked as either of:
  444. |
  445. |         rc = SockSelect("r.","w.","")
  446. |         rc = SockSelect("r.","w.",)
  447. |
  448. |     The function call SockSelect(,,,x) results in the program pausing for
  449. |     x seconds.
  450. |
  451. |     The return code from SockSelect() is the number of ready sockets or
  452. |     0 if a timeout occurred.  If a timeout occurred, the socket arrays are
  453. |     not modified.
  454.  
  455.    -------------------------------------------------------------------
  456.    SockSend            - implements C function send()
  457.    -------------------------------------------------------------------
  458.  
  459.       rc = SockSend(socket,data<,flags>)
  460.  
  461.       data is a string of text to be sent on the sock.
  462.       flags is a blank delimited list of options: "MSG_OOB", "MSG_DONTROUTE".
  463.  
  464.       Returns the return code from the send() function.
  465.  
  466. |  -------------------------------------------------------------------
  467. |  SockSetSockOpt      - implements C function setsockopt()
  468. |  -------------------------------------------------------------------
  469. |
  470. |     rc = SockSetSockOpt(socket,level,optVar,optVal)
  471. |
  472. |     The only valid value for level is "SOL_SOCKET"
  473. |
  474. |     optVar is the option to set.  See SockGetSockOpt() for valid
  475. |     values.  Some options listed in SockGetSockOpt() are not valid
  476. |     for SockSetSockOpt().  They are:
  477. |        "SO_ERROR"
  478. |        "SO_TYPE"
  479. |
  480. |     optVal is the value to set the option to.  The formats are the
  481. |     same as that of SockGetSockOpt(), except the actual value should
  482. |     be passed in, instead of a variable name.
  483.  
  484.  
  485.    -------------------------------------------------------------------
  486.    SockShutDown        - implements C function shutdown()
  487.    -------------------------------------------------------------------
  488.  
  489.       rc = SockShutDown(socket,how)
  490.  
  491.    -------------------------------------------------------------------
  492.    SockSocket          - implements C function socket()
  493.    -------------------------------------------------------------------
  494.  
  495.       socket = SockSocket(domain,type,protocol)
  496.  
  497.       domain must be "AF_INET".
  498.       type may be one of "SOCK_STREAM", "SOCK_DGRAM", or "SOCK_RAW"
  499.       protocol may be one of "IPPROTO_UDP", "IPPROTO_TCP", or "0"
  500.  
  501.    -------------------------------------------------------------------
  502.    SockSoClose         - implements C function soclose()/close()
  503.    -------------------------------------------------------------------
  504.  
  505.       rc = SockSoClose(socket)
  506.  
  507. ----------------------------------------------------------------------
  508. Utilities Provided
  509. ----------------------------------------------------------------------
  510.  
  511.    killsock.cmd
  512.    ------------
  513.  
  514.    This program takes socket numbers and closes them.  Useful for
  515.    terminating a stubborn server, or cleaning up after accidents.
  516.  
  517.    Use "netstat -s" to get a list of currently open sockets.
  518.  
  519.  
  520.    rnr.cmd
  521.    -------
  522.  
  523.    A very basic news reader.  Used to demonstrate a fairly complex
  524.    application using rxSock functions.
  525.  
  526.  
  527.    test_h.cmd
  528.    ----------
  529.  
  530.    A test program testing address to hostname conversions.
  531.  
  532.  
  533.    test_c.cmd
  534.    test_s.cmd
  535.    ----------
  536.  
  537.    These program are test client/server programs.  Start test_s.cmd
  538.    in one session, and then test_c.cmd in another.  The programs
  539.    exchange data and print some timing information before quitting.
  540.    The server and client can run across two different hosts.  Pass
  541.    the host name of the server as a parameter to test_c.cmd
  542.  
  543.    test*.cmd
  544.    ---------
  545.  
  546.    These test programs test other parts of the RxSock package.  Not
  547.    all that useful, unless you are looking for info on SockSelect(),
  548.    SockIoctl(), Sock?etSockOpt() functions.
  549.  
  550. ----------------------------------------------------------------------
  551. History
  552. ----------------------------------------------------------------------
  553.  
  554. 08/05/93
  555.    - version 1.3
  556.    - fixed stupid bug in SockGetPeerName() and SockGetSockName()
  557.  
  558. 07/16/93
  559.    - version 1.2
  560.    - added SockVersion(), SockClose(), SockIoctl(), SockSelect(),
  561.      SockGetSockOpt(), SockSetSockOpt()
  562.    - changed documentation for SockGetHostByName() and SockGetHostByAddr()
  563.      to reflect what the code actually does
  564.    - now return a list of addresses per host instead of just one
  565.  
  566. 03/11/93
  567.    - version 1.1
  568.    - first release in OS/2 Employee Written Software program
  569.    - simulataneous (or nearly) release on OS2TOOLS
  570.  
  571. distant past
  572.    - version 1.0
  573.  
  574.