home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxsockin.zip / RXSOCK.INF (.txt) < prev   
OS/2 Help File  |  1998-02-12  |  44KB  |  1,822 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. What is RxSock? ΓòÉΓòÉΓòÉ
  3.  
  4. RxSock is a REXX function package providing access to the TCP/IP socket API's 
  5. available for the C programming environment. Therefore, most of the functions 
  6. described in this reference correspond to their  like-named C functions 
  7. available in the TCP/IP socket library. 
  8.  
  9. The function reference below is certainly not exhaustive. It is assumed you are 
  10. already familiar with the basic socket APIs, and can reference the system 
  11. specific ones. A widely available book with information on the basic socket 
  12. APIs is "Internetworking with TCP/IP Volume I:  Principals, Protocols, and 
  13. Architecture" by Douglas Comer (ISBN 0-132-16987-8). 
  14.  
  15. This function package requires TCP/IP support to be active. 
  16.  
  17.  
  18. ΓòÉΓòÉΓòÉ 2. Installation and Removal ΓòÉΓòÉΓòÉ
  19.  
  20. The REXX function package RxSock is contained in the file rxsock.dll. This file 
  21. is to be placed in a directory along your LIBPATH.  To get access to the 
  22. functions in the function package RxSock, execute the following REXX code: 
  23.  
  24.    rc = RxFuncAdd("SockLoadFuncs","rxsock","SockLoadFuncs")
  25.    rc = SockLoadFuncs()
  26.  
  27. To unload the DLL, you should first call the SockDropFuncs() function, then 
  28. exit all CMD.EXE shells. After exiting all the command shells, the DLL will be 
  29. dropped by the system and can be deleted or replaced. 
  30.  
  31.  
  32. ΓòÉΓòÉΓòÉ 3. Parameters and Return Values ΓòÉΓòÉΓòÉ
  33.  
  34. Return values for most functions are the same as the C equivalents, unless 
  35. otherwise noted. There are a number of standard parameter types referenced in 
  36. the function reference. 
  37.  
  38.  socket 
  39.            This is a socket value. It is an integral number. 
  40.  
  41.  domain 
  42.            This is a domain value. The only currently supported domain is 
  43.            "AF_INET". 
  44.  
  45.  address 
  46.            This is the 'stem' of a stemmed variable with the following values: 
  47.  
  48.            address.family 
  49.                           should always be "AF_INET" 
  50.  
  51.            address.port 
  52.                           a port number 
  53.  
  54.            address.addr 
  55.                           a dotted decimal address, or where appropriate, 
  56.                           "INADDR_ANY" 
  57.  
  58.            When this parameter is needed you should set it the name of a stem 
  59.            variable for the function to set (or that the function will read 
  60.            from). For example, if you passed the string "xxx.!" as a parameter, 
  61.            the variables 
  62.  
  63.                          "xxx.!family",
  64.                          "xxx.!port", and
  65.                          "xxx.!addr"
  66.  
  67.            will be set by the function, or queried by the function. 
  68.  
  69.            A null address is an address with the family field being "AF_INET", 
  70.            the port field being 0, and the addr field being "0.0.0.0". 
  71.  
  72.  dotAddress 
  73.            the standard dotted decimal address. For example, the string 
  74.            "9.23.19.63" is a valid address. 
  75.  
  76.  host 
  77.            This is the 'stem' of a stemmed variable with the following values: 
  78.  
  79.            host.name 
  80.                           the standard name of the host 
  81.  
  82.            host.alias.0 
  83.                           number of aliases for this host 
  84.  
  85.            host.alias.1 
  86.                           First alias for this host 
  87.  
  88.            host.alias.n 
  89.                           n'th alias for this host 
  90.  
  91.            host.addrtype 
  92.                           should always be "AF_INET" 
  93.  
  94.            host.addr 
  95.                           a dotted decimal address (default address) 
  96.  
  97.            host.addr.0 
  98.                           number of addresses for this host 
  99.  
  100.            host.addr.1 
  101.                           First address for this host 
  102.  
  103.            host.addr.n 
  104.                           n'th address for this host 
  105.  
  106.            When this parameter is needed you should set it the name of a stem 
  107.            variable for the function to set (or that the function will read 
  108.            from). For example, if you passed the string "xxx.!" as a parameter, 
  109.            the variables 
  110.  
  111.                          "xxx.!name",
  112.                          "xxx.!alias.0", "xxx.!alias.1" ... "xxx.!alias.n",
  113.                          "xxx.!addrtype",
  114.                          "xxx.!addr",
  115.                          "xxx.!addr.0", "xxx.!addr.1" ... "xxx.!addr.n"
  116.  
  117.            will be set by the function, or queried by the function. 
  118.  
  119.  
  120. ΓòÉΓòÉΓòÉ 4. Special Note on Stemmed Variables ΓòÉΓòÉΓòÉ
  121.  
  122. The address and host type of parameters are stemmed variable names. 
  123. Traditionally, you would pass a string like "addr." as a parameter, and expect 
  124. to have the variables addr.family, addr.port, and addr.addr set by the 
  125. function. In the examples above though, using a stem like "addr.!" was shown. 
  126. The exclamation point helps to distinguish the tail values, so they won't get 
  127. mis-used as normal variables. For instance, look at the following code: 
  128.  
  129.    port = 923
  130.    sNew =  SockAccept(sOld,"addr.")
  131.    say addr.port
  132.  
  133. You might expect the say statement to write the port number of the accepted 
  134. socket. Instead it writes the value of the variable addr.923, since the port 
  135. variable is SET to a value. 
  136.  
  137. Since you probably don't normally use exclamation points in your variables, 
  138. it's unlikely that you will be using the variable "!port" in your program. 
  139.  
  140. Also note, some folk prefer other characters, including "_", "0", and "1" (the 
  141. digits are allowed to prefix tail values and are very secure against this kind 
  142. of accidental misuse - don't use them because the characters are hard to 
  143. distinguish from O, I, and l). 
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 5. Special Variables ΓòÉΓòÉΓòÉ
  147.  
  148. There are two variables that are maintained by the system: 
  149.  
  150.      Variable errno 
  151.  
  152.      Variable h_errno 
  153.  
  154.  
  155. ΓòÉΓòÉΓòÉ 5.1. Variable errno ΓòÉΓòÉΓòÉ
  156.  
  157. The errno variable is set after every REXX Socket Library (RxSock) function 
  158. call. It will have one of the following values (or a numeric value if the 
  159. number isn't one of these values): 
  160.  
  161.    "EWOULDBLOCK"
  162.    "EINPROGRESS"
  163.    "EALREADY"
  164.    "ENOTSOCK"
  165.    "EDESTADDRREQ"
  166.    "EMSGSIZE"
  167.    "EPROTOTYPE"
  168.    "ENOPROTOOPT"
  169.    "EPROTONOSUPPORT"
  170.    "ESOCKTNOSUPPORT"
  171.    "EOPNOTSUPP"
  172.    "EPFNOSUPPORT"
  173.    "EAFNOSUPPORT"
  174.    "EADDRINUSE"
  175.    "EADDRNOTAVAIL"
  176.    "ENETDOWN"
  177.    "ENETUNREACH"
  178.    "ENETRESET"
  179.    "ECONNABORTED"
  180.    "ECONNRESET"
  181.    "ENOBUFS"
  182.    "EISCONN"
  183.    "ENOTCONN"
  184.    "ESHUTDOWN"
  185.    "ETOOMANYREFS"
  186.    "ETIMEDOUT"
  187.    "ECONNREFUSED"
  188.    "ELOOP"
  189.    "ENAMETOOLONG"
  190.    "EHOSTDOWN"
  191.    "EHOSTUNREACH"
  192.    "ENOTEMPTY"
  193.  
  194. Note the value is set even if the function that was called does not 
  195. neccessarily set the variable, in which case the value has no meaning. The 
  196. value 0 indicates no error occurred. 
  197.  
  198.  
  199. ΓòÉΓòÉΓòÉ 5.2. Variable h_errno ΓòÉΓòÉΓòÉ
  200.  
  201. The h_errno variable is set after every REXX Socket Library (RxSock)  function 
  202. call. It will have one of the following values (or a numeric value if the 
  203. number isn't one of these values): 
  204.  
  205.    "HOST_NOT_FOUND"
  206.    "TRY_AGAIN"
  207.    "NO_RECOVERY"
  208.    "NO_ADDRESS"
  209.  
  210. Note the value is set even if the function that was called does not 
  211. neccessarily set the variable, in which case the value has no meaning. The 
  212. value 0 indicates no error occurred. 
  213.  
  214.  
  215. ΓòÉΓòÉΓòÉ 6. Function Reference ΓòÉΓòÉΓòÉ
  216.  
  217. The following chapters provide a description of how the individal functions 
  218. contained in the REXX Socket Library RxSock are invoked from the REXX 
  219. programming environment: 
  220.  
  221.      SockLoadFuncs 
  222.  
  223.      SockDropFuncs 
  224.  
  225.      SockVersion 
  226.  
  227.      SockAccept 
  228.  
  229.      SockBind 
  230.  
  231.      SockClose 
  232.  
  233.      SockConnect 
  234.  
  235.      SockGetHostByAddr 
  236.  
  237.      SockGetHostByName 
  238.  
  239.      SockGetHostId 
  240.  
  241.      SockGetPeerName 
  242.  
  243.      SockGetSockName 
  244.  
  245.      SockGetSockOpt 
  246.  
  247.      SockInit 
  248.  
  249.      SockIoctl 
  250.  
  251.      SockListen 
  252.  
  253.      SockPSock_Errno 
  254.  
  255.      SockRecv 
  256.  
  257.      SockRecvFrom 
  258.  
  259.      SockSelect 
  260.  
  261.      SockSend 
  262.  
  263.      SockSendTo 
  264.  
  265.      SockSetSockOpt 
  266.  
  267.      SockShutDown 
  268.  
  269.      SockSock_Errno 
  270.  
  271.      SockSocket 
  272.  
  273.      SockSoClose 
  274.  
  275.  
  276. ΓòÉΓòÉΓòÉ 6.1. SockLoadFuncs ΓòÉΓòÉΓòÉ
  277.  
  278. The SockLoadFuncs() call loads all the functions in the REXX Socket Library 
  279. RxSock package. 
  280.  
  281. Syntax: 
  282.  
  283.    SockLoadFuncs([parm])
  284.  
  285. Parameters: 
  286.  
  287. If any parameter parm is passed to this function, it will bypass the 
  288. program/copyright information normally displayed. All parameters are ignored 
  289. except to determine whether or not to bypass displaying the information. 
  290.  
  291.  
  292. ΓòÉΓòÉΓòÉ 6.2. SockDropFuncs ΓòÉΓòÉΓòÉ
  293.  
  294. The SockDropFuncs call drops all the functions in the REXX Socket Library 
  295. RxSock package. 
  296.  
  297. Syntax: 
  298.  
  299.    SockDropFuncs()
  300.  
  301. To unload the dynamic load library (DLL), you should first call 
  302. SockDropFuncs(), then exit all CMD.EXE shells. After exiting all command 
  303. shells, the DLL will be dropped by the system and can be deleted or replaced. 
  304.  
  305.  
  306. ΓòÉΓòÉΓòÉ 6.3. SockVersion ΓòÉΓòÉΓòÉ
  307.  
  308. The SockVersion() call provides the version number of the REXX Socket Library 
  309. RxSock. 
  310.  
  311. Syntax: 
  312.  
  313.    vers = SockVersion()
  314.  
  315. Return Values: 
  316.  
  317. The returned result consists of an integral version number followed by a dot 
  318. followed by  an integral subversion number. An example is "2.0". 
  319.  
  320. Prior to version 1.2, this function did not exist. To check if a previous 
  321. version of RxSock is installed, use the following code, after loading the 
  322. function package with SockLoadFuncs(). 
  323.  
  324.    /* oldVersion will be '1' if a version of RxSock < 1.2 is loaded */
  325.    oldVersion = (1 = RxFuncQuery("SockVersion"))
  326.  
  327.  
  328. ΓòÉΓòÉΓòÉ 6.4. SockAccept ΓòÉΓòÉΓòÉ
  329.  
  330. The SockAccept() call accepts a connection request from a remote host. 
  331.  
  332. Syntax: 
  333.  
  334.    csocket = SockAccept(socket[, address])
  335.  
  336. Parameters: 
  337.  
  338.  socket    is the socket descriptor 
  339.  
  340.  address   is a REXX stem variable that contains the  socket address of  the 
  341.            connection client when the SockAccept() call returns.  This 
  342.            parameter is optional. It can be omitted if the caller is not 
  343.            interested in the client address. 
  344.  
  345.  Description: 
  346.  
  347.  This call is used by a server acting in a connection-oriented mode to accept a 
  348.  connection request from a client.  The call accepts the first connection on 
  349.  its queue of pending  connection requests. The SockAccept() call creates a new 
  350.  socket descriptor with the same  properties as socket and returns it to the 
  351.  caller. The new socket descriptor cannot be used to accept new connections. 
  352.  The original socket socket, remains available to accept more connection 
  353.  requests. 
  354.  
  355.  If the queue has no pending connection requests, SockAccept() blocks the 
  356.  caller unless  socket is in nonblocking mode.  If no connection requests are 
  357.  queued and socket is in  nonblocking mode, SockAccept() returns -1 and sets 
  358.  the return code  to EWOULDBLOCK. 
  359.  
  360.  The socket parameter must be a socket descriptor created  with the 
  361.  SockSocket() call. It is usually  bound to an address with the SockBind() call 
  362.  and must be made capable of accepting connections with the SockListen() call. 
  363.  The SockListen() call marks the socket as one that accepts connections and 
  364.  allocates a queue to hold pending connection requests. The SockListen() call 
  365.  allows the caller to place an upper boundary on the size of the queue. 
  366.  
  367.  The address parameter is where the connection requester address is placed. It 
  368.  is optional. 
  369.  
  370.  You cannot screen requesters without calling SockAccept(). The application 
  371.  cannot tell the  system the requesters it will accept connections from.  The 
  372.  caller can, however, choose to close a connection  immediately after 
  373.  discovering the identity of the requester. 
  374.  
  375.  The SockSelect() call can be used to check the socket for incoming connection 
  376.  requests. 
  377.  
  378.  Return Values: 
  379.  
  380.  A non-negative client socket descriptor csocket indicates success;  the value 
  381.  -1 indicates an error. You can get the specific error code by calling 
  382.  SockSock_Errno() or SockPSock_Errno().  These are: 
  383.  
  384.  ENOTSOCK 
  385.            The socket parameter is not a valid socket descriptor. 
  386.  
  387.  EINTR 
  388.            Interrupted system call. 
  389.  
  390.  EINVAL 
  391.            SockListen() was not called for socket socket. 
  392.  
  393.  EOPNOTSUPP 
  394.            The socket parameter is not connection-oriented. 
  395.  
  396.  EWOULDBLOCK 
  397.            The socket parameter is in nonblocking mode and no connections are 
  398.            on the queue. 
  399.  
  400.  ECONNABORTED 
  401.            The software caused a connection close. 
  402.  
  403.  NOTE: SockAccept() interfaces to the C function accept(). 
  404.  
  405.  
  406. ΓòÉΓòÉΓòÉ 6.5. SockBind ΓòÉΓòÉΓòÉ
  407.  
  408. The SockBind() call binds a local name to the socket. 
  409.  
  410. Syntax: 
  411.  
  412.    rc = SockBind(socket, address)
  413.  
  414. Parameters: 
  415.  
  416.  socket    is the socket descriptor returned by a previous call to SockSocket() 
  417.  
  418.  address   is a REXX stem variable containing the address that is to be bound 
  419.            to socket 
  420.  
  421.  Description: 
  422.  
  423.  The SockBind() call binds a unique local  name address to the socket with 
  424.  descriptor socket.  After calling SockSocket(), a descriptor does not have a 
  425.  name  associated with it.  However, it does belong to a particular addressing 
  426.  family as specified when SockSocket() is called. 
  427.  
  428.  Because socket was created in the AF_INET domain, the fields of the REXX stem 
  429.  variable address are expected  to be as follows: 
  430.  
  431.  The family field must be set to "AF_INET".  The port field is set to the port 
  432.  to which  the application must bind. If port is set to 0, the caller leaves it 
  433.  to the system to assign an available port.  The application can call 
  434.  SockGetSockName() to discover the port number assigned. The addr field is set 
  435.  to the internet address. On hosts with more than  one network interface 
  436.  (called multihomed hosts), a caller can select the interface with which it is 
  437.  to bind. 
  438.  
  439.  Subsequently, only UDP packets and TCP connection requests from this interface 
  440.  (which match the bound name) are routed to the application. If addr is set to 
  441.  "INADDR_ANY", the caller is requesting that the socket be  bound to all 
  442.  network interfaces on the host.  Subsequently, UDP packets and TCP 
  443.  connections from all interfaces (which match the bound name) are routed to the 
  444.  application. This becomes important when a server offers a service to multiple 
  445.  networks.  By leaving the address unspecified, the server can accept all UDP 
  446.  packets and TCP  connection requests made for its port, regardless of the 
  447.  network interface on which the requests arrived. 
  448.  
  449.  Return Values: 
  450.  
  451.  The value 0 indicates success; the value -1 indicates an error. You can get 
  452.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  453.  These are: 
  454.  
  455.  EADDRINUSE 
  456.            The address is already in use. See the SO_REUSEADDR option 
  457.            described under SockGetSockOpt() and the SO_REUSEADDR option 
  458.            described under SockSetSockOpt(). 
  459.  
  460.  EADDRNOTAVAIL 
  461.            The address specified is not valid on this host. For example, the 
  462.            Internet address does not specify a valid network interface. 
  463.  
  464.  EAFNOSUPPORT 
  465.            The address family is not supported. 
  466.  
  467.  ENOTSOCK 
  468.            The socket parameter is not a valid socket descriptor. 
  469.  
  470.  EINVAL 
  471.            The socket is already bound to an address. 
  472.  
  473.  ENOBUFS 
  474.            No buffer space is available. 
  475.  
  476.  NOTE: SockBind() interfaces to the C function bind(). 
  477.  
  478.  
  479. ΓòÉΓòÉΓòÉ 6.6. SockClose ΓòÉΓòÉΓòÉ
  480.  
  481. The SockClose() call shuts down a socket and frees resources allocated to the 
  482. socket. 
  483.  
  484. Syntax: 
  485.  
  486.    rc = SockClose(socket)
  487.  
  488. Parameter: 
  489.  
  490.  socket    is the Socket descriptor of the socket to be closed. 
  491.  
  492.  Description: 
  493.  
  494.  This call shuts down the socket associated with the socket descriptor socket, 
  495.  and frees resources allocated to the socket. If socket refers to a connected 
  496.  socket, the connection is closed. 
  497.  
  498.  If the SO_LINGER socket option is enabled  (see SockSetSockOpt() for 
  499.  additional information),  then the task will try to send any queued data. If 
  500.  the SO_LINGER socket option is disabled, then the task will flush any data 
  501.  queued to be sent. 
  502.  
  503.  Return Values: 
  504.  
  505.  The value 0 indicates success; the value -1 indicates an error. You can get 
  506.  the specific  error code by calling SockSock_Errno() or SockPSock_Errno(). The 
  507.  error codes are: 
  508.  
  509.  ENOTSOCK 
  510.            The socket parameter is not a valid socket descriptor. 
  511.  
  512.  EALREADY 
  513.            The socket socket is marked nonblocking, and a previous connection 
  514.            attempt has not completed. 
  515.  
  516.  The Function SockClose() is exactly the same as SockSoClose(). 
  517.  
  518.  NOTE: SockClose() interfaces to the C function soclose() or in the Windows 
  519.  environments to closesocket(). 
  520.  
  521.  
  522. ΓòÉΓòÉΓòÉ 6.7. SockConnect ΓòÉΓòÉΓòÉ
  523.  
  524. The SockConnect() socket call requests a connection to a remote host. 
  525.  
  526. Syntax: 
  527.  
  528.    rc = SockConnect(socket, address)
  529.  
  530. Parameters: 
  531.  
  532.  socket    is the socket descriptor used to originate the connection request 
  533.  
  534.  address   is a REXX stem variable containing  the address of the socket to 
  535.            which a  connection will be attempted 
  536.  
  537.  Description: 
  538.  
  539.  The SockConnect() call performs two tasks when  called for a stream socket: 
  540.  
  541.    1. Completes the binding if necessary for a socket 
  542.  
  543.    2. Attempts to create a connection between two sockets. 
  544.  
  545.  This call is used by the client side of socket-based applications to establish 
  546.  a connection with a server.  The remote server must have a passive open 
  547.  pending. This means the  server must successfully call SockBind() and 
  548.  SockListen(); otherwise, SockConnect() returns -1 and the error value is set 
  549.  to ECONNREFUSED. 
  550.  
  551.  In the Internet communication domain, a timeout occurs if a connection to the 
  552.  remote host  is not successful within 75 seconds (1 minute and 15 seconds). 
  553.  
  554.  If the socket is in blocking mode, the SockConnect() call blocks the caller 
  555.  until the connection is established or until an error is received. If the 
  556.  socket is in nonblocking  mode, SockConnect() returns -1 and sets the error 
  557.  value to EINPROGRESS if the connection was successfully initiated. The caller 
  558.  can test the completion of the connection setup by calling: 
  559.  
  560.      SockSelect(), to test for the ability to write to the socket 
  561.  
  562.      SockGetsockOpt(), with option SO_ERROR, to test if the connection 
  563.       succeeded 
  564.  
  565.  Stream sockets can call SockConnect() only once. 
  566.  
  567.  Datagram or raw sockets: The SockConnect() call specifies the destination 
  568.  peer address when called for a datagram or raw socket. Normally,  datagram and 
  569.  raw sockets use connectionless data transfer calls such as  SockSendTo() and 
  570.  SockRecvFrom(). However, applications can call SockConnect() to specify and 
  571.  store the destination peer address for this socket. The system will then know 
  572.  which address to send data to on this socket. This method  of communication 
  573.  allows datagram and raw sockets to be connected.  However, data is still not 
  574.  guaranteed to be delivered. Thus the normal  features of connectionless mode 
  575.  sockets are maintained. The address is  remembered until another SockConnect() 
  576.  call is made. This permits the use of SockRecv() and SockSend(), which are 
  577.  usually reserved for  connection-oriented sockets. The application can still 
  578.  use SockSendTo(),  SockRecvFrom(). The advantage of calling SockConnect()  and 
  579.  being connected is that the destination peer address does not have to be 
  580.  specified for all datagrams sent. 
  581.  
  582.  Datagram and raw sockets can call SockConnect() multiple times. The 
  583.  application can reset their destination address by specifying a new address on 
  584.  the SockConnect() call. In addition, the socket can be returned to operate in 
  585.  a connectionless mode by calling SockConnect() with a null destination 
  586.  address. The null address is created by setting the REXX stem variable 
  587.  address as follows: 
  588.  
  589.  The family field is set to "AF_INET",  the port field is set to 0, and  the 
  590.  addr field is set to "0.0.0.0". 
  591.  
  592.  The call to SockConnect will return -1,  indicating that the connection to the 
  593.  null address cannot be established. Calling SockSock_Errno() will return 
  594.  EADDRNOTAVAIL. For more information  on connecting datagram sockets, see 
  595.  "Description" for SockSendTo(). 
  596.  
  597.  Return Values: 
  598.  
  599.  The value 0 indicates success; the value -1 indicates an error. You can get 
  600.  the specific  error code by calling SockSock_Errno() or SockPSock_Errno(). 
  601.  These are: 
  602.  
  603.  EADDRNOTAVAIL 
  604.            The calling host cannot reach the specified destination. 
  605.  
  606.  EAFNOSUPPORT 
  607.            The address family is not supported. 
  608.  
  609.  EALREADY 
  610.            The socket socket is marked nonblocking,  and a previous connection 
  611.            attempt has not completed. 
  612.  
  613.  ENOTSOCK 
  614.            The socket parameter is not a valid socket descriptor. 
  615.  
  616.  ECONNREFUSED 
  617.            The connection request was rejected by the destination host. 
  618.  
  619.  EINPROGRESS 
  620.            The socket socket is marked nonblocking, and the connection cannot 
  621.            be completed immediately. The EINPROGRESS value does not indicate an 
  622.            error condition. 
  623.  
  624.  EINTR 
  625.            Interrupted system call. 
  626.  
  627.  EISCONN 
  628.            The socket socket is already connected. 
  629.  
  630.  ENETUNREACH 
  631.            The network cannot be reached from this host. 
  632.  
  633.  ETIMEDOUT 
  634.            The connection establishment timed out before a connection was made. 
  635.  
  636.  ENOBUFS 
  637.            No buffer space is available. 
  638.  
  639.  EOPNOTSUPP 
  640.            The operation is not supported on socket socket. 
  641.  
  642.  NOTE: SockConnect interfaces to the C function connect(). 
  643.  
  644.  
  645. ΓòÉΓòÉΓòÉ 6.8. SockGetHostByAddr ΓòÉΓòÉΓòÉ
  646.  
  647. The SockGetHostByAddr() call retrieves host information on a specified host  on 
  648. the network using its address. 
  649.  
  650. Syntax: 
  651.  
  652.    rc = SockGetHostByAddr(dotAddress, host[, domain])
  653.  
  654. Parameters: 
  655.  
  656.  dotAddress is the standard dotted decimal address of the host 
  657.  
  658.  host      is a REXX stem variable that is to receive the information on the 
  659.            host. 
  660.  
  661.  domain    is the domain value. The only supported domain is "AF_INET". This 
  662.            parameter is optional. The default value is "AF_INET". 
  663.  
  664.  Description: 
  665.  
  666.  This socket call retrieves information on the host identified by its 
  667.  dotAddress. 
  668.  
  669.  Return Values: 
  670.  
  671.  Returns 1 for success, 0 for error. 
  672.  
  673.  NOTE: SockGetHostByAdress() interfaces to the C function gethostbyaddr(). 
  674.  
  675.  
  676. ΓòÉΓòÉΓòÉ 6.9. SockGetHostByName ΓòÉΓòÉΓòÉ
  677.  
  678. The SockGetHostByName() call retrieves host information on a specified host  on 
  679. the network using its name. 
  680.  
  681. Syntax: 
  682.  
  683.    rc = SockGetHostByName(nameAddress, host)
  684.  
  685. Parameters: 
  686.  
  687.  nameAddress should be the textual name of a host, for example "www.ibm.com". 
  688.  
  689.  host      is the name of a REXX stem variable that is to receive the 
  690.            information on the host. 
  691.  
  692.  Description: 
  693.  
  694.  This socket call retrieves information on the host identified by its hostname 
  695.  or any alias of it. 
  696.  
  697.  Return Values: 
  698.  
  699.  Returns 1 for success, 0 for error. 
  700.  
  701.  NOTE: SockGetHostByName() interfaces to the C function gethostbyname(). 
  702.  
  703.  
  704. ΓòÉΓòÉΓòÉ 6.10. SockGetHostId ΓòÉΓòÉΓòÉ
  705.  
  706. The SockGetHostId() call retrieves the dotAddress of the local host. 
  707.  
  708. Syntax: 
  709.  
  710.    dotAddress = SockGetHostId()
  711.  
  712. Description: 
  713.  
  714. This socket call retrieves the dotAddress of the local host. 
  715.  
  716. Return Value: 
  717.  
  718. The dotAddress of the local host. 
  719.  
  720. NOTE: SockGetHostId() interfaces to the C function gethostid(). 
  721.  
  722.  
  723. ΓòÉΓòÉΓòÉ 6.11. SockGetPeerName ΓòÉΓòÉΓòÉ
  724.  
  725. The SockGetPeerName() call gets the name of the peer connected to a socket. 
  726.  
  727. Syntax: 
  728.  
  729.    rc = SockGetPeerName(socket, address)
  730.  
  731. Parameter: 
  732.  
  733.  socket    is the socket descriptor 
  734.  
  735.  address   is a REXX stem variable that is to contain the address  of the peer 
  736.            connected to socket socket is returned. 
  737.  
  738.  Description: 
  739.  
  740.  This call returns the address of the peer connected to socket socket. This 
  741.  call operates only on connected sockets. 
  742.  
  743.  Return Values: 
  744.  
  745.  The value 0 indicates success; the value -1 indicates an error. You can get 
  746.  the specific  error code by calling SockSock_Errno() or SockPSock_Errno(). 
  747.  These are: 
  748.  
  749.  ENOTSOCK 
  750.            The socket parameter is not a valid socket descriptor. 
  751.  
  752.  ENOTCONN 
  753.            The socket is not connected. 
  754.  
  755.  ENOBUFS 
  756.            No buffer space is available. 
  757.  
  758.  NOTE: SockGetPeerName() interfaces to the C function getpeername(). 
  759.  
  760.  
  761. ΓòÉΓòÉΓòÉ 6.12. SockGetSockName ΓòÉΓòÉΓòÉ
  762.  
  763. The SockGetSockName() call gets the local socket name. 
  764.  
  765. Syntax: 
  766.  
  767.    rc = SockGetSockName(socket, address)
  768.  
  769. Parameters: 
  770.  
  771.  socket    is the socket descriptor 
  772.  
  773.  address   is a REXX stem variable that is to receive the address of the 
  774.            socket being returned. 
  775.  
  776.  Description: 
  777.  
  778.  This call returns the address for the socket specified by the socket parameter 
  779.  in the REXX stem variable address.  It returns the address to the socket that 
  780.  has been bound.  If the socket is not bound to an address, the call returns a 
  781.  null address. 
  782.  
  783.  The returned null address is a REXX stem variable with the family field set to 
  784.  "AF_INET", the port field set to 0, and the addr field  set to "0.0.0.0". 
  785.  
  786.  Sockets are explicitly assigned an address after a successful call to 
  787.  SockBind(). Stream sockets are implicitly assigned an address after a 
  788.  successful call to SockConnect() or SockAccept() if SockBind() was not called. 
  789.  
  790.  The SockGetSockName() call is often used to discover the port assigned to a 
  791.  socket after the  socket has been implicitly bound to a port. For example, an 
  792.  application can call SockConnect()  without previously calling SockBind(). In 
  793.  this case, the SockConnect() call completes the binding  necessary by 
  794.  assigning a port to the socket. 
  795.  
  796.  Return Values: 
  797.  
  798.  The value 0 indicates success; the value -1 indicates an error. You can get 
  799.  the specific  error code by calling SockSock_Errno() or SockPSock_Errno(). 
  800.  These are: 
  801.  
  802.  ENOTSOCK 
  803.            The socket parameter is not a valid socket descriptor. 
  804.  
  805.  ENOBUFS 
  806.            No buffer space available. 
  807.  
  808.  NOTE: SockGetSockName() interfaces to the C function getsockname(). 
  809.  
  810.  
  811. ΓòÉΓòÉΓòÉ 6.13. SockGetSockOpt ΓòÉΓòÉΓòÉ
  812.  
  813. The SockGetSockOpt() call gets the socket options associated with a socket. 
  814.  
  815. Syntax: 
  816.  
  817.    rc = SockGetSockOpt(socket, level, optName, optVal)
  818.  
  819. Parameters: 
  820.  
  821.  socket    Socket descriptor 
  822.  
  823.  level     Specifies which option level is being queried for the specified 
  824.            optname 
  825.  
  826.  optname   Name of a specified socket option. Only one option can be specified 
  827.            on a call. 
  828.  
  829.  optval    is the variable to receive the option data requested 
  830.  
  831.  Description: 
  832.  
  833.  This call returns the value of a socket option at the socket  level. It can be 
  834.  called for sockets of all domain types. Some options are supported only for 
  835.  specific socket types. You must specify the level of  the option and the name 
  836.  of the option to retrieve option values.  The only supported level is 
  837.  SOL_SOCKET. 
  838.  
  839.  The optval parameter is a variable where the option values  are returned. For 
  840.  socket options that are  Boolean, the option is enabled if optval is nonzero 
  841.  and disabled if optval is 0. 
  842.  
  843.  The following options are recognized for SOL_SOCKET: 
  844.  
  845.  SO_BROADCAST 
  846.            (datagram sockets only) Retrieves the current ability  of the socket 
  847.            to broadcast messages. If this option is  enabled, it allows the 
  848.            application to send broadcast  messages over socket, if the 
  849.            interface specified in the destination supports broadcasting of 
  850.            packets. 
  851.  
  852.  SO_DEBUG 
  853.            Retrieves the current ability for recording debug information for a 
  854.            socket. 
  855.  
  856.  SO_DONTROUTE 
  857.            Retrieves the current ability for the socket to bypass  routing. 
  858.            When this option is enabled, it causes  outgoing messages to bypass 
  859.            the standard routing  algorithm and be directed to the appropriate 
  860.            network  interface, according to the network portion of the 
  861.            destination address. When enabled, packets can be sent only to 
  862.            directly connected networks (networks  this host has an interface 
  863.            for). 
  864.  
  865.  SO_ERROR 
  866.            Returns any pending error on the socket and clears  the error 
  867.            status. It can be used to check for  asynchronous errors on 
  868.            connected datagram sockets or for other asynchronous errors (errors 
  869.            that are not  returned explicitly by one of the socket calls). 
  870.  
  871.  SO_KEEPALIVE 
  872.            (stream sockets only) Retrieves the current ability of  the socket 
  873.            to send keepalive packets. TCP uses a  timer called the keepalive 
  874.            timer. This timer is used  to monitor idle connections that might 
  875.            have been  disconnected because of a peer crash or timeout. If  this 
  876.            option is set on, a keepalive packet is periodically sent to the 
  877.            peer. This is mainly used to  allow servers to close connections 
  878.            that are no longer  active as a result of clients going away without 
  879.            properly closing connections. 
  880.  
  881.  SO_LINGER 
  882.            (stream sockets only) Retrieves the current ability of  the socket 
  883.            to linger on close if data is present.  When this option is enabled 
  884.            and there is unsent data  present when SockSoClose() is called, the 
  885.            calling  application is blocked during the SockSoClose() call until 
  886.            the data is transmitted or the connection has timed  out. If this 
  887.            option is disabled, the SockSoClose() call returns without blocking 
  888.            the caller, and TCP waits to  try to send the data. Although the 
  889.            data transfer is  usually successful, it cannot be guaranteed, 
  890.            because  TCP waits only a finite amount of time trying to send the 
  891.            data. 
  892.  
  893.  SO_OOBINLINE 
  894.            (stream sockets only) Retrieves the current ability of  the socket 
  895.            to receive out-of-band data. When this  option is enabled, it causes 
  896.            out-of-band data to be  placed in the normal data input queue as it 
  897.            is  received, making it available to SockRecv(), and  SockRecvFrom() 
  898.            without having to specify the MSG_OOB  flag in those calls. When 
  899.            this option is disabled, it  causes out-of-band data to be placed in 
  900.            the priority  data input queue as it is received, making it 
  901.            available  to SockRecv(), and SockRecvFrom(), only by specifying the 
  902.            MSG_OOB flag in those calls. 
  903.  
  904.  SO_RCVBUF 
  905.            Retrieves buffer size for input. This value tailors the  receive 
  906.            buffer size for specific application needs, such  as increasing the 
  907.            buffer size for high-volume connections. 
  908.  
  909.  SO_RCVLOWAT 
  910.            Retrieves receive low-water mark information. 
  911.  
  912.  SO_RCVTIMEO 
  913.            Retrieves the timeout value for a receive operation. 
  914.  
  915.  SO_REUSEADDR 
  916.            (stream and datagram sockets only) Retrieves the  current ability of 
  917.            the socket to reuse local addresses.  When enabled, this option 
  918.            allows local addresses that  are already in use to be bound. This 
  919.            alters the  normal algorithm used in the SockBind() call. At connect 
  920.            time, the system checks to be sure that no local  address and port 
  921.            have the same foreign address and port. The error EADDRINUSE is 
  922.            returned if the  association already exists. 
  923.  
  924.  SO_SNDBUF 
  925.            Retrieves the size of the send buffer. This value  tailors the send 
  926.            buffer size for specific application  needs, such as increasing the 
  927.            buffer size for high-volume connections. 
  928.  
  929.  SO_SNDLOWAT 
  930.            Retrieves send low-water mark information. This value is ignored for 
  931.            nonblocking calls. For the Internet domain, this value is not used. 
  932.  
  933.  SO_SNDTIMEO 
  934.            Retrieves the timeout value for a send operation. 
  935.  
  936.  SO_TYPE 
  937.            Returns the type of the socket. On return, the  integer pointed to 
  938.            by optval is set to one of the  following: "STREAM", "DGRAM", "RAW", 
  939.            or "UNKNOWN". 
  940.  
  941.  SO_USELOOPBACK 
  942.            Bypasses hardware when possible. 
  943.  
  944.  Most of the options' values are integral. The exception is "SO_LINGER" that 
  945.  contains two blank delimited integers: 
  946.  
  947.    1. the l_onoff value.  The l_onoff field is set to zero if the SO_LINGER 
  948.       option is being disabled. A nonzero value enables the option. 
  949.  
  950.    2. the l_linger value. The l_linger field specifies the amount of time in 
  951.       seconds to linger on close. A value of zero will cause SockSoClose() to 
  952.       wait until the disconnect completes. 
  953.  
  954.  Return Values: 
  955.  
  956.  The value 0 indicates success; the value -1 indicates an error. You can get 
  957.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  958.  These are: 
  959.  
  960.  EADDRINUSE 
  961.            The address is already in use. 
  962.  
  963.  ENOTSOCK 
  964.            The socket parameter is not a valid socket descriptor. 
  965.  
  966.  ENOPROTOOPT 
  967.            The optname parameter or level parameter is not recognized. 
  968.  
  969.  NOTE: SockGetSockOpt() interfaces to the C function getsockopt(). 
  970.  
  971.  
  972. ΓòÉΓòÉΓòÉ 6.14. SockInit ΓòÉΓòÉΓòÉ
  973.  
  974. The SockInit() call initializes the socket data structures. 
  975.  
  976. Syntax: 
  977.  
  978.    rc = SockInit()
  979.  
  980. Description: 
  981.  
  982. This call initializes the socket data structures and checks whether  the TCP/IP 
  983. network is active. Therefore, SockInit() should be called at the beginning of 
  984. each program that uses SockSocket(). 
  985.  
  986. SockInit() is not strictly required as initalization is done for each REXX 
  987. Function Library (RxSock) function in case the initialization has not yet 
  988. occurred. For this reason, the explicit initialization function is not 
  989. available in all system environments. 
  990.  
  991. Return Values: 
  992.  
  993. The value 0 indicates success; the value 1 indicates an error. 
  994.  
  995. NOTE: SockInit() interfaces to the C function sock_init(). 
  996.  
  997.  
  998. ΓòÉΓòÉΓòÉ 6.15. SockIoctl ΓòÉΓòÉΓòÉ
  999.  
  1000. The SockIoctl() call performs special operations on socket. 
  1001.  
  1002. Syntax: 
  1003.  
  1004.    rc = SockIoctl(socket, ioctlCmd, ioctlData)
  1005.  
  1006. Parameters: 
  1007.  
  1008.  socket    Socket descriptor 
  1009.  
  1010.  ioctlCmd  is the ioctl command to perform. 
  1011.  
  1012.  ioctlData is the command specific value. 
  1013.  
  1014.  Description: 
  1015.  
  1016.  This call controls the operating characteristics of sockets.  The ioctlData 
  1017.  parameter is a variable containing data associated with the particular 
  1018.  command, and its format depends on the command that is requested. Valid 
  1019.  commands are: 
  1020.  
  1021.  FIONBIO 
  1022.            Sets or clears nonblocking input/output for a socket.  When this 
  1023.            option is set, input/output calls will not block  until the call is 
  1024.            completed. The data parameter is an integer. If the integer is 0, 
  1025.            nonblocking  input/output on the socket is cleared. Otherwise, the 
  1026.            socket is set for nonblocking input/output. 
  1027.  
  1028.  FIONREAD 
  1029.            Gets the number of immediately readable bytes for the  socket. The 
  1030.            data parameter is an integer.  Sets the value of the integer to the 
  1031.            number of immediately readable characters for the socket. 
  1032.  
  1033.  Return Values: 
  1034.  
  1035.  The value 0 indicates success; the value -1 indicates an error. You can get 
  1036.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  1037.  These are: 
  1038.  
  1039.  ENOTSOCK 
  1040.            The socket parameter is not a valid socket descriptor. 
  1041.  
  1042.  EINVAL 
  1043.            The request is not valid or not supported. 
  1044.  
  1045.  EOPNOTSUPP 
  1046.            The operation is not supported on the socket. 
  1047.  
  1048.  NOTE: SockIoctl() interfaces to the C function ioctl() or in the Windows 
  1049.  environments to ioctlsocket(). 
  1050.  
  1051.  
  1052. ΓòÉΓòÉΓòÉ 6.16. SockListen ΓòÉΓòÉΓòÉ
  1053.  
  1054. The SockListen() call completes the binding necessary for a socket to accept 
  1055. connections and creates a connection request queue for incoming requests. 
  1056.  
  1057. Syntax: 
  1058.  
  1059.    rc = SockListen(socket, backlog)
  1060.  
  1061. Parameter: 
  1062.  
  1063.  socket    is the socket descriptor. 
  1064.  
  1065.  backlog   controls the maximum queue length for pending connections. 
  1066.  
  1067.  Description: 
  1068.  
  1069.  The SockListen() call performs two tasks: 
  1070.  
  1071.    1. Completes the binding necessary for a socket socket, if SockBind() has 
  1072.       not been called for socket 
  1073.  
  1074.    2. Creates a connection request queue of length backlog, to queue incoming 
  1075.       connection requests. 
  1076.  
  1077.  When the queue is full, additional connection requests are ignored. 
  1078.  
  1079.  The SockListen() call indicates a readiness to accept client connection 
  1080.  requests.  It transforms an active socket into a passive socket. After 
  1081.  SockListen() is  called, socket can never be used as an active socket to 
  1082.  initiate connection requests.  SockListen() is called after allocating a 
  1083.  socket with SockSocket() and  after binding a name to socket with SockBind(). 
  1084.  SockListen() must be called before calling SockAccept(). 
  1085.  
  1086.  SockListen() can only be called on connection-oriented sockets. 
  1087.  
  1088.  If the backlog parameter is less than 0, then SockListen() interprets backlog 
  1089.  as 0. If the backlog parameter is greater than the maximum value as defined by 
  1090.  the network system then SockListen()  interprets backlog as this maximum 
  1091.  value. 
  1092.  
  1093.  Return Values: 
  1094.  
  1095.  The value 0 indicates success, the value -1 indicates an error. You can get 
  1096.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  1097.  These are: 
  1098.  
  1099.  ENOTSOCK 
  1100.            The socket parameter is not a valid socket descriptor. 
  1101.  
  1102.  EOPNOTSUPP 
  1103.            The socket parameter is not a socket descriptor that supports the 
  1104.            SockListen() call. 
  1105.  
  1106.  NOTE: SockListen() interfaces to the C function listen(). 
  1107.  
  1108.  
  1109. ΓòÉΓòÉΓòÉ 6.17. SockPSock_Errno ΓòÉΓòÉΓòÉ
  1110.  
  1111. The SockPSock_Errno() call writes a short error message to the  standard error 
  1112. device. 
  1113.  
  1114. Syntax: 
  1115.  
  1116.    SockPSock_Errno([error_string])
  1117.  
  1118. Parameter: 
  1119.  
  1120.  error_string will be the error string that is printed to standard error 
  1121.            describing the last error encountered. It is optional. 
  1122.  
  1123.  Description: 
  1124.  
  1125.  This call writes a short error message to the standard error display 
  1126.  describing the last error encountered during a call to a socket library 
  1127.  function. If error_string is specified and is not an empty string, the string 
  1128.  is printed, followed by a colon, followed by a space, followed by the message. 
  1129.  If error_string is omitted or is an empty string, only the message is printed. 
  1130.  
  1131.  The error code is acquired by calling SockSock_Errno(). The error code is set 
  1132.  when errors occur. Subsequent socket calls do not clear the error code. 
  1133.  
  1134.  NOTE: SockPSock_Errno() interfaces to the C function psock_errno(). 
  1135.  
  1136.  
  1137. ΓòÉΓòÉΓòÉ 6.18. SockRecv ΓòÉΓòÉΓòÉ
  1138.  
  1139. The SockRecv() call receives data on a connected socket. 
  1140.  
  1141. Syntax: 
  1142.  
  1143.    rc = SockRecv(socket, var, len[, flags])
  1144.  
  1145. Parameters: 
  1146.  
  1147.  socket    is the socket descriptor 
  1148.  
  1149.  var       is the name of a REXX variable the data should be received into. 
  1150.  
  1151.  len       is the maximum amount of data to read. 
  1152.  
  1153.  flags     is a blank delimited list of options: 
  1154.  
  1155.            MSG_OOB        Reads any out-of-band data on the socket. 
  1156.  
  1157.            MSG_PEEK       Peeks at the data present on the socket; the data is 
  1158.                           returned but not consumed, so that a subsequent 
  1159.                           receive operation sees the same data. 
  1160.  
  1161.  Description: 
  1162.  
  1163.  This call receives data on a socket with descriptor  socket and stores it in 
  1164.  the REXX  variable named var. The SockRecv() call applies only to connected 
  1165.  sockets. For information on how to use SockRecv() with datagram and raw 
  1166.  sockets, see "Datagram or raw sockets" in SockConnect(). 
  1167.  
  1168.  The SockRecv() call returns the length of the incoming data. If a datagram is 
  1169.  too long to fit in the buffer, the excess is discarded.  No data is discarded 
  1170.  for stream sockets. If data is  not available at the socket with descriptor 
  1171.  socket, the SockRecv() call waits for a  message to arrive and blocks the 
  1172.  caller, unless the socket is in  nonblocking mode. See SockIoctl()  for a 
  1173.  description of how to set nonblocking mode. 
  1174.  
  1175.  Return Values: 
  1176.  
  1177.  If successful, the length in bytes of the data is returned.  The value 0 
  1178.  indicates that the connection is closed. The value -1 indicates an error. You 
  1179.  can get the specific error code by calling SockSock_Errno() or 
  1180.  SockPSock_Errno(). These are: 
  1181.  
  1182.  ENOTSOCK 
  1183.            The socket parameter is not a valid socket descriptor. 
  1184.  
  1185.  EINTR 
  1186.            Interrupted system call. 
  1187.  
  1188.  EINVAL 
  1189.            Invalid argument. 
  1190.  
  1191.  EWOULDBLOCK 
  1192.            The socket parameter is in nonblocking mode and no data is available 
  1193.            to receive, or the SO_RCVTIMEO option has been set for socket socket 
  1194.            and the timeout expired before any data arrived to receive. 
  1195.  
  1196.  NOTE: SockRecv() interfaces to the C function recv(). 
  1197.  
  1198.  
  1199. ΓòÉΓòÉΓòÉ 6.19. SockRecvFrom ΓòÉΓòÉΓòÉ
  1200.  
  1201. The SockRecvFrom() call receives data on a socket. 
  1202.  
  1203. Syntax: 
  1204.  
  1205.    rc = SockRecvFrom(socket, var, len[, flags], address)
  1206.  
  1207. Parameters: 
  1208.  
  1209.  socket    is the socket descriptor 
  1210.  
  1211.  var       is the name of a REXX variable the data should be received into. 
  1212.  
  1213.  len       is the maximum amount of data to read. 
  1214.  
  1215.  flags     is a blank delimited list of options: 
  1216.  
  1217.            MSG_OOB        Reads any out-of-band data on the socket. 
  1218.  
  1219.            MSG_PEEK       Peeks at the data present on the socket; the data is 
  1220.                           returned but not consumed, so that a subsequent 
  1221.                           receive operation sees the same data. 
  1222.  
  1223.  address   is a REXX stem variable specifying the address of the sender the 
  1224.            data is received from. 
  1225.  
  1226.  Description: 
  1227.  
  1228.  The SockRecvFrom() call receives data on a socket with descriptor socket and 
  1229.  stores it in a REXX variable named  var. The SockRecvFrom() call applies to 
  1230.  any socket type,  whether connected or not. 
  1231.  
  1232.  If address is not a null address,  the address of the sender of the data is 
  1233.  returned. 
  1234.  
  1235.  The SockRecvFrom() call returns the length of the incoming message or data. If 
  1236.  a datagram is too long to fit in the supplied buffer,  the excess is 
  1237.  discarded. No data is discarded for stream sockets.  If data is not available 
  1238.  at the socket with descriptor socket,  the SockRecvFrom() call waits for a 
  1239.  message to arrive and blocks the caller, unless the socket is in nonblocking 
  1240.  mode. See SockIoctl() for a  description of how to set nonblocking mode. 
  1241.  
  1242.  Return Values: 
  1243.  
  1244.  If successful, the length, in bytes, of the data is returned. The value -1 
  1245.  indicates an error. You can get the specific error code by calling 
  1246.  SockSock_Errno() or SockPSock_Errno(). These are: 
  1247.  
  1248.  ENOTSOCK 
  1249.            The socket parameter is not a valid socket descriptor. 
  1250.  
  1251.  EINVAL 
  1252.            Invalid argument. 
  1253.  
  1254.  EWOULDBLOCK 
  1255.            The socket parameter is in nonblocking mode and no data is available 
  1256.            to receive, or the SO_RCVTIMEO option has  been set for socket 
  1257.            socket and the timeout expired before any data arrived to receive. 
  1258.  
  1259.  NOTE: SockRecvFrom() interfaces to the C function recvfrom(). 
  1260.  
  1261.  
  1262. ΓòÉΓòÉΓòÉ 6.20. SockSelect ΓòÉΓòÉΓòÉ
  1263.  
  1264. The SockSelect() call monitors the activity on a socket by specifying the 
  1265. number of sockets to be checked for readability, readiness for writing,  and 
  1266. exception pending conditions. 
  1267.  
  1268. Syntax: 
  1269.  
  1270.    rc = SockSelect(reads, writes, excepts [, timeout])
  1271.  
  1272. Parameters: 
  1273.  
  1274.  reads     A Number of sockets to be checked for readability. 
  1275.  
  1276.  writes    A Number of sockets to be checked for readiness for writing. 
  1277.  
  1278.  excepts   A Number of sockets to be checked for exceptional pending 
  1279.            conditions. For Network Services sockets, the only exceptional 
  1280.            pending condition is out-of-band data in the receive buffer. 
  1281.  
  1282.  timeout   Maximum interval, in seconds, to wait for the selection to complete. 
  1283.  
  1284.  Description: 
  1285.  
  1286.  This call monitors activity on a set of different sockets until a timeout 
  1287.  expires, to see if any sockets are ready for reading or writing, or if any 
  1288.  exceptional conditions are pending. 
  1289.  
  1290.  Each parameter specifying a number of sockets is specified by a  stem variable 
  1291.  which is queried and set by this function.  The stem variable has the 
  1292.  following format:   The stem.0 variable should contain the number of sockets, 
  1293.  stem.1 the first socket, etc.  Upon return, the stem variables will be reset 
  1294.  to the sockets which are ready. If any of the stem variables are "", or no 
  1295.  parameter is passed, no sockets for that type will be checked. 
  1296.  
  1297.  If the timeout value is 0, SockSelect() does not wait before returning. If the 
  1298.  timeout value is "", SockSelect() does not timeout, but returns when a socket 
  1299.  becomes ready. If the timeout value is a number of seconds, SockSelect() 
  1300.  waits for the specified interval before returning. The SockSelect() call 
  1301.  checks all indicated sockets at the same time and returns when any of them is 
  1302.  ready. 
  1303.  
  1304.  If no timeout value is passed, "" is assumed. The timeout value must be 
  1305.  integral (no fractional values).  Non-numeric and negative numbers are 
  1306.  considered 0. 
  1307.  
  1308.  Return Values: 
  1309.  
  1310.  The number of ready sockets is returned.  The value 0 indicates an expired 
  1311.  time limit.  In this case, the stem variables are not modified. The value -1 
  1312.  indicates an error.  You can get the specific error code by calling 
  1313.  SockSock_Errno() or SockPSock_Errno(). These are: 
  1314.  
  1315.  ENOTSOCK 
  1316.            The socket parameter is not a valid socket descriptor. 
  1317.  
  1318.  EFAULT 
  1319.            The address is not valid. 
  1320.  
  1321.  EINVAL 
  1322.            Invalid argument. 
  1323.  
  1324.  EINTR 
  1325.            Interrupted system call. 
  1326.  
  1327.  Examples: 
  1328.  
  1329.      r.0 = 2                  /* specify 2 sockets for read in stem r. */
  1330.      r.1 = 101
  1331.      r.2 = 102
  1332.                               /* specify 1 socket for write in stem w. */
  1333.      w.0 = 1
  1334.      w.1 = 103
  1335.                               /* no sockets for exceptions in stem e.  */
  1336.      e.0 = 0
  1337.      rc = SockSelect("r.","w.","e.")
  1338.  
  1339.      do i = 1 to r.0          /* display sockets being ready for read  /*
  1340.         say "socket" r.i "is ready for reading."
  1341.      end
  1342.  
  1343.  The SockSelect() call above could as well have been invoked as either of: 
  1344.  
  1345.      rc = SockSelect("r.","w.","")
  1346.      rc = SockSelect("r.","w.",)
  1347.  
  1348.  The function call SockSelect(, , , x) results in the program pausing for x 
  1349.  seconds. 
  1350.  
  1351.  NOTE: SockSelect() interfaces to the C function select(). 
  1352.  
  1353.  
  1354. ΓòÉΓòÉΓòÉ 6.21. SockSend ΓòÉΓòÉΓòÉ
  1355.  
  1356. The SockSend() call sends data on a connected socket. 
  1357.  
  1358. Syntax: 
  1359.  
  1360.    rc = SockSend(socket, data[, flags])
  1361.  
  1362. Parameters: 
  1363.  
  1364.  socket    is the socket descriptor 
  1365.  
  1366.  data      is the name of a REXX variable containing the data to transmit 
  1367.  
  1368.  flags     is a blank delimited list of options: 
  1369.  
  1370.            MSG_OOB 
  1371.                           Sends out-of-band data on sockets that support 
  1372.                           SOCK_STREAM communication. 
  1373.  
  1374.            MSG_DONTROUTE 
  1375.                           The SO_DONTROUTE option is turned on for the duration 
  1376.                           of the operation. This is usually used only by 
  1377.                           diagnostic or routing programs. 
  1378.  
  1379.  Description: 
  1380.  
  1381.  This call sends data on the socket with descriptor socket. The SockSend() call 
  1382.  applies to connected sockets. For information on how to use SockSend() with 
  1383.  datagram and raw sockets, see "Datagram or raw sockets" in SockConnect(). 
  1384.  
  1385.  If buffer space is not available at the socket to hold the data to be sent, 
  1386.  the SockSend() call normally blocks, unless the socket is placed in 
  1387.  nonblocking mode. See SockIoctl() for a description of how to set nonblocking 
  1388.  mode. Use the SockSelect() call to determine when it is possible to send more 
  1389.  data. 
  1390.  
  1391.  Return Values: 
  1392.  
  1393.  If successful, the number of bytes of the socket with descriptor socket that 
  1394.  is  added to the send buffer is returned. This may be less than the number  of 
  1395.  bytes specified in the length parameter. Successful completion does not imply 
  1396.  that the data has already been delivered to the receiver. The  return value -1 
  1397.  indicates an error was detected on the sending side of  the connection. You 
  1398.  can get the specific error code by calling SockSock_Errno() or 
  1399.  SockPSock_Errno(). These are: 
  1400.  
  1401.  ENOTSOCK 
  1402.            The socket parameter is not a valid socket descriptor. 
  1403.  
  1404.  EINTR 
  1405.            Interrupted system call. 
  1406.  
  1407.  EINVAL 
  1408.            Invalid argument. 
  1409.  
  1410.  ENOBUFS 
  1411.            No buffer space is available to send the message. 
  1412.  
  1413.  EWOULDBLOCK 
  1414.            The socket parameter is in nonblocking mode and the data cannot be 
  1415.            sent without blocking, or the SO_SNDTIMEO  option has been set for 
  1416.            socket socket and the timeout expired before any data was sent. 
  1417.  
  1418.  Note. SockSend() interfaces to the C function send(). 
  1419.  
  1420.  
  1421. ΓòÉΓòÉΓòÉ 6.22. SockSendTo ΓòÉΓòÉΓòÉ
  1422.  
  1423. The SockSentTo() call sends data on a socket. 
  1424.  
  1425. Syntax: 
  1426.  
  1427.    rc = SockSendTo(socket, data[, flags], address)
  1428.  
  1429. Parameters: 
  1430.  
  1431.  socket    is the socket descriptor 
  1432.  
  1433.  data      is a string of data to transmit 
  1434.  
  1435.  flags     is a blank delimited list of options: 
  1436.  
  1437.            MSG_OOB 
  1438.                           Sends out-of-band data on sockets that support 
  1439.                           SOCK_STREAM communication. 
  1440.  
  1441.            MSG_DONTROUTE 
  1442.                           The SO_DONTROUTE option is turned on for the duration 
  1443.                           of the operation. This is usually used only by 
  1444.                           diagnostic or routing programs. 
  1445.  
  1446.  address   is a REXX stem variable containing the destination address. 
  1447.  
  1448.  Description: 
  1449.  
  1450.  This call sends data on the socket with descriptor  socket. The SockSendTo() 
  1451.  call  applies to connected or unconnected sockets. For unconnected datagram 
  1452.  and raw sockets, the SockSendTo() call sends data to the specified destination 
  1453.  address. For stream sockets the destination address  is ignored. 
  1454.  
  1455.  Datagram sockets are connected by calling SockConnect(). This identifies the 
  1456.  peer to send/receive the datagram. Once a datagram socket is connected  to a 
  1457.  peer, you may still use the SockSendTo() call but a destination address cannot 
  1458.  be included. 
  1459.  
  1460.  To change the peer address when using connected datagram sockets,  issue a 
  1461.  SockConnect() call with a null address. Specifying a null address on a 
  1462.  connected datagram socket removes the peer address specification. You  can 
  1463.  then either issue a SockSendTo() call specifying a different destination 
  1464.  address or issue a SockConnect() call to connect to a different peer. For more 
  1465.  information on connecting datagram sockets and specifying null addresses, see 
  1466.  "Datagram or raw sockets" in SockConnect(). 
  1467.  
  1468.  Return Values: 
  1469.  
  1470.  If successful, the number of bytes sent is returned. Successful completion 
  1471.  does not guarantee delivery of the data to the receiver. The return value -1 
  1472.  indicates an error was detected on the sending side. You can get the  specific 
  1473.  error code by calling SockSock_Errno() or SockPSock_Errno(). 
  1474.  
  1475.  ENOTSOCK 
  1476.            The socket parameter is not a valid socket descriptor. 
  1477.  
  1478.  EMSGSIZE 
  1479.            The message data was too big to be sent as a single datagram. 
  1480.  
  1481.  ENOBUFS 
  1482.            No buffer space is available to send the message. 
  1483.  
  1484.  EWOULDBLOCK 
  1485.            The socket parameter is in nonblocking mode and the  data cannot be 
  1486.            sent without blocking, or the SO_SNDTIMEO option has been set for 
  1487.            socket socket and  the timeout expired before any data was sent. 
  1488.  
  1489.  ENOTCONN 
  1490.            The socket is not connected. 
  1491.  
  1492.  EDESTADDRREQ 
  1493.            Destination address required. 
  1494.  
  1495.  Note. SockSendTo() interfaces to the C function sendto(). 
  1496.  
  1497.  
  1498. ΓòÉΓòÉΓòÉ 6.23. SockSetSockOpt ΓòÉΓòÉΓòÉ
  1499.  
  1500. The SockSetSockOpt() call sets options associated with a socket. 
  1501.  
  1502. Syntax: 
  1503.  
  1504.    rc = SockSetSockOpt(socket, level, optName, optVal)
  1505.  
  1506. Parameters: 
  1507.  
  1508.  socket    Socket descriptor 
  1509.  
  1510.  level     Specifies which option level is being set 
  1511.  
  1512.  optname   Name of a specified socket option 
  1513.  
  1514.  optval    option data value 
  1515.  
  1516.  Description: 
  1517.  
  1518.  This call sets options associated with a socket such as enabling debugging at 
  1519.  the socket or protocol level, control timeouts, or permit socket data 
  1520.  broadcast. Options can exist at the socket or the protocol level; options are 
  1521.  always present at the highest socket level. When setting socket options, the 
  1522.  level of the option level and the name of the option optname must be 
  1523.  specified. The only supported level is SOL_SOCKET. 
  1524.  
  1525.  The optval parameter is used to pass data used by the particular set command. 
  1526.  The optval parameter is a variable containing  the data needed by the set 
  1527.  command.  The optval parameter is optional and  if data is not needed by the 
  1528.  command, it can be omitted.  For socket options that are toggles, the option 
  1529.  is enabled if optval is nonzero and disabled if optval is 0. 
  1530.  
  1531.  The following options are recognized for SOL_SOCKET: 
  1532.  
  1533.  SO_BROADCAST 
  1534.            (datagram sockets only) Sets the ability to broadcast  messages. If 
  1535.            this option is enabled, it allows the  application to send broadcast 
  1536.            messages over socket, if the  interface specified in the destination 
  1537.            supports broadcasting of packets. 
  1538.  
  1539.  SO_DEBUG 
  1540.            Sets the ability to record debug information for a socket. 
  1541.  
  1542.  SO_DONTROUTE 
  1543.            Sets the ability for the socket to bypass the routing of  outgoing 
  1544.            messages. When this option is enabled, it  causes outgoing messages 
  1545.            to bypass the standard  routing algorithm and be directed to the 
  1546.            appropriate  network interface according to the network portion of 
  1547.            the destination address. When enabled, packets can be  sent only to 
  1548.            directly connected networks (networks for which this host has an 
  1549.            interface). 
  1550.  
  1551.  SO_KEEPALIVE 
  1552.            (stream sockets only) Sets the ability of the socket to  send 
  1553.            keepalive packets that will keep the connection  alive. TCP uses a 
  1554.            timer called the keepalive timer. This  timer is used to monitor 
  1555.            idle connections that might have been disconnected because of a peer 
  1556.            crash or  timeout. If this option is set on, a keepalive packet is 
  1557.            periodically sent to the peer. This is mainly used to  allow servers 
  1558.            to close connections that are no longer  active as a result of 
  1559.            clients going away without  properly closing connections. 
  1560.  
  1561.  SO_LINGER 
  1562.            (stream sockets only) Sets the ability of the socket to  linger on 
  1563.            close if data is present. When this option is  enabled and there is 
  1564.            unsent data present when  SockSoClose() is called, the calling 
  1565.            application is blocked during the SockSoClose() call until the data 
  1566.            is transmitted  or the connection has timed out. If this option is 
  1567.            disabled, the SockSoClose() call returns without blocking  the 
  1568.            caller, and TCP waits to try to send the data.  Although the data 
  1569.            transfer is usually successful, it  cannot be guaranteed, because 
  1570.            TCP waits only a finite  amount of time trying to send the data. 
  1571.  
  1572.  SO_OOBINLINE 
  1573.            (stream sockets only) Sets the ability of the socket to  receive 
  1574.            out-of-band data. As stated in TCP/IP  Illustrated, Volume 1: The 
  1575.            Protocols, out-of-band data  is "a logically separate data path 
  1576.            using the same  connection as the normal data path." 
  1577.  
  1578.            When this option is enabled, it causes out-of-band  data to be 
  1579.            placed in the normal data input queue as it  is received, making it 
  1580.            available to SockRecv(), and  SockRecvFrom(), without having to 
  1581.            specify the MSG_OOB  flag in those calls. When this option is 
  1582.            disabled, it  causes out-of-band data to be placed in the priority 
  1583.            data input queue as it is received, making it available  to 
  1584.            SockRecv(), and SockRecvFrom(), only by specifying the  MSG_OOB flag 
  1585.            in those calls. 
  1586.  
  1587.  SO_RCVBUF 
  1588.            Sets buffer size for input. This option sets the size of  the 
  1589.            receive buffer to the value contained in the buffer  pointed to by 
  1590.            optval. This allows the buffer size to be  tailored for specific 
  1591.            application needs, such as  increasing the buffer size for 
  1592.            high-volume connections. 
  1593.  
  1594.  SO_RCVLOWAT 
  1595.            Sets receive low-water mark. 
  1596.  
  1597.  SO_RCVTIMEO 
  1598.            Sets the timeout value for a receive operation. 
  1599.  
  1600.  SO_REUSEADDR 
  1601.            (stream and datagram sockets only) Sets the ability of  a socket to 
  1602.            reuse a local address. When enabled, this  option allows local 
  1603.            addresses that are already in use  to be bound. This alters the 
  1604.            normal algorithm used in theSockBind() call. The system checks at 
  1605.            connect time to  be sure that no local address and port have the 
  1606.            same  foreign address and port. The error SOCEADDRINUSE is  returned 
  1607.            if the association already exists. 
  1608.  
  1609.            Multicast applications must set this socket option if  they want to 
  1610.            join the same Class D IP address and  port for sending and receiving 
  1611.            multicast packets. 
  1612.  
  1613.  SO_SNDBUF 
  1614.            Sets buffer size for output. This option sets the size of  the send 
  1615.            buffer to the value contained in the buffer  pointed to by optval. 
  1616.            This allows the send buffer size  to be tailored for specific 
  1617.            application needs, such as  increasing the buffer size for 
  1618.            high-volume connections. 
  1619.  
  1620.  SO_SNDLOWAT 
  1621.            Sets send low-water mark. 
  1622.  
  1623.  SO_SNDTIMEO 
  1624.            Sets the timeout value for a send operation. 
  1625.  
  1626.  SO_USELOOPBACK 
  1627.            Bypasses hardware when possible. 
  1628.  
  1629.  Most of the options' values are integral. The exception is "SO_LINGER" that 
  1630.  expects two blank delimited integers: 
  1631.  
  1632.    1. the l_onoff value.  The l_onoff field is set to zero if the SO_LINGER 
  1633.       option is being disabled. A nonzero value enables the option. 
  1634.  
  1635.    2. the l_linger value. The l_linger field specifies the amount of time in 
  1636.       seconds to linger on close. A value of zero will cause SockSoClose() to 
  1637.       wait until the disconnect completes. 
  1638.  
  1639.  Return Values: 
  1640.  
  1641.  The value 0 indicates success; the value -1 indicates an error. You can get 
  1642.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  1643.  These are: 
  1644.  
  1645.  EADDRINUSE 
  1646.            The address is already in use. 
  1647.  
  1648.  ENOTSOCK 
  1649.            The socket parameter is not a valid socket descriptor. 
  1650.  
  1651.  ENOPROTOOPT 
  1652.            The optname parameter is unrecognized. 
  1653.  
  1654.  EINVAL 
  1655.            Invalid argument. 
  1656.  
  1657.  ENOBUFS 
  1658.            No buffer space is available. 
  1659.  
  1660.  NOTE: SockSetSockOpt() interfaces to the C function setsockopt(). 
  1661.  
  1662.  
  1663. ΓòÉΓòÉΓòÉ 6.24. SockShutDown ΓòÉΓòÉΓòÉ
  1664.  
  1665. The SockShutDown() call shuts down all or part of a full duplex connection. 
  1666.  
  1667. Syntax: 
  1668.  
  1669.    rc = SockShutDown(socket, howto)
  1670.  
  1671. Parameters: 
  1672.  
  1673.  socket    is the socket descriptor 
  1674.  
  1675.  howto     is the condition of the shutdown 
  1676.  
  1677.  Description: 
  1678.  
  1679.  This call shuts down all or part of a full duplex connection. Since data flows 
  1680.  in one direction are independent of data flowing from the other direction, the 
  1681.  shutdown call allows you to independently stop data flow in either direction 
  1682.  or all data flows with one API call. For example, you may want to stop the 
  1683.  sender(s) from sending data to you, but you still want  to send data. 
  1684.  
  1685.  Using the SockShutDown() call is optional. 
  1686.  
  1687.  The howto parameter sets the condition for shutting down the connection  to 
  1688.  socket socket. It can be set to one of the following: 
  1689.  
  1690.      0 - no more data can be received on socket socket. 
  1691.  
  1692.      1 - no more output to be allowed on the socket socket. 
  1693.  
  1694.      2 - no more data can be sent or received on socket socket. 
  1695.  
  1696.  Return Values: 
  1697.  
  1698.  The value 0 indicates success; the value -1 indicates an error. You can get 
  1699.  the specific error code by calling SockSock_Errno() or SockPSock_Errno(). 
  1700.  These are: 
  1701.  
  1702.  ENOTSOCK 
  1703.            The socket parameter is not a valid socket descriptor. 
  1704.  
  1705.  EINVAL 
  1706.            The howto parameter was not set to one of the valid values. 
  1707.  
  1708.  NOTE: SockShutDown() interfaces to the C function shutdown(). 
  1709.  
  1710.  
  1711. ΓòÉΓòÉΓòÉ 6.25. SockSock_Errno ΓòÉΓòÉΓòÉ
  1712.  
  1713. The SockSock_Errno() call returns an error code set by a socket call. 
  1714.  
  1715. Syntax: 
  1716.  
  1717.    errno = SockSock_Errno()
  1718.  
  1719. Description: 
  1720.  
  1721. The SockSock_Errno() call returns the last error code set by a socket call. 
  1722. Subsequent socket API calls do not reset this error code. 
  1723.  
  1724. NOTE: SockSock_Errno() interfaces to the C function sock_errno(). 
  1725.  
  1726.  
  1727. ΓòÉΓòÉΓòÉ 6.26. SockSocket ΓòÉΓòÉΓòÉ
  1728.  
  1729. The SockSocket() call creates an endpoint for communication and returns a 
  1730. socket  descriptor representing the endpoint. 
  1731.  
  1732. Syntax: 
  1733.  
  1734.    socket = SockSocket(domain, type, protocol)
  1735.  
  1736. Parameters: 
  1737.  
  1738.  domain    is the communication domain requested 
  1739.  
  1740.  type      is the type of socket created 
  1741.  
  1742.  protocol  is the protocol requested 
  1743.  
  1744.  domain must be "AF_INET", type may be one of "SOCK_STREAM", "SOCK_DGRAM", or 
  1745.  "SOCK_RAW", and protocol may be one of "IPPROTO_UDP", "IPPROTO_TCP", or "0". 
  1746.  
  1747.  Description: 
  1748.  
  1749.  This call creates an endpoint for communication and returns a socket 
  1750.  descriptor representing the endpoint. Each socket type provides a different 
  1751.  communication service. 
  1752.  
  1753.  Sockets are deallocated with the SockClose() call. 
  1754.  
  1755.  The domain parameter specifies a communications domain where communication is 
  1756.  to take place. This parameter specifies the protocol family which is used. 
  1757.  
  1758.  AF_INET   Use addresses in the Internet address format. 
  1759.  
  1760.  The type parameter specifies the type of socket created. The type is 
  1761.  analogous with the semantics of the communication requested.  The types 
  1762.  supported are: 
  1763.  
  1764.  SOCK_STREAM 
  1765.            Provides sequenced, two-way byte streams that are  reliable and 
  1766.            connection-oriented. It supports a mechanism  for out-of-band data. 
  1767.            Stream sockets are supported by the Internet (AF_INET) communication 
  1768.            domain. 
  1769.  
  1770.  SOCK_DGRAM 
  1771.            Provides datagrams, which are connectionless messages  of a fixed 
  1772.            length whose reliability is not guaranteed.  Datagrams can be 
  1773.            received out of order, lost, or delivered multiple times.  Datagram 
  1774.            sockets are supported by the Internet (AF_INET) communication 
  1775.            domain. 
  1776.  
  1777.  SOCK_RAW 
  1778.            Provides the interface to internal protocols (such as IP and ICMP). 
  1779.            Raw sockets are supported by the Internet (AF_INET) communication 
  1780.            domain. 
  1781.  
  1782.  The protocol parameter specifies a particular protocol to be used with the 
  1783.  socket.  If the protocol field is set to 0 (default), the system selects the 
  1784.  default protocol number for the domain and socket type requested. 
  1785.  
  1786.  Return Values: 
  1787.  
  1788.  A non-negative socket descriptor return value indicates success. The return 
  1789.  value -1 indicates an error. You can get the specific error code by calling 
  1790.  SockSock_Errno() or SockPSock_Errno(). These are: 
  1791.  
  1792.  EMFILE 
  1793.            The maximum number of sockets are currently in use. 
  1794.  
  1795.  EPROTONOSUPPORT 
  1796.            The protocol is not supported in the specified  domain or the 
  1797.            protocol is not supported for the specified socket type. 
  1798.  
  1799.  EPFNOSUPPORT 
  1800.            The protocol family is not supported. 
  1801.  
  1802.  ESOCKTNOSUPPORT 
  1803.            The socket type is not supported. 
  1804.  
  1805.  NOTE: SockSocket() interfaces to the C function socket(). 
  1806.  
  1807.  
  1808. ΓòÉΓòÉΓòÉ 6.27. SockSoClose ΓòÉΓòÉΓòÉ
  1809.  
  1810. The SockSoClose() call shuts down a socket and frees resources allocated to the 
  1811. socket. 
  1812.  
  1813. Syntax: 
  1814.  
  1815.    rc = SockSoClose(socket)
  1816.  
  1817. Parameter: 
  1818.  
  1819.  socket    is the socket descriptor of the socket to be closed. 
  1820.  
  1821.  This function is identical to SockClose(). For a detailed description of 
  1822.  SockSoClose(), please refer to SockClose().