tcpcmd.checkURL
Checking URLs

Many webmasters and content developers need to check WWW urls. tcpcmd.checkURL can be a good way to do so.

checkURL returns different kinds of information, depending on the type of url you give it, and depending upon the result of the check.

For http urls, checkURL sends a HEAD request to the server, requesting that header information for the url be returned. For ftp urls, checkURL tries to locate the file or directory on the host specified in the url.

Here's a sample use of checkURL:

tcpcmd.checkURL ("http://www.scripting.com/frontier/")
« "Success: Thursday, 17-Oct-96 17:59:13 GMT"

Here, the http url is located and the last-modified date of the file is returned. You could easily compare this time with a cached copy, for example, to know whether or not your cache was outdated.

Here's another example:

tcpcmd.checkURL("http://www.tiac.net/biz/bbsw/index.html")
« "Error: File Not Found"

This is the former home age of Bare Bones' BBEdit program. They're not at that site any more, and there is no file at that location.

And one more example:

tcpcmd.checkURL("http://info.apple.com/macos/macosmain.html")
« "Redirected: http://www.macos.apple.com"

In this case, the page has been redirected. checkURL returns the new url.

You can use checkURL to check the validity of an FTP url, too:

tcpcmd.checkURL("ftp://ftp.scripting.com/userland/")
« "Success: ftp://ftp.scripting.com/userland/"

Here, we're checking to see that the userland directory still exists at the ftp.scripting.com site. It does.

When checking ftp urls, checkURL returns the url if the file or directory is found.

Next, let's see what happens if we make a subtle "typo" in the url:

tcpcmd.checkURL("ftp://ftp.scripting.com/userlan/")
« "Error: Directory Not Found"

Oops! We accidentally left the "d" off the end of the userland directory.

And, if we are checking for a file that doesn't exist, we'll see:

tcpcmd.checkURL("ftp://ftp.scripting.com/userland/blahblah.sit.hqx")
« "Error: File Not Found"

The syntax of tcpcmd.checkURL is:

tcpcmd.checkURL (url [,proxy] [,timeout])

Where:

  • url

    a string containing the url to be checked

    "http://www.scripting.com"

  • proxy
    an optional string containing the IP address or domain name of a proxy server, if it is to be used. The address can contain an optional port number.

    "myProxy.com:36000"

  • timeout
    an optional number containing the number of seconds checkURL will wait at each step in the sending and receiving process before it gives up and returns to the caller. The default timeout used is defined in tcpcmd.timeouts.http.

Returns

checkURL returns a string prefixed with either "Success: " or "Error: ". Additional information regarding the success or error follows the prefix.

For http urls, the additional information returned is:

  • "Success: Sun, 23 Jun 1996 19:53:12 GMT"
    The file was found. The date is the last-modified date as specified by the server. The date is not altered by checkURL allowing you to convert it to any format desired. (HTTP/1.0 2xx and 304 messages)
  • "Success: Last-modified date unknown."
    The file was located, but the host did not return a header or document with a valid "Last-modified" date. (HTTP/1.0 2xx and 304 messages)
  • "Redirected: http://theHost.com/aNewLocation/file.html"
    The host has redirected the url to a new location (HTTP/1.0 3xx (but not 304)
  • "Error: File moved. New location not specified"
    The host has issued an HTTP/1.0 3xx (not 304) message and checkURL was not able to determine the new location.
  • "Error: File Not Found"
    HTTP/1.0 404 message.
  • "Error: File Unavailable"
    HTTP/1.0 4xx (not 404) message.
  • "Error: Server Error"
    HTTP/1.0 5xx message.
  • "Error: " followed by the actual header returned by the host
    If the host returns a response to the HEAD request, but checkURL cannot process it properly, the entire header is returned.

Example return messages for ftp urls are:

  • "Success: ftp://ftp.scripting.com/userland/finderAliases.sit.hqx"
    The ftp url was found. The original url is returned.
  • "Error: Can't connect to host"
    checkURL could not log on to the ftp host.
  • "Error: Directory Not Found"
    The url requested a directory which could not be found.
  • "Error: File Not Found"
    The url requested a file which could not be found.

Additional error messages can occur for any url:

  • "Error: Bad URL"
    checkURL could not understand the url.
  • "Error: Unsupported URL in checkURL."
    checkURL does not support this kind of url.
  • "Error: No DNS Entry"
    There was no domain name or address for the host specified in this url.

  • "Error: Timeout reaching host"
    The host could not be contacted within the value specified in the timeout parameter. If the timeout parameter is omitted, the default in tcpcmd.timeouts.http will be used.

  • "Error: Host refused connection"
    The host is not accepting requests or is busy.

  • "Error: " followed by a system error message
    A system-level error occurred.

Current Limitations and Restrictions

tcpcmd.checkURL only supports HTTP and FTP urls at this time.

A proxy is supported only for HTTP urls in this version of tcpcmd.

This page was last built on 8/1/98; 10:28:40 PM ET by Alan German, asg@erols.com. At the moment, I am using Macintosh OS to work on this website. The "Electric Cactus" graphic is based on original artwork owned by UserLand Software and is used with their permission.