Rexx/CURL

# A Rexx interface to the cURL library

Version 1.4

16 October 2005

## Table of Contents

1. Introduction
2. Overview
3. Functions
  CURLINIT
  CURLCLEANUP
  CURLSETOPT
  CURLFORMADD
  CURLFORMFREE
  CURLPERFORM
  CURLGETINFO
  CURLVARIABLE
  CURLLOADFUNC
  CURLDROPFUNC
4. Errors
5. Using Rexx/CURL
6. History of Rexx/CURL

## 1. Introduction

This document describes the interface to the cURL package. cURL is a general purpose package that allows access to any URL-addressable resource. With Rexx/CURL you can access resources such as web pages, ftp sites, and telnet sessions under control of your Rexx program. Rexx/CURL is actually built on top of libcurl but for the purposes of this document it will be refered to simply as cURL.

## 2. Overview

Rexx/CURL consists of Rexx external functions that allows a Rexx program to access any URL. The basic concept of Rexx/CURL (and cURL), is that you specify a URL and all options appropriate to that URL, and then perform the URL access.
See Using Rexx/CURL for more details.

The Rexx/CURL external functions are:

- CURLINIT - initialise the cURL interface
- CURLCLEANUP - cleanup the cURL interface
- CURLSETOPT - defines all the options appropriate to the type of URL you wish to access
- CURLFORMADD - add a section to a multipart/formdata HTTP POST
- CURLFORMFREE - free up resources used by CURLFORMADD
- CURLPERFORM - carries out the actions defined by the various calls to CURLSETOPT
- CURLGETINFO - return information about the action carried out by CURLPERFORM
- CURLVARIABLE - set or retrieve default run-time values

- CURLLOADFUNCS - load all Rexx/CURL external functions
- CURLDROPFUNCS - unload all Rexx/CURL external functions

## 3. Functions

This section provides the full syntax and usage of each function that comprises Rexx/CURL.

CURLINIT()

Initialises the cURL interface. The return value from this call is used as the first argument to most of the other Rexx/CURL functions.

Arguments:

none

Returns:

success:
  any non-blank value
failure:
  blank

CURLSETOPT(handle, option,option value[,more option values,...])

This function is called to define all the parameters and data required to carry out the particular request. The option argument is case-insensitive. The table below defining the options available contains the equivalent cURL option value used in the C/C++ interface. Not all of the Rexx/CURL option strings are the same as the C/C++ equivalents; I've tried to be more consistent and clearer with the name of the option. The C/C++ equivalents are there if you wish to read alternate definitions of these options. See the curl_easy_setopt() function documentation.

Arguments:

handle
  The value returned from CURLINIT.

option
  This is the string identifying the option to set.

  Rexx/CURL Option | Description | cURL Equivalent Option
  --- | --- | ---
  BUFFERSIZE | Specify the size of the recieve buffer to use. | CURLOPT_BUFFERSIZE
  CAINFO | The name of a file from which the SSL peer certificate data is read for the performed action. This file must exist. | CURLOPT_CAINFO
  CAPATH | The CAPATH directory used to validate the peer certificate. This option is used only if SSL_VERIFYPEER is true. | CURLOPT_CAPATH
  CLOSEPOLICY | Specify the type of disconnection policy to use if the connection cache is filled. This is only applicable if you potentially use more than 5 concurrent connections. Can be one of "OLDEST", or "LEAST_RECENTLY_USED". | CURLOPT_CLOSEPOLICY
  CONNECTTIMEOUT | To limit the time it takes to connect to the server, set this value to the number of seconds. | CURLOPT_CONNECTTIMEOUT
  COOKIE | If you want to pass a cookie to the server, set this option to the cookie. The format of the cookie is: name=contents, where name is the name of the cookie to be set. | CURLOPT_COOKIE
  COOKIEFILE | The name of a file from which cookie data is read for the performed action. The cookie file can contain Netscape/Mozilla formated cookies, or regular HTTP header format. This file must exist. | CURLOPT_COOKIEFILE
  COOKIEJAR | The name of a file to which all known cookies are written after the operation completes. | CURLOPT_COOKIEJAR
  COOKIELIST | Pass a string containing a cookie string. Cookie can be either in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL cookie engine was not enabled it will enable its cookie engine. Passing a magic string ALL will erase all cookies known by cURL. | CURLOPT_COOKIELIST
  COOKIESESSION | Set this option to a 1 or Y to indicate that this operation is the start of a cookie session. Set this option to a 0 or N to indicate that this operation is the end of a cookie session. | CURLOPT_COOKIESESSION
  CRLF | Set this option to a 1 or Y to indicate that LF charcaters should be converted to CRLF on transfers. | CURLOPT_CRLF
  CUSTOMREQUEST | To carry out an HTTP request command other than GET or HEAD, pass the command in this option. | CURLOPT_CUSTOMREQUEST
  DNSCACHETIMEOUT | This sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches info for 60 seconds. | CURLOPT_DNS_CACHE_TIMEOUT
  DNSUSEGLOBALCACHE | Set this option to a 1 or Y to use a global DNS cahce that will last between operations. | CURLOPT_DNS_USE_GLOBAL_CACHE
  EGDSOCKET | The name of the Entropy Gathering Socket which is used to seed the SSL random engine. | CURLOPT_EGDSOCKET
  ENCODING | Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received. "IDENTITY": Does nothing "DEFLATE": requests the server to compress its response using the zlib algorithm "GZIP": requests the gzip algorithm If a zero-length string is set, then an Accept-Encoding: header containing all supported encodings is sent. This is a request, not an order; the server may or may not do it. This option must be set (to any non-empty value) or else any unsolicited encoding done by the server is ignored. See the special cURL file lib/README.encoding for details. | CURLOPT_ENCODING
  ERRFILE | The name of a file into which any error output from the performed action is written. By default, if this file exists, it will be over-written. You can pass APPEND as an extra argument to append data to an existing file. | CURLOPT_STDERR
  FAILONERROR | Set this option to a 1 or Y to get cURL to fail, rather than return the page, if the HTTP return code is greater than or equal to 300. | CURLOPT_FAILONERROR
  FILETIME | Set this option to a 1 or Y to indicate that cURL should attempt to retrieve the modification date of the remote document. Not all servers will respond to this type of request. To retrieve the date, call CURLGETINFO with the FILE_TIME option. | CURLOPT_FILETIME
  FOLLOWLOCATION | Set this option to a 1 or Y to get cURL to follow any Location: headers in the specified site. | CURLOPT_FOLLOWLOCATION
  FORBIDREUSE | Set this option to a 1 or Y to get cURL to make the next transfer explicitly close the connection when done. Normally, libcurl keeps all connections alive when done with one transfer in case there comes a succeeding one that can re-use them. This option should be used with caution and only if you understand what it does. Set to 0 to have libcurl keep the connection open for possibly later re-use (default behavior). | CURLOPT_FORBID_REUSE
  FRESHCONNECT | Set this option to a 1 or Y to indicate that the next transfer should use a new connection. | CURLOPT_FRESH_CONNECT
  FTPAPPEND | Set this option to a 1 or Y to indicate that the remote file is to be appended to rather than replaced when an FTP upload is to be carried out. | CURLOPT_FTPAPPEND
  FTPCMDS | Specify a stem containing FTP commands to be issued before an FTP session is started. | CURLOPT_QUOTE
  FTPCMDSAFTER | A list of FTP commands to be executed after the URL is accessed. The list of commands is specified as a stem name; ie the supplied string must end in a period, and represent a valid Rexx array. | CURLOPT_POSTQUOTE
  FTPCMDSBEFORE | A list of FTP commands to be executed before the URL is accessed. The list of commands is specified as a stem name; ie the supplied string must end in a period, and represent a valid Rexx array. | CURLOPT_PREQUOTE
  FTPCREATEMISSINGDIRS | Set this option to a 1 or Y to tell cURL to attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. | CURLOPT_FTP_CREATE_MISSING_DIRS
  FTPCRLF | See the prefered CRLF option. | CURLOPT_CRLF
  FTPLISTONLY | Set this option to a 1 or Y to indicate that only filenames are to be returned when the URL option specifies an FTP directory. Normally, file sizes, dates etc. are returned. | CURLOPT_FTPLISTONLY
  FTPPORT | Set this option to a string to use as the parameter to the FTP PORT command. The parameter can be an IP address, a hostname, an interface name (undex Unix), or '-' to use the client machine's default IP address. | CURLOPT_FTPPORT
  FTPRESPONSETIMEOUT | Causes uURL to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response message for a command before the session is considered hung. Note that while curl is waiting for a response, this value overrides "TIMEOUT". It is recommended that if used in conjunction with "TIMEOUT", you set "FTPRESPONSETIMEOUT" to a value smaller than "TIMEOUT". | CURLOPT_FTP_RESPONSE_TIMEOUT
  FTPSKIPPASVIP | Set this option to a 1 or Y to instruct libcurl to not use the IP address the server suggests in its 227-response to libcurl's PASV command when libcurl connects the data connection. Instead libcurl will re-use the same IP address it already uses for the control connection. But it will use the port number from the 227-response. This option has no effect if PORT, EPRT or EPSV is used instead of PASV. | CURLOPT_FTP_SKIP_PASV_IP
  FTPSSL | Set this option to one of the following string values to make libcurl use your desired level of SSL for the ftp transfer. "NONE": Don't attempt to use SSL. "TRY": Try using SSL, proceed as normal otherwise. "CONTROL": Require SSL for the control connection or fail with FTP_SSL_FAILED. "ALL": Require SSL for all communication or fail with FTP_SSL_FAILED. | CURLOPT_FTP_SSL
  FTPSSLAUTH | Set this option to one of the following string values to alter how libcurl issues AUTH TLS or AUTH SSL when FTP over SSL is activated. "DEFAULT": Allow libcurl to decide. "SSL": Try "AUTH SSL" first, and only if that fails try "AUTH TLS". "TLS": Try "AUTH TLS" first, and only if that fails try "AUTH SSL". | CURLOPT_FTPSSLAUTH
  FTPUSEEPRT | Set this option to a 1 or Y to tell cURL to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by "FTPPORT"). Using EPRT means that it will first attempt to use EPRT and then LPRT before using PORT, but if you pass 0 to this option, it will not try using EPRT or LPRT, only plain PORT. | CURLOPT_FTP_USE_EPRT
  FTPUSEEPSV | Set this option to a 1 or Y to tell cURL to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass 0 or N to this option, it will not try using EPSV, only plain PASV. | CURLOPT_FTP_USE_EPSV
  HEADER | Set this option to a 1 or Y to get cURL to return header information for those protocols, like HTTP, that have seperate headers and footers. | CURLOPT_HEADER
  HEADERFILE | The name of a file into which headers from the performed action are written. By default, if this file exists, it will be over-written. You can pass APPEND as an extra argument to append data to an existing file. | CURLOPT_WRITEHEADER CURLOPT_HEADERDATA
  HEADERSTEM | Specify the stem variable of an array into which any headers from the performed action are written. If the array exists, it will be over-written. Where possible, each entry in the array will contain a single line. | CURLOPT_WRITEHEADER
  HTTP200ALIASES | Specify a stem containing a list of aliases to be treated as valid HTTP 200 responses. Some servers respond with a custom header response line. For example, IceCast servers respond with "ICY 200 OK". By including this string in your list of aliases, the response will be treated as a valid HTTP header line such as "HTTP/1.0 200 OK". | CURLOPT_HTTP200ALIASES
  HTTPAUTH | Pass one or more of the following string values as seperate arguments. These option tell cURL which HTTP authentication options to attempt from the list. "AUTHBASIC": HTTP Basic authentication. This is the default choice, and the only method that is in wide-spread use and supported virtually everywhere. This is sending the user name and password over the network in plain text, easily captured by others. "AUTHDIGEST": HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. "AUTHGSSNEGOTIATE": HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain "Negotiate") method was designed by Microsoft and is used in their web applications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. "AUTHNTLM": HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. "AUTHANY": This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. "AUTHANYSAFE": This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. | CURLOPT_HTTPAUTH
  HTTPGET | Set this option to a 1 or Y to get cURL to return to HTTP GET mode. Really only useful if a POST was set with the same connection handle. | CURLOPT_HTTPGET
  HTTPHEADER | To pass a series of HTTP headers to the server, set this option to a valid Rexx stem. Any headers included in this option, that would have normally been generated internally by cURL, will be replaced. | CURLOPT_HTTPHEADER
  HTTPPOST | Set this option to a 1 or Y to indicate that a regular (application/x-www-form-urlencoded) HTTP POST is to be carried out. Most HTTP forms are of this type. See HTTPPOSTFIELDS option for details on how to specify the content of the form fields. | CURLOPT_POST
  HTTPPOSTDATA | Setting this option indicates that you wish to issue a multipart/formdata HTTP POST. You pass the data that is posted as a valid Rexx stem. | CURLOPT_HTTPPOST
  HTTPPOSTFORM | Setting this option indicates that the HTTP form data specified with CURLFORMADD is to be posted. No data is passed with this option. | CURLOPT_HTTPPOST
  HTTPPOSTFIELDS | Specify the content of the fields to be filled in with a HTTPPOST. The passed parameter is a Rexx array, with each item in the array a name/value pair. eg field.1 = 'email=M.Hessling@qut.edu.au' | CURLOPT_POSTFIELDS CURLOPT_POSTFIELDSIZE
  HTTPPROXYTUNNEL | Set this option to a 1 or Y to tunnel all non-http operations through the HTTP proxy. | CURLOPT_HTTPPROXYTUNNEL
  HTTPPUT | Set this option to a 1 or Y to get indicate that a HTTP PUT command is issued for the URL. The file to be uploaded must be specified with INFILE. | CURLOPT_PUT
  HTTPVERSION | Set this option to "VERSION_NONE", "VERSION_1_0" or "VERSION_1_1" to specify the version to be used in HTTP requests. | CURLOPT_HTTP_VERSION
  IGNORECONTENTLENGTH | Ignore the Content-Length header. This is useful for Apache 1.x (and similar servers) which will report incorrect content length for files over 2 gigabytes. If this option is used, curl will not be able to accurately report progress, and will simply stop the download when the server ends the connection. | CURLOPT_IGNORE_CONTENT_LENGTH
  INFILE | The name of a file from which data is read for the performed action. This file must exist. For ftp uploads, this is the file to upload. | CURLOPT_INFILE CURLOPT_READDATA
  INTERFACE | To specify an outgoing interface other than the default, pass the interface in this option. The interface can be specified as an IP address, a hostname, or an interface name (undex Unix). | CURLOPT_INTERFACE
  IPRESOLVE | Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that resolve addresses using more than one version of IP. The allowed values are: "IPRESOLVE_WHATEVER": Default, resolves addresses to all IP versions that your system allows. "IPRESOLVE_V4": Resolve to ipv4 addresses. "IPRESOLVE_V6": Resolve to ipv6 addresses. | CURLOPT_IPRESOLVE
  KRB4LEVEL | Set the krb4 security level, this also enables krb4 awareness. This is a string, "CLEAR", "SAFE", "CONFIDENTIAL" or "PRIVATE". If the string is set but doesn't match one of these, "PRIVATE" will be used. Pass the empty string to disable kerberos4. The kerberos support only works for FTP. | CURLOPT_KRB4LEVEL
  LOWSPEEDLIMIT | This option should contain a number representing the bytes per second that cURL will use as the lowest transfer rate to run at before it aborts the session as being too slow. | CURLOPT_LOW_SPEED_LIMIT
  LOWSPEEDTIME | This option should contain a number representing the number of seconds that cURL will use as the lowest transfer time to run for before it aborts the session as being too slow. | CURLOPT_LOW_SPEED_TIME
  MAXCONNECTS | You can specify how many persistent connections cURL is to maintain. The default is 5 and unless you know what you are doing leave it alone. | CURLOPT_MAXCONNECTS
  MAXFILESIZE | This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and FILESIZE_EXCEEDED will be returned. NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. | CURLOPT_MAXFILESIZE CURLOPT_MAXFILESIZE_LARGE
  MAXREDIRS | To limit the number of redirections followed, set this value with this option. This option only makes sense when FOLLOWLOCATION is also set. | CURLOPT_MAXREDIRS
  NETRC | This parameter controls the preference of libcurl between using user names and passwords from your ~/.netrc file, relative to user names and passwords in the URL supplied with the URL option. Note: cURL uses a user name (and supplied or prompted password) supplied with the option USERPWD in preference to any of the options controlled by this parameter. "OPTIONAL": The use of your ~/.netrc file is optional, and information in the URL is to be preferred. The file will be scanned with the host and user name (to find the password only) or with the host only, to find the first user name and password after that machine, which ever information is not specified in the URL. Undefined values of the option will have this effect. "IGNORED": The library will ignore the file and use only the information in the URL. This is the default. "REQUIRED": This value tells the library that use of the file is required, to ignore the information in the URL, and to search the file with the host only. Only machine name, user name and password are taken into account (init macros and similar things aren't supported). Note: cURL does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user. | CURLOPT_NETRC
  NETRCFILE | The name of a file you want to be used as a .netrc file. If this option is omitted, and NETRC option is set, then Rexx/CURL attempts to look for .netrc in the current user's home directory. | CURLOPT_NETRC_FILE
  NOBODY | Set this option to a 1 or Y to get cURL to not return the body information for those protocols, like HTTP, that have seperate headers and footers. | CURLOPT_NOBODY
  NODELAY | Set this option to a 1 or Y to get cURL to disable TCP's Nagle algorithm. The purpose of this algorithm is to try to minimize the number of small packets on the network (where "small packets" means TCP segments less than the Maximum Segment Size (MSS) for the network). Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without delay. This is less efficient than sending larger amounts of data at a time, and can contribute to congestion on the network if overdone. The option is off by default. This will have no effect after the connection has been established. | CURLOPT_NODELAY
  NOPROGRESS | Set this option to a 1 or Y to turn off cURL's default progress meter. | CURLOPT_NOPROGRES
  OUTFILE | The name of a file into which any output from the performed action is written. By default, if this file exists, it will be over-written. You can pass APPEND as an extra argument to append data to an existing file. This is necessary when using RESUMEFROM to resume a download. | CURLOPT_FILE CURLOPT_WRITEDATA
  OUTSTEM | Specify the stem variable of an array into which any output from the performed action is written. If the array exists, it will be over-written. Where possible, each entry in the array will contain a single line. | CURLOPT_FILE CURLOPT_WRITEDATA
  POSTQUOTE | See the prefered FTPCMDSAFTER option. | CURLOPT_POSTQUOTE
  PREQUOTE | See the prefered FTPCMDSBEFORE option. | CURLOPT_PREQUOTE
  PRIVATE | Pass a string of private data that can be associated with the cURL handle to be retrieved later with a call to CURLGETINFO with the PRIVATE option. | CURLOPT_PRIVATE
  PROGRESSFUNCTION | When uploading or downloading, cURL will call the specified internal Rexx procedure at regular intervals. Four arguments are passed; total bytes to download, bytes downloaded so far, total bytes to upload, bytes uploaded so far. This option is only valid if your Rexx interpreter has the RexxCallback() API (to date only Regina has this). | CURLOPT_PROGRESSFUNCTION
  PROXY | If you need to use a HTTP proxy to access the outside world, specify it with this option. The format of the proxy string is host[:port]. The default port number is 1080. | CURLOPT_PROXY
  PROXYAUTH | Pass one or more string values as seperate arguments. These options tell cURL which PROXY authentication options to attempt from the list. See HTTPAUTH for the list of valid string values. | CURLOPT_PROXYAUTH
  PROXYPORT | Specify the port to use for the proxy server. | CURLOPT_PROXYPORT
  PROXYTYPE | Set this option to "HTTP", "SOCKS4" or "SOCKS5". | CURLOPT_PROXYTYPE
  PROXYUSERPWD | Specify the username/password to use for the the HTTP proxy connection. The format is username[:password]. If the password is omitted, you will be prompted for it. | CURLOPT_PROXYUSERPWD
  QUOTE | See the prefered FTPCMDS option. | CURLOPT_QUOTE
  RANDOMFILE | The name of a file from which is used to seed the SSL random engine. This file must exist. | CURLOPT_RANDOM_FILE
  RANGE | Specify the required range you want in the format X-Y. I have no idea what this is! | CURLOPT_RANGE
  REFERER | Set this option to a string to set the header field: referer: in the HTTP request. | CURLOPT_REFERER
  RESUMEFROM | Set this option to the byte at which you want a request to start from. This is particularly useful for restarting a download that was interrupted. | CURLOPT_RESUME_FROM CURLOPT_RESUME_FROM_LARGE
  SOURCEPREQUOTE | Exactly like, PREQUOTE, but for source host. | CURLOPT_SOURCE_PREQUOTE
  SOURCEPOSTQUOTE | Exactly like, POSTQUOTE, but for source host. | CURLOPT_SOURCE_POSTQUOTE
  SOURCEQUOTE | Exactly like, QUOTE, but for source host. | CURLOPT_SOURCE_QUOTE
  SOURCEURL | When set, it enables a FTP third party transfer, using this value as source, while the option; URL is the target. | CURLOPT_SOURCE_URL
  SOURCEUSERPWD | Set this to a string in the format; "username:password" to use for the source connection when doing FTP third party transfers. | CURLOPT_SOURCE_USERPWD
  SSLCERT | To set a SSL certificate, set this option to the filename containing the certificate. The certificate should be in PEM format. | CURLOPT_SSLCERT
  SSLCERTPASSWD | The password associated with the SSL certificate set by SSLCERT can be set with this option. If you don't supply the password with this option, you will be prompted for it. | CURLOPT_SSLCERTPASSWD
  SSLCERTTYPE | The type of SSL certificate. One of "DER" or "PEM". | CURLOPT_SSLCERTTYPE
  SSLCIPHERLIST | The list of ciphers to use for the SSL connection. It consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, "-" and "+" can be used as operators. Valid examples of cipher lists include "RC4-SHA", "SHA1+DES", "TLSv1" and "DEFAULT". The default list is normally set when you compile OpenSSL. You'll find more details about cipher lists here. | CURLOPT_SSL_CIPHER_LIST
  SSLENGINE | Identifies the name of the crypto engine used for your private key. | CURLOPT_SSL_ENGINE
  SSLENGINEDEFAULT | Identifies the name of the default crypto engine used for asymetric crypto operations. | CURLOPT_SSL_ENGINEDEFAULT
  SSLKEY | The name of the file containing your private key. | CURLOPT_SSLKEY
  SSLKEYPASSWD | This will be used as the password required to use the SSLKEY private key. | CURLOPT_SSLKEYPASSWD
  SSLKEYTYPE | The format of your private key. One of "DER", "PEM" or "ENG". | CURLOPT_SSLKEYTYPE
  SSLPEERCERT | The name of a file from which the SSL peer certificate data is read for the performed action. This file must exist. | CURLOPT_CAINFO
  SSLVERIFYHOST | Set this if we should verify the Common name from the peer certificate in the SSL hand-shake, set to "1" to check existence, "2" to ensure that it matches the provided hostname. | CURLOPT_SSL_VERIFYHOST
  SSLVERIFYPEER | Set this option to a 1 or Y to indicate that the SSL peer's certificate should be verified. The SSL peer certificate must be specified with the SSLPEERCERT option. | CURLOPT_SSL_VERIFYPEER
  SSLVERSION | To over-ride the default SSL version used, pass this option in as a number. | CURLOPT_SSLVERSION
  TIMECONDITION | This defines how the TIMEVALUE time value is treated. You can set this parameter to "IFMODSINCE", "TIMECOND_IFUNMODSINCE" or "LASTMOD". This option is valid for HTTP or FTP. | CURLOPT_TIMECONDITION
  TIMEOUT | Specify the number of seconds in which the whole transaction is to complete. Note that this timeout period also includes the time taken to do name lookups, so don't specify too short a period. | CURLOPT_TIMEOUT
  TIMEVALUE | This should be the time in seconds since 1 jan 1970, and the time will be used in a condition as specified with TIMECONDITION. | CURLOPT_TIMEVALUE
  TRANSFERTEXT | Set this option to a 1 or Y to get indicate that FTP transfers are to be done in ASCII mode. For LDAP requests, the details are returned in plain text rather than HTML. | CURLOPT_TRANSFERTEXT
  UPLOAD | Set this option to a 1 or Y to indicate that an upload is to be done, rather than a download. | CURLOPT_UPLOAD
  UNRESTRICTEDAUTH | Set this option to a 1 or Y to indicate that Rexx/CURL can continue to send authentication (user+password) when following locations, even when hostname changed. Note that this is meaningful only when setting FOLLOWLOCATION. | CURLOPT_UNRESTRICTED_AUTH
  USERAGENT | Set this option to a string to set the header field: user-agent: in the HTTP request. This can be useful to imitate different browser clients. | CURLOPT_USERAGENT
  USERPWD | Specify the username/password to use for this connection. The format is username[:password]. If the password is omitted, you will be prompted for it. | CURLOPT_USERPWD
  URL | The URL against which the access is to be made. | CURLOPT_URL
  VERBOSE | Set this option to a 1 or Y to get cURL to display lots of details about what it is doing. | CURLOPT_VERBOSE

option value
  The value of the option to set.

Returns:

success:
  blank
failure:
  blank
  On failure CURLERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then CURLERROR.CURLCODE is also set to a non-zero value.

CURLFORMADD(handle,option=COPYCONTENTS,section name,content type,content) CURLFORMADD(handle,option=FILE,section name,content type,filename,[...]) CURLFORMADD(handle,option=FILE,section name,content type array,filename array)

This function is used to append sections when building multipart/formdata HTTP POST transfers. Any number of sections can be added by calling this multiple times before executing the transfer with the CURLPERFORM function.
Once CURLPERFORM has been called, call CURLFORMFREE to free resources used in this function.

Arguments:

handle
  The value returned from CURLINIT.

option
  One of COPYCONTENTS or FILE which specifies the valid arguments to follow.

section name
  The name to associate with this section of posted data.

content type
  The type of data present in content.Mandatory for COPYCONTENTS option, but for FILE option, if not specified, cURL tries to guess.

content
  The data comprising this part.

filename
  The name of the file containing the data for this part.

filename array
  A Rexx array containing names of the files containing the data for this part.

content type array
  A Rexx array of the types of data present in the filename array.If an item in the array is not specified, cURL tries to guess.

Returns:

success:
  blank
failure:
  blank
  On failure CURLERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then CURLERROR.CURLCODE is also set to a non-zero value.

CURLFORMFREE(handle)

This function is required to be called after calling CURLPERFORM if HTTP POST data is specified by calling CURLFORMADD.

Arguments:

handle
  The value returned from CURLINIT.

Returns:

success:
  blank
failure:
  blank
  On failure CURLERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then CURLERROR.CURLCODE is also set to a non-zero value.

CURLPERFORM(handle)

Once all the options have been set up, call this function to carry out the transfer.

Arguments:

handle
  The value returned from CURLINIT.

Returns:

success:
  blank
failure:
  blank
  On failure CURLERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then CURLERROR.CURLCODE is also set to a non-zero value.

CURLGETINFO(handle, option [,stem]

Retrieves information about the most recently executed command.
Arguments:

handle
  The value returned from CURLINIT.

option
  This is the string identifying the information to retrieve.

  Rexx/CURL Option | Description | cURL Equivalent Option
  --- | --- | ---
  CONNECT_TIME | Returns the number of seconds it took to connect to the remote server. | CURLINFO_CONNECT_TIME
  CONTENT_LENGTH_DOWNLOAD | Returns the length of the contents returned. This is the value returned by the header field; Content-Length: | CURLINFO_CONTENT_LENGTH_DOWNLOAD
  CONTENT_LENGTH_UPLOAD | Returns the length of the specified upload size. | CURLINFO_CONTENT_LENGTH_UPLOAD
  COOKIELIST | Returns the list of all cookies cURL knows (expired ones, too). The results are returned in the named stem (argument 3). | CURLINFO_COOKIELIST
  EFFECTIVE_URL | Returns the last used effective URL. | CURLINFO_EFFECTIVE_URL
  FILE_TIME | The time of the remote document received. This is only returned if setopt FILETIME is called. WHT FORMAT? CONVERT TIME_T TO TIME('N') | CURLINFO_FILETIME
  HEADER_SIZE | Returns the length of all headers returned. | CURLINFO_HEADER_SIZE
  HTTPAUTH_AVAIL | Returns a bitmask indicating the authentication method(s) available. The meaning of the bits is explained in the HTTPAUTH option for CURLSETOPT | CURLINFO_HTTPAUTH_AVAIL
  HTTP_CODE | Returns the last received HTTP code. Only useful if the last URL requested was HTTP. Use RESPONSE_CODE. | CURLINFO_HTTP_CODE
  NAMELOOKUP_TIME | Returns the time in seconds for the time taken to resolve the remote server name. | CURLINFO_NAMELOOKUP_TIME
  NUM_CONNECTS | Returns the number of new connections libcurl had to create to achieve the previous transfer (only the successful connects are counted). Combined with CURLINFO_REDIRECT_COUNT you are able to know how many times libcurl successfully reused existing connection(s) or not. See the Connection Options of curl_easy_setopt(3) to see how libcurl tries to make persistent connections to save time. | CURLINFO_NUM_CONNECTS
  OS_ERRNO | Returns the operating system errno from a connect failure. | CURLINFO_OS_ERRONO
  PRETRANSFER_TIME | Returns the total time taken from the start up until the transfer is about to begin. This time includes all pre-transfer commands and negotiations. | CURLINFO_PRETRANSFER_TIME
  PRIVATE | Returns the private string associated with the curl handle (set with the PRIVATE option to CURLSETOPT). | CURLINFO_PRIVATE
  PROXYAUTH_AVAIL | Returns a bitmask indicating the proxy authentication method(s) available. The meaning of the bits is explained in the PROXYAUTH option for CURLSETOPT | CURLINFO_PROXYAUTH_AVAIL
  REDIRECT_COUNT | Returns the total number of redirections that were actually followed. | CURLINFO_REDIRECT_COUNT
  REDIRECT_TIME | Returns the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. REDIRECT_TIME contains the complete execution time for multiple redirections. | CURLINFO_REDIRECT_TIME
  REQUEST_SIZE | Returns the total size of all requests. Note that this may be for more than one request if FOLLOWLOCATION was set. | CURLINFO_REQUEST_SIZE
  RESPONSE_CODE | Returns the last received HTTP or FTP code. This used to be known as HTTP_CODE. | CURLINFO_RESPONSE_CODE
  SIZE_DOWNLAOD | Returns the total number of bytes downloaded. | CURLINFO_SIZE_DOWNLOAD
  SIZE_UPLOAD | Returns the total number of bytes uploaded. | CURLINFO_SIZE_UPLOAD
  SPEED_DOWNLOAD | Returns the average download speed in bytes OR K? per second. | CURLINFO_SPEED_DOWNLOAD
  SPEED_UPLOAD | Returns the average upload speed in bytes OR K? per second. | CURLINFO_SPEED_UPLOAD
  SSL_ENGINES | Returns the list of supported SSL engines available. The results are returned in the named stem (argument 3). The return value will be the number of entries in the stem. | CURLINFO_SSL_ENGINES
  SSL_VERIFY_RESULT | Returns the result of the SSL certificate verification requested by SSLVERIFYPEER. | CURLINFO_SSL_VERIFYRESULT
  TOTAL_TIME | Returns the time in seconds for the complete transfer. | CURLINFO_TOTAL_TIME

Returns:

success:
  the value specified above
failure:
  blank
  On failure CURLERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then CURLERROR.CURLCODE is also set to a non-zero value.

CURLVARIABLE(variable name[,variable value])

Set or get the value for the specified variable.

The following variables are available in all implementations:

- VERSION (readonly) the version of Rexx/CURL, consisting of:
  - package name - rexxcurl
  - Rexx/CURL version - numerical version; eg. 1.0
  - Rexx/CURL date - Rexx standard date format; eg. 4 Jul 2001
  - OS platform - current operating system
  - cURL version - version of cURL library: libcurl version

  eg. REXXCURL 1.0 4 Jul 2001 UNIX libcurl 7.8

- DEBUG (setable) level of debugging requested.
  - 0 - no debugging information displayed (default)
  - 1 - Rexx variables displayed as set
    Equivalent to -v command line flag.
  - 2 - function entry/exit information displayed
    Equivalent to -d command line flag.
  - 4 - internal tracing information displayed
    Equivalent to -D command line flags.
  Any of the above values may be added together to combine their effects. eg. 6 is equivalent to -dD on the command line.

- DEBUGFILE (setable) file where debug information is sent.
  Any valid filename. If the file exists it will be overwritten If not specified, all dubugging information gets written to stderr.

- ERROR (setable) prefix for error code variables.
  Any valid Rexx variable name; usually a stem name. The default is CURLERROR.

Arguments:

variable name
  The name of the variable who's value is to be set or retrieved.

variable value
  The value that the variable to be set to.

Returns:

with variable value specified:
  success
  blank if a valid variable name specified and it is able to be set;
  failure
  blank and CURLERROR.INTCODE set to a non-zero value.

with variable value NOT specified:
  success
  the current value of the variable
  failure
  blank and CURLERROR.INTCODE is set to a non-zero value.

CURLLOADFUNCS()

This function is used to load all the Rexx/CURL external functions. This function is called after the function has been loaded with the Rexx builtin function rxfuncadd().

Although this function is useful only for dynamic library implementations of Rexx/CURL, it can be called by the executable version of Rexx/CURL. In this case it does nothing.

Arguments:

none

Returns:

success:
  zero
failure:
  non-zero

CURLDROPFUNCS()

This function is used to terminate Rexx/CURL and free up all resources that have been used.

It should be called at the end of every Rexx/CURL program. In particular, this function should be called after a syntax error has been caught with SIGNAL ON SYNTAX.

Arguments:

none

Returns:

success:
  zero
failure:
  non-zero

## 4. Errors

The success or failure of each function call is determined by the Rexx compound variable; CURLERROR.INTCODE. If the function call succeeds, this will be set to zero. If the function call fails, this will be set to a non-zero value. If the value set is 1 (one), a cURL error occured, and CURLERROR.CURLCODE is set to the appropriate error code. Associated with both error code variables, is an equivalent textual error message. These are CURLERROR.INTERRM and CURLERROR.CURLERRM respectively.
The stem name initially set for the error variables is CURLERROR. (including trailing period). You can change this to any value you prefer, with a call to CURLVARIABLE with the ERROR argument.

Internal Errors:

        1  - Error from cURL
        2  - Invalid Number
        3  - Invalid Option
        4  - Out of memory
        5  - Invalid cURL handle
        6  - Invalid filename
        7  - Invalid boolean
        8  - Expecting a stem as parameter
        9  - Invalid variable name specified
       10  - Attempt to set a readonly variable name
       11  - Too few arguments supplied
       12  - Field must be specified

## 5. Using Rexx/CURL

A typical Rexx/CURL program looks like the following program. This example will simply display the contents of my home page:

    Call RXFuncAdd 'CURLLoadFuncs','rexxcurl','CURLLoadFuncs'
    Call CURLLoadFuncs
    curl = CURLInit()
    If curl \= '' Then
       Do
          Call CURLSetOpt 'URL', "http://www.rexx.org/"
          If curlerror.intcode \= 0 Then Call Abort 'Error setting URL option'
          Call CURLPerform curl
          If curlerror.intcode \= 0 Then Call Abort 'Error performing action'
          Call CURLCleanup curl
       End
    Call CURLDropFuncs
    Return 0
    Abort:
    Parse Arg msg
    Say msg
    If curlerror.intcode = 1 Then Say 'Internal error:' curlerror.intcode curlerror.interrm
    Else Say 'CURL error:' curlerror.curlcode curlerror.curlerrm
    Call CURLCleanup curl
    Exit 1

Examples
Several example programs are provided with all Rexx/CURL distributions.

## History of Rexx/CURL

This section provides details of changes and additions made to the Rexx/CURL interface as it evolves.

### Version 1.4: 16 October 2005

- Additional return information (curlgetinfo) from cURL 7.14.0: NUM_CONNECTS, OS_ERRNO, SSL_ENGINES
- Additional return information (curlgetinfo) from cURL 7.14.1: COOKIELIST
- Added CURLFORMADD and CURLFORMFREE to provide more flexibility with HTTP POST options
- Additional options (curlsetopt) from cURL 7.15.0: FTPSKIPPASVIP

### Version 1.3: 4 October 2005

- Additional options (curlsetopt) from cURL 7.14.0: FTPSSL, FTPSSLAUTH, SOURCEPOSTQUOTE, SOURCEPREQUOTE, SOURCEQUOTE, SOURCEURL, SOURCEUSERPWD, TCPNODELAY

### Version 1.2: 2 December 2004

- Fixed bug with CURLGETINFO and returned string values
- Bring up-to-date with cURL 7.12.1 features
- First callback (PROGRESSFUNCTION) added (only works with Regina)
- Fixed SF bugs 516517 618127

### Version 1.1: 27 Jul 2003 (not released)

- Bring up-to-date with cURL 7.10.2 features

### Version 1.0: 4 Jul 2001

- Initial release for Unix platforms.

Last updated 16 October 2005