Connects to a server. Can also set the current server handle.
Synopsis
error = InetConnect(variableName, server, type, user, password, port, options)
Args
variableName is the name of some REXX variable that you wish to be set to a server handle that InetConnect creates for you. You do not need to know the details of what a server handle is, but you need to pass this server handle to InetClose after you've finished all communication with this server.
Note: If variableName is already set to some server handle that was previously returned by InetConnect or InetOpenUrl, then it is simply made the "current server handle". So, after you InetClose a particular server handle, you should DROP its variable if you intend to reuse than variable in another call to InetConnect.
server is a string specifying the URL to the server, for example http://www.microsoft.com to access Microsoft's server. Alternately, you specify the IP number of the server, in ASCII dotted-decimal format (for example, 11.0.1.45).
type is the protocol you wish to use in communicating with the server. It may be one of the following:
Value | Meaning |
---|---|
HTTP | Use HTTP protocol. |
FTP | Use FTP protocol. |
GOPHER | Use Gopher protocol. |
If omitted, type defaults to "HTTP".
user is some string containing the user's login name for the server. If omitted, a default login name will be chosen according to the protocol type. You may be able to omit the user name for FTP protocol, in which case the default user name is "anonymous".
password is some string containing the user's password for the server. If omitted, a default password will be chosen according to the protocol type. You may be able to omit the password for FTP protocol. If user is also omitted, then the default password is the user's email address, otherwise it is an empty string.
port specifies the TCP/IP port number that the server uses (ie, the port number to which you connect on the server). Most protocols use a default port number. For example, HTTP protocol usually has the server on port 80. FTP protocol has the server on port 21. HTTPS (secure HTTP) typically uses port 443. If you omit this arg, then RexxINet will use the default port for whatever type of protocol you've chosen. But if you need to specify a non-standard port number for the server, you'll need to supply this arg.
options may be one of the following:
Value | Meaning |
---|---|
ACTIVE | Use active (ie, not passive) FTP semantics for FTP files and directories. |
If omitted, options is none of the above.
Returns
An empty string if successful, or an error message if a problem.
Notes
If you call InetConnect() before calling InetOpen() to initialize RexxInet, then a REXX SYNTAX condition is raised. CONDITION('E') returns error number 40.1 and CONDITION('D') returns the message DLL function "INETCONNECT" reported session handle not open!.
For FTP protocol, InetConnect actually establishes a connection with the server. For others, such as Gopher, the actual connection is not established until your script does a specific operation.
For maximum efficiency when using the Gopher and HTTP protocols, you should try to minimize calls to InetConnect and avoid calling this function for every transaction with the server. One way to accomplish this is to not call InetClose on the server handle until you're completely finished interacting with the server.