Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

CURL.Perform

Perform a file transfer.

Component Version macOS Windows Linux Server iOS SDK
CURL 2.5 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MBS( "CURL.Perform"; curl )   More

Parameters

Parameter Description Example
curl The CURL session handle. $curl

Result

Error OK or error.

Description

Perform a file transfer.
This function is called after the init and all the options are set, and will perform the transfer as described in the options. It must be called with the same handle as input as the CURL.New call returned.

You can do any amount of calls to CURL.Perform while using the same handle. If you intend to transfer more than one file, you are even encouraged to do so. CURL will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources. Just note that you will have to use the option functions between the invokes to set options for the following CURL.Perform.

You must never call this function simultaneously from two places using the same handle. Let the function return first before invoking it another time. If you want parallel transfers, you must use several curl handles.

While transfer is running, your FileMaker application is blocked. It's useful to show progress with using CURL.SetUpdateProgressDialog. Or you use CURL.PerformInBackground or CURL.PerformAsync to run the transfer in background.

Internal buffer for output, debug and header data is cleared before the perform.

This function returns error codes. If you get an error, please use CURL.GetDebugMessages to read the transcription of the transfer and look for error messages from server.
Typical error codes are 6 for a wrong domain name in the URL, 67 for wrong name/password combination, 60 for missing/bad SSL settings, 1 for an unsupported protocol.

In case of error 60, please decide what SSL policy you want and use our SSL options. e.g. use CURL.SetOptionSSLVerifyHost and CURL.SetOptionSSLVerifyPeer to disable SSL security or use CURL.SetOptionCAInfo to point CURL to a certificate.

No error means the data transfer was okay, but it doesn't tell you if for example a web server reported an error. Please check CURL.GetResponseCode for HTTP requests to get the HTTP status code. e.g. 404 if file is not found.

The list of possible error codes:

NameNumberDescription
CURLE_OK0No error.
CURLE_UNSUPPORTED_PROTOCOL1Unsupported protocol.
CURLE_FAILED_INIT2Initialization failed or option not available.
CURLE_URL_MALFORMAT3URL has wrong format.
CURLE_COULDNT_RESOLVE_PROXY5DNS didn't return proxy IP.
CURLE_COULDNT_RESOLVE_HOST6DNS didn't return IP for host.
CURLE_COULDNT_CONNECT7Connection failed.
CURLE_FTP_WEIRD_SERVER_REPLY8FTP error.
CURLE_REMOTE_ACCESS_DENIED9A service was denied by the server due to lack of access when login fails this is not returned.
CURLE_FTP_WEIRD_PASS_REPLY11FTP error.
CURLE_FTP_WEIRD_PASV_REPLY13FTP error.
CURLE_FTP_WEIRD_227_FORMAT14FTP error.
CURLE_FTP_CANT_GET_HOST15FTP error.
CURLE_FTP_COULDNT_SET_TYPE17FTP set command failed.
CURLE_PARTIAL_FILE18Only a part of the file was downloaded.
CURLE_FTP_COULDNT_RETR_FILE19File not found.
CURLE_QUOTE_ERROR21quote command failure
CURLE_HTTP_RETURNED_ERROR22HTTP returned an error.
CURLE_WRITE_ERROR23Write error.
CURLE_UPLOAD_FAILED25failed upload "command"
CURLE_READ_ERROR26couldn't open/read from file
CURLE_OUT_OF_MEMORY27Out Of memory
CURLE_OPERATION_TIMEDOUT28the timeout time was reached
CURLE_FTP_PORT_FAILED30FTP PORT operation failed
CURLE_FTP_COULDNT_USE_REST31the REST command failed
CURLE_RANGE_ERROR33RANGE "command" didn't work
CURLE_HTTP_POST_ERROR34HTTP Post failed.
CURLE_SSL_CONNECT_ERROR35wrong when connecting with SSL
CURLE_BAD_DOWNLOAD_RESUME36couldn't resume download
CURLE_FILE_COULDNT_READ_FILE37Failed to read file.
CURLE_LDAP_CANNOT_BIND38LDAP can't connect.
CURLE_LDAP_SEARCH_FAILED39LDAP Search failed.
CURLE_FUNCTION_NOT_FOUND41Function not found.
CURLE_ABORTED_BY_CALLBACK42Transfer aborted with CURL.Cancel.
CURLE_BAD_FUNCTION_ARGUMENT43Bad parameters.
CURLE_INTERFACE_FAILED45CURL.OptionInterface failed
CURLE_TOO_MANY_REDIRECTS 47catch endless re-direct loops
CURLE_UNKNOWN_TELNET_OPTION48User specified an unknown option
CURLE_TELNET_OPTION_SYNTAX 49Malformed telnet option
CURLE_PEER_FAILED_VERIFICATION51peer's certificate or fingerprint wasn't verified fine
CURLE_GOT_NOTHING52when this is a specific error
CURLE_SSL_ENGINE_NOTFOUND53SSL crypto engine not found
CURLE_SSL_ENGINE_SETFAILED54can not set SSL crypto engine as default
CURLE_SEND_ERROR55failed sending network data
CURLE_RECV_ERROR56failure in receiving network data
CURLE_SSL_CERTPROBLEM58problem with the local certificate
CURLE_SSL_CIPHER59couldn't use specified cipher
CURLE_SSL_CACERT60problem with the CA cert (path?)
CURLE_BAD_CONTENT_ENCODING61Unrecognized transfer encoding
CURLE_LDAP_INVALID_URL62Invalid LDAP URL
CURLE_FILESIZE_EXCEEDED63Maximum file size exceeded
CURLE_USE_SSL_FAILED64Requested FTP SSL level failed
CURLE_SEND_FAIL_REWIND65Sending the data requires a rewind that failed
CURLE_SSL_ENGINE_INITFAILED66failed to initialise ENGINE
CURLE_LOGIN_DENIED67user, password or similar was not accepted and we failed to login
CURLE_TFTP_NOTFOUND68file not found on server
CURLE_TFTP_PERM69permission problem on server
CURLE_REMOTE_DISK_FULL70out of disk space on server
CURLE_TFTP_ILLEGAL71Illegal TFTP operation
CURLE_TFTP_UNKNOWNID72Unknown transfer ID
CURLE_REMOTE_FILE_EXISTS73File already exists
CURLE_TFTP_NOSUCHUSER74No such user
CURLE_CONV_FAILED75conversion failed
CURLE_CONV_REQD76caller must register conversion callbacks
CURLE_SSL_CACERT_BADFILE77could not load CACERT file, missing or wrong format
CURLE_REMOTE_FILE_NOT_FOUND78remote file not found
CURLE_SSH79error from the SSH layer, somewhat generic so the error message will be of interest when this has happened
CURLE_SSL_SHUTDOWN_FAILED80Failed to shut down the SSL connection
CURLE_AGAIN81socket is not ready for send/recv, wait till it's ready and try again.
CURLE_SSL_CRL_BADFILE82could not load CRL file, missing or wrong format.
CURLE_SSL_ISSUER_ERROR83Issuer check failed.
CURLE_FTP_PRET_FAILED84a PRET command failed
CURLE_RTSP_CSEQ_ERROR85mismatch of RTSP CSeq numbers
CURLE_RTSP_SESSION_ERROR86mismatch of RTSP Session Identifiers
CURLE_FTP_BAD_FILE_LIST87unable to parse FTP file list
CURLE_CHUNK_FAILED88chunk callback reported error

With SFTP, you can get logged error "Upload failed: Operation failed (4/-31)" when upload uses path to folder instead of file in URL.

Examples

Query a REST API:

# new session
Set Variable [$curl; MBS( "CURL.New" ) ] ]
# set URL for this REST API
Set Variable [$rMBS("CURL.SetOptionURL"; $curl; "https://example.test/wc-api/v2/products") ]
# make a post with some data
Set Variable [$rMBS("CURL.SetOptionPost"; $curl; 1) ]
Set Variable [$rMBS("CURL.SetOptionPostFields"; $curl; "{product:{...}}"; "UTF-8") ]
# set credentials
Set Variable [$rMBS("CURL.SetOptionUserName"; $curl; "consumer_key") ]
Set Variable [$rMBS("CURL.SetOptionPassword"; $curl; "consumer_secret") ]
# add header option
Set Variable [$rMBS("CURL.SetOptionHTTPHeader"; $curl; "Content-Type: application/json"; "Expect:" ) ]

# run it!
Set Variable [$ErrorMBS( "CURL.Perform"; $curl ) ]
# check debug messages
Set Variable [$MessagesMBS("CURL.GetDebugMessages"; $curl) ]
# check result
Set Variable [$OutputMBS("CURL.GetResultAsText"; $curl) ]
# and cleanup
Set Variable [$rMBS( "CURL.Release"; $curl ) ]

Run a generic POST request for REST or SOAP web service:

# new session
Set Variable [$curl; Value:MBS("CURL.New")]
# use stripe charge API
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "https://someURL/service")]
# set user name and password if needed:
Set Variable [$result; Value:MBS("CURL.SetOptionUserName"; $curl; "user name")]
Set Variable [$result; Value:MBS("CURL.SetOptionPassword"; $curl; "password")]
# set some additional headers, which may include custom authorization and content types:
Set Variable [$result; Value:MBS( "CURL.SetOptionHTTPHeader"; $curl; "Authorization: Bearer a92eabb9-76f9-42ee-b280-bcd15cb2e9db"; "Content-Type: application/json" )
# make a post with given content:
Set Variable [$result; Value:MBS("CURL.SetOptionPostFields"; $curl; $json]
# perform
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
# now check result
Set Field [CURL Test::Text; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
Set Field [CURL Test::header; MBS("CURL.GetDebugMessages"; $curl)]
# cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

Using Rosette web service:

# Start new CURL transfer
Set Variable [$curl; Value:MBS("CURL.New")]
# Set options like Verbose Debug Messages
Set Variable [$result; Value:MBS("CURL.SetOptionVerbose"; $curl; 1)]
# the url of webservice
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "https://api.rosette.com/rest/v1/morphology/parts-of-speech")]
# the header info for tagging, API Key comes from a global field.
Set Variable [$result; Value:MBS("CURL.SetOptionHTTPHeader"; $curl; "user_key: " & RosetteAPISettings::RosetteAPIKey; "Content-Type: application/json"; "Accept: application/json" )]
# We want a POST transfer:
Set Variable [$result; Value:MBS("CURL.SetOptionPost"; $curl; 1 )]
# Build JSON using the plugin function to properly encode a string:
Set Variable [$request; Value:"{\"content\": " & MBS("JSON.CreateString"; TextData::TextAsInput) & "}"]
Set Variable [$result; Value:MBS("CURL.SetOptionPostFields"; $curl; $request)]
#show our JSON in a field for debugging:
Set Field [TextData::CURLInput; $request]
#Run transfer
Set Variable [$result; Value:MBS("CURL.Perform"; $curl)]
# Check result and debug messages
Set Field [TextData::CurlDebug; MBS("CURL.GetDebugMessages"; $curl)]
Set Field [TextData::CurlOutput; MBS("CURL.GetResultAsText"; $curl)]
# Cleanup
Set Variable [$r; Value:MBS("CURL.Release"; $curl)]

Download a text from URL:

# start new transfer
Set Variable [$curl; Value:MBS("CURL.New")]
# set URL
Set Variable [$r; Value:MBS("CURL.SetOptionURL"; $curl; "https://www.mbsplugins.eu/")]
# run transfer
Set Variable [$ErrorCode; Value:MBS("CURL.Perform"; $curl)]
# get result as text and debug messages:
Set Variable [$TextResult; Value:MBS( "CURL.GetResultAsText"; $curl)]
Set Variable [$DebugMessages; Value:MBS( "CURL.GetDebugMessages"; $curl)]
# cleanup
Set Variable [$r; Value:MBS("CURL.Release"; $curl)]

Charge with Stripe webservice:

# new session
Set Variable [$curl; Value:MBS("CURL.New")]
# use stripe charge API
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "https://api.stripe.com/v1/charges")]
# set user name
Set Variable [$result; Value:MBS("CURL.SetOptionUserName"; $curl; "sk_test_ your id here")]
# make a post with given content:
Set Variable [$result; Value:MBS("CURL.SetOptionPost"; $curl; 1)]
Set Variable [$result; Value:MBS("CURL.SetOptionPostFields"; $curl; "amount=400&currency=usd&description=Charge%20for%20test@example.com&source[object]=card&source[number]=4242424242424242&source[exp_month]=12&source[exp_year]=2017&source[cvc]=123")]
# perform
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
# now check result
Set Field [CURL Test::Text; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
Set Field [CURL Test::header; MBS("CURL.GetDebugMessages"; $curl)]
# cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

Download URL to temp file:

Set Variable [$curl; Value:MBS("CURL.New")]
#this is URL to download
Set Variable [$url; Value:"https://www.monkeybreadsoftware.com/filemaker/test.txt"]
#get file name from URL
Set Variable [$name; Value:MBS( "Path.LastPathComponent"; $URL )]
#now make temp file path
Set Variable [$path; Value:MBS( "Path.AddPathComponent"; MBS( "Folders.SystemTemporary" ); $name )]
#set URL to download
Set Variable [$r; Value:MBS("CURL.SetOptionURL"; $curl; $url)]
#open destination file
Set Variable [$r; Value:MBS("CURL.CreateOutputFile"; $curl; $path)]
#run transfer
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
#close destination file
Set Variable [$r; Value:MBS("CURL.CloseOutputFile"; $curl)]
#get debug messages
Set Field [CURL Test::debug; MBS("CURL.GetDebugMessages"; $curl)]
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

Query IP via ipinfo.io:

Go to Layout [“Table”]
New Record/Request
#Start new session
Set Variable [$curl; Value:MBS("CURL.New")]
#Set URL to load (HTTP, HTTPS, FTP, FTPS, SFTP, etc.)
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "http://ipinfo.io")]
#RUN now
Set Variable [$result; Value:MBS("CURL.Perform"; $curl)]
#Check result
Set Field [Table::DebugLog; MBS("CURL.GetDebugMessages"; $curl)]
Set Field [Table::Result; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
If [$result = "OK"]
    #Check HTTP error code
    Set Variable [$response; Value:MBS("CURL.GetResponseCode"; $curl)]
    If [$response = 200]
        #Query values from JSON
        Set Variable [$json; Value:MBS( "JSON.Parse"; Table::Result )]
        Set Field [Table::IP; MBS("JSON.GetPathItem"; $json; "ip"; 1)]
        Set Field [Table::Hostname; MBS("JSON.GetPathItem"; $json; "hostname"; 1)]
        Set Field [Table::City; MBS("JSON.GetPathItem"; $json; "city"; 1)]
        Set Field [Table::Region; MBS("JSON.GetPathItem"; $json; "region"; 1)]
        Set Field [Table::Country; MBS("JSON.GetPathItem"; $json; "country"; 1)]
        Set Field [Table::Location; MBS("JSON.GetPathItem"; $json; "loc"; 1)]
        Set Field [Table::Company or Provider; MBS("JSON.GetPathItem"; $json; "org"; 1)]
        Set Variable [$r; Value:MBS( "JSON.Release"; $json )]
    End If
End If
#Cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]
Commit Records/Requests [No dialog]

Query fedex for tracking status:

#Start new session
Set Variable [$curl; Value:MBS("CURL.New")]
#Set URL to load (HTTP, HTTPS, FTP, FTPS, SFTP, etc.)
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "https://www.fedex.com/trackingCal/track/v1/shipments/trackingnumbers")]
# set query content including the trackingNumber
Set Variable [$result; Value: MBS("CURL.SetOptionPostFields"; $curl; "{\"TrackPackagesRequest\":{\"appType\":\"WTRK\",\"appDeviceType\":\"WTRK\",\"uniqueKey\":\"\",\"processingParameters\":{},\"trackingInfoList\":[{\"trackNumberInfo\":{\"trackingNumber\":\"" & $trackingNumber & "\",\"trackingQualifier\":\"\",\"trackingCarrier\":\"\"}}]}}") ]
Set Variable [$result; Value:MBS("CURL.SetOptionHTTPHeader"; $curl; "Content-Type: application/json")]
#RUN now
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
#Check result
Set Field [CURL Test::Text; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
Set Field [CURL Test::debug; MBS("CURL.GetDebugMessages"; $curl)]
#Cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

Send request to Apple's gsx webservice:

Set Variable [$XMLRequest; Value:""]
#Start new session
Set Variable [$curl; Value:MBS("CURL.New")]
# URL for web service
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "https://gsxapiut.apple.com:443/gsx-ws/services/emea/asp")]
# Mark content as XML
Set Variable [$result; Value:MBS("CURL.SetOptionHTTPHeader"; $curl; "Content-Type: text/xml; charset=UTF-8")]
# Pass XML content for request
Set Variable [$result; Value:MBS("CURL.SetOptionPostFields"; $curl; $XMLRequest)]
# Certificate and private key in one file
Set Variable [$result; Value:MBS("CURL.SetOptionSSLCert"; $curl; "/Users/cs/Keys/apple-cert+key.pem")]
# Root certificates
Set Variable [$result; Value:MBS("CURL.SetOptionCAInfo"; $curl; "/Users/cs/Keys/cacert.pem")]
# SSL Key is in PEM Format
Set Variable [$result; Value:MBS("CURL.SetOptionSSLCertType"; $curl; "PEM")]
# Password for key file
Set Variable [$result; Value:MBS("CURL.SetOptionKeyPassword"; $curl; "xxx")]
# SSL Verification on
Set Variable [$result; Value:MBS("CURL.SetOptionSSLVerifyPeer"; $curl; 1)]
Set Variable [$result; Value:MBS("CURL.SetOptionSSLVerifyHost"; $curl; 1)]
# use TLS v1.2
Set Variable [$result; Value:MBS("CURL.SetOptionSSLVersion"; $curl; 6)]
#RUN now
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
#Check result
Set Field [CURL Test::Text; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
Set Field [CURL Test::debug; MBS("CURL.GetDebugMessages"; $curl)]
#Cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

Upload file from OS X to IBM Mainframe:

Set Variable [$debug; Value:""]
Set Variable [$curl; Value:MBS("CURL.New")]
Set Variable [$result; Value:MBS("CURL.SetOptionUpload"; $curl; 1)]
Set Variable [$result; Value:MBS("CURL.SetOptionUserName"; $curl; "xxx")]
Set Variable [$result; Value:MBS("CURL.SetOptionPassword"; $curl; "yyy")]
Set Variable [$result; Value:MBS( "CURL.OpenInputFile"; $curl; "/Users/gene/Desktop/MY.Logfile.txt")]
Set Variable [$result; Value:MBS( "CURL.SetOptionURL"; $curl; "ftp://192.168.1.4:21/MY.LOGFILE1" )]
Set Variable [$result; Value:MBS("CURL.SetOptionVerbose"; $curl; 1)]
Set Variable [$result; Value:MBS( "CURL.SetOptionTransferText"; $curl; 1 )]
Set Variable [$result; Value:MBS( "CURL.SetOptionSSLVerifyPeer"; $curl; 0 )]
Set Variable [$result; Value:MBS( "CURL.SetOptionSSLVerifyHost"; $curl; 0 )]
Set Variable [$result; Value:MBS( "CURL.SetOptionQuote"; $curl; "site RECFM=FB LRECL=1024")]
Set Variable [$result; Value:MBS("CURL.Perform"; $curl)]
Set Variable [$debug; Value:MBS("CURL.GetDebugMessages"; $curl)]
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

OAuth2 Token authentication with passing credentials via POST:

Set Variable [ $Curl ; Value: MBS("CURL.New") ]
#
# Change path to your CACert PEM File.
Set Variable [ $CacertPath ; Value: "C:\Users\Public\cacert.pem" ]
// Set Variable [ $Result ; Value: MBS( "CURL.SetOptionCAInfo"; $curl; $cacertPath ) ]
// Set Variable [ $Result ; Value: MBS( "CURL.SetOptionSSLVerifyHost"; $curl; 2 ) ]
// Set Variable [ $Result ; Value: MBS( "CURL.SetOptionSSLVerifyPeer"; $curl; 1 ) ]
Set Variable [ $Result ; Value: MBS("CURL.SetOptionVerbose"; $curl; 1) ]
#
# credentials
Set Variable [ $secret ; Value: "xxx" ]
Set Variable [ $client ; Value: "yyy" ]
Set Variable [ $domain ; Value: "zzz" ]
Set Variable [ $Result ; Value: MBS("CURL.SetOptionURL"; $curl; "https://" & $domain & "/auth/realms/demo/protocol/openid-connect/token") ]
#
# POST with form encoding
Set Variable [ $result ; Value: MBS("CURL.SetOptionHTTPHeader"; $curl; "content-type: application/x-www-form-urlencoded") ]
Set Variable [ $Result ; Value: MBS("CURL.SetOptionPostFields"; $curl; "grant_type=client_credentials&client_id="& $client & "&client_secret=" & $secret) ]
#
# run it
Set Variable [ $Result ; Value: MBS("CURL.Perform"; $curl) ]
Set Variable [ $DebugText ; Value: MBS("CURL.GetDebugMessages"; $curl) ]
Set Variable [ $ResultText ; Value: MBS("CURL.GetResultAsText"; $curl) ]
If [ $result = "OK" ]
    # extract token
    Set Variable [ $Token ; Value: JSONGetElement ( $ResultText; "access_token" ) ]
    Set Field [ tbl_debugger::token ; $Token ]
End If
Set Field [ tbl_debugger::header ; $DebugText ]
Set Variable [ $Result ; Value: MBS("CURL.Release"; $curl) ]

See also

Release notes

Example Databases

Blog Entries

This function checks for a license.

Created 18th August 2014, last changed 7th February 2023


CURL.Options - CURL.PerformAsync