Supported cURL options

cURL (Client for URLs) is an open-standard library of software functions that enable the Insert from URL script step to support many common file transfer options. In this script step, use Specify cURL options to create a calculation that includes one or more of the following cURL options.

Note  Within cURL options, precede each quotation mark with a backslash. For example, to specify an HTTP header for Content-type: application/json, the text expression for Specify cURL options is:

"--header \"Content-type: application/json\""

Only the options listed below are supported by FileMaker clients. For more information, see the cURL documentation.

Option1 Parameter2 Notes

--anyauth

 

 

--aws-sigv4

<provider1[:provider2[:region[:service]]]>

To send Amazon Web Services (AWS) V4 signature authentication in HTTPS headers, specify a string for provider and, optionally, region and service. Also use --user to specify access_key_id:secret_access_key.

In server-side scripts, this option isn't supported by FileMaker Server on Ubuntu 20.

--basic

 

 

--cert

-E

<$[$]fmvariable[:password]>

Specify the client certificate file3 to use with HTTPS, FTPS, or another SSL-based protocol. Append :[password] to specify a passphrase for the client certificate.

This option assumes a certificate file that has the private key and the client certificate concatenated. Use --key, and --pass to specify them independently.

--cert-type

<type>

Specify the type of the client certificate. PEM, DER, and P12 are supported types. If not specified, PEM is used.

--ciphers

<list of ciphers>

 

--connect-timeout

<seconds>

Specify a decimal number of seconds.

--continue-at

-C

<offset>

Using "-" for current file size is not supported. Data replaces, not appends to, binary targets.

--cookie

-b

<name=data[;n2=d2]> or <$[$]fmvariable>

See table note 3.

--cookie-jar

-c

<$[$]fmvariable>

Direct file access and "-" are replaced with a FileMaker variable.

--crlf

 

 

--data

-d

<data> or @<$[$]fmvariable>

See table note 4.

--data-ascii

<data> or @<$[$]fmvariable>

See table note 4.

--data-binary

<data> or @<$[$]fmvariable>

See table note 4.

--data-raw

<data>

 

--data-urlencode

<data> or =<data> or @<$[$]fmvariable> or <name>=<data> or <name>@<$[$]fmvariable>

See table note 4.

--digest

 

 

--disable-eprt

 

 

--disable-epsv

 

 

--dump-header

-D

<$[$]fmvariable>

See table note 3.

--expect100-timeout

<seconds>

Specify a decimal number of seconds.

--fail

-f

 

 

--FM-return-container-variable

 

When Insert from URL targets a variable, use this option to force returned data to be stored as container data.

--FM-text-encoding

<encoding>

Converts text in the options that immediately follow this option from the FileMaker internal character encoding to the specified encoding. Use one of the names defined for the encoding parameter of the TextEncode function.

--form

-F

<name=content> or <name=@$[$]fmvariable>

See table note 4.

--form-string

<name=content>

 

--ftp-alternative-to-user

<command>

 

--ftp-create-dirs

 

 

--ftp-method

multicwd, nocwd, or singlecwd

Specify one of these methods.

--ftp-pasv

 

 

--ftp-port

-P

<interface> or <IP address> or <host name> or -

Append :[start]-[end] to specify a range of ports.

--ftp-pret

 

 

--ftp-skip-pasv-ip

 

 

--ftp-ssl-ccc

 

Also sets --ftp-ssl-ccc-mode to passive, if not already set.

--ftp-ssl-ccc-mode

active or passive

Specify one of these modes.

--ftp-ssl-control

 

 

--head

-I

 

 

--header

-H

<name: value>

Use this option once for each header you specify.

--ignore-content-length

 

 

--interface

<name>

 

--ipv4

-4

 

 

--ipv6

-6

 

 

--junk-session-cookies

-j

 

 

--keepalive-time

<seconds>

Specify an integer number of seconds.

--key-type

<type>

Specify the type of the private key file. DER and PEM are supported types. If not specified, PEM is used.

--key

<$[$]fmvariable>

Specify the private key file3. Use this option if you need to provide your private key separately from the certificate file.

--limit-rate

<speed[b|B|k|K|m|M|g|G]>

Specify an integer followed by an optional unit.

--list-only

-l

 

 

--local-port

<num>[-num]

Specify one port or a range of ports.

--location

-L

 

 

--location-trusted

 

 

--mail-auth

<address>

 

--mail-from

<address>

 

--mail-rcpt

<address>

 

--max-filesize

<bytes>

 

--max-time

-m

<seconds>

Specify a decimal number of seconds.

--no-compressed

 

By default, a compressed response is requested. Use this option to disable.

--no-keepalive

 

By default, keepalive messages are enabled. Use this option to disable.

--noproxy

<host[,host]> or *

 

--output

-o

<filename>

The filename is used only as an attribute of container data.

--pass

<phrase>

Passphrase for the private key. Use this option if you need to provide your private key's passphrase separately from the certificate file.

--path-as-is

 

 

--post301

 

 

--post302

 

 

--post303

 

 

--proxy

-x

<[protocol://][user:password@]proxyhost[:port]>

 

--proxy-anyauth

 

 

--proxy-basic

 

 

--proxy-digest

 

 

--proxy-header

<name: value>

Use this option once for each header you specify.

--proxy-user

-U

<user:password>

Unlike the curl command-line tool, if the password doesn't exist, FileMaker clients don't ask the user for it.

--proxy1.0

<proxyhost[:port]>

 

--proxytunnel

-p

 

 

--pubkey

<$[$]fmvariable>

Specify the public key file3 to use with SFTP protocol. Use --key and --pass to specify the private key and passphrase for the private key independently.

--quote

-Q

<command>

Use this option once for each command to the FTP server.

--range

-r

<range>

 

--raw

 

 

--referer

-e

<URL>

Supports ;auto at the end of the URL when used with --location.

--request

-X

<command>

 

--resolve

<host:port:address>

Use this option once for each resolver you specify.

--show-error

-S

 

See Handling errors.

--socks4

<host[:port]>

 

--socks4a

<host[:port]>

 

--socks5

<host[:port]>

 

--socks5-hostname

<host[:port]>

 

--speed-limit

-Y

<speed>

Specify an integer number of bytes per second.

--speed-time

-y

<time>

Specify an integer number of seconds.

--ssl

 

--ftp-ssl is also supported.

--ssl-reqd

 

--ftp-ssl-reqd is also supported.

--time-cond

-z

<date expression>

Only supports specifying a cURL-style date expression.

--tr-encoding

 

 

--trace

<$[$]fmvariable>

See table note 3.

--trace-ascii

<$[$]fmvariable>

See table note 3.

--trace-time

 

 

--upload-file

-T

<$[$]fmvariable>

See table note 3. Does not support globbing (specifying filenames that match a pattern). For FTP and FTPS, the filename after uploading to the server will be the same as the filename specified at the end of the URL. For all other supported protocols, the filename is the same as specified in the container data; any filename in the URL is ignored.

--use-ascii

-B

 

 

--user

-u

<user:password>

Unlike the curl command-line tool, if the password doesn't exist, FileMaker clients don't ask the user for it.

--user-agent

-A

<agent string>

 

--version

-V

 

Displays information about the version of the cURL library (libcurl). The first line shows the full version of libcurl and other linked third-party libraries. The second line (starting with "Features:") lists supported libcurl features.

Table notes

  1. For some options, long and short forms of the option name are supported (for example, ‑‑data and -d).

  2. Optional parts of parameters are in brackets [ ].

  3. Direct file access is replaced with a FileMaker variable.

  4. Direct file access is replaced with a FileMaker variable prefixed by the @ character.

Using variables

Although none of the supported options allow you to directly access or create files in the file system, you can specify a FileMaker variable as the source or destination of the data that the option requires. To access or create a file, you can set the variable to a container field.

To access a file, you can set the variable to a container field, which contains the file, then use that variable as the parameter of the cURL option.

To create a file, you can use a variable as the parameter of the cURL option, set a container field to that variable, then export the container field as a file.

Handling errors

Unsupported cURL options are ignored.

If you use the --show-error option:

  • When errors returned by the cURL library cause FileMaker clients to return error code 1631 via the Get(LastError) function to indicate an unspecified connection failure, the Get(LastErrorDetail) function returns the same text that the curl command-line tool returns.

  • When an operation succeeds but the server returns a response code of 400 or higher with the data, FileMaker clients return an appropriate error code. If there is no appropriate FileMaker error code, Get(LastError) returns 1631 and Get(LastErrorDetail) returns the response code in the form "Response code: nnn."

If you don't use the --show-error option, a server response code of 401 causes Get(LastError) to return FileMaker error code 1627 ("Authentication failed"). All other response codes return FileMaker error code 0 ("No error").

Example

Sends HTTPS POST data as two key-value pairs, fname=Bob and lname=Smith, to example.com using the credentials myusername and mypassword and stores the requested data in the $$results variable.

In the Insert from URL script step:

  • Set Target to the variable named $$results.

  • Set Specify URL to https://example.com/.

  • Set Specify cURL options to one of the following equivalent sets of options:

    "--user myusername:mypassword --data fname=Bob&lname=Smith"
    "--user myusername:mypassword -d fname=Bob --data-ascii lname=Smith"
    "--user myusername:mypassword -d @$post_data"

    where the variable $post_data is set to key-value pairs as text or set to a container field whose content is a text file containing key-value pairs.

This script shows the above example sending key-value pairs from a file in the post_data container field.

Copy 
Set Variable [ $post_data ; table::post_data ]
Insert from URL [ With dialog: Off ; Target: $$results ; 
"https://example.com/" ; Verify SSL Certificates ; 
cURL options: "--user myusername:mypassword -d @$post_data" ]