DUMP_FILE_CONTENTS

Declare the response to be destined for a file, or receive a file or a part thereof, in the body of a response as a download from a REST API.

DUMP_FILE_CONTENTS(LocalFilePath,OptionList)

vUhttp->DUMP_FILE_CONTENTS("mydocs.zip", "total=10k")

Parameters

Parameter

Type

Direction

Description

LocalFilePath

string

INOUT

Name of the file whose contents will be added to the HTTP request body. Uniface syntax for (zip) files can be used but no assignment file redirection is supported.

OptionList

string

OUT

Associative list of name-value pairs

Options

Parameter

Description

TOTAL=Size

For simple (non-chunked) transfers only, specify the size of the file to be downloaded. Size is expressed as:

  • Num{k} (kilobytes). For example: 4 or 4k
  • Numm (megabytes). For example: 16m

A buffer of this size will be allocated to minimize the number of re-allocations in memory.

  • Default: 16k
  • Minimum: 4k
  • Maximum: 1024m

CHUNK=Size

Use a chunked file transfer to download the file of the specified size. Size is expressed as Num{k | m}

Each REST API has its own size limits, but for Uniface, the limits are:

  • Minimum: 4 (4k)
  • Maximum: 1024m

STARTAT=Num

For chunked file transfer only, resets the file position in order to receive lost chunks.

TCPRCVBUF=Size

Specifies the size of the TCP Receive Buffer. It can be used to improve performance when downloading large files or chunks.

Size is expressed as Num{k | m}

  • Minimum: 4k
  • Maximum: None.

The maximum buffer size depends on the local TCP stack. Normally, if a value is specified that is larger than the maximum, then the maximum value is used.

TCPSNDBUF=Size

Specifies the size of the TCP Send Buffer. It can be used to improve performance when uploading large files or chunks.

  • Minimum: 4k
  • Maximum: None.

Size is expressed as Num{k | m}

The maximum buffer size depends on the local TCP stack. Normally, if a value is specified that is larger than the maximum, then the maximum value is used.

Return Values

Values Returned in $status

Value

Meaning

>=0

Successfully loaded, showing the number of bytes written

-1

Cannot open the specified file

-2

Cannot reposition to STARTAT in the file

-3

Problems reading file

-4

Invalid option in the OptionList

-5

Invalid value for option in the OptionList

-12

Internal error occurred

Description

The DUMP_FILE_CONTENTS operation must be called once before the SEND operation to declare that the body of the response is to be treated as file contents, and once after the SEND operation to actually place the body of the response into a file. Nothing is returned in the Contents parameter of the SEND operation. If errors occur, the file will be closed, irrespective of its state.

For downloading a file, the REST API may redirect the SEND call to a download URL. By default, these re-directions are automatically followed, which may not produce the desired effect, if extra headers are required. To stop automatic redirection, you should use the SET_FLAGS operation to specify the 16 flag.

To improve the speed of single or chunked downloads, you can specify a larger TCP Receive Buffer using the TCPRCVBUF option. For example, on Windows the default buffer size is 8K. By setting it to 512K you can significantly improve performance.

Chunked Downloads

Many APIs impose an upper limit to the size of file that can be transfered in one request. They also set limits on the chunk size being a multiple of some size. There is a balance between the chunk size and how many chunks have to be sent, as a result of that. The chunk size is allocated as a single buffer. The larger it is the fewer repeat calls you need to make. The Uniface limit is for a file or chunk of a file is 2GB. The limits for most APIs is likely to be substantially smaller.

When downloading a file in chunks, you must use the CHUNK option to specify the file size. A buffer of this size will be allocated in order to minimize the number of re-allocations in memory. The number of bytes actually transferred in the response of the SEND operation may be controlled by a Range header, which you must provide.

Repeated calls to SEND and then DUMP_FILE_CONTENTS are required to download the complete file. The last chunk to be transferred will probably be smaller than the previous chunks if a range header is used. You must provide an updated Range header to inform the REST API of which chunk is required. This operation can only handle one range at a time.

Call Order for Downloading Files

The following code demonstrates the call order when using the DUMP_FILE_CONTENTS operation to download a file. It is assumed that the remote file path is specified in headers or the URL.

  • vUhttp is a handle to a UHTTP component instance
  • vInfo is a variable to hold returned string information
  • vLen is a variable to hold returned content length
  • vHeaders is a variable that holds headers
  • vResp is a variable to hold the response
Simple Download 
vUhttp->SET_FLAGS(8)	; GET send headers
vUhttp->DUMP_FILE_CONTENTS("your.jpg", "")
vUhttp->SEND(vUrl, "GET", "", "", vHeaders, "", vResp)
vUhttp->DUMP_FILE_CONTENTS("", "")
Chunked Download

In this example, a loop is constructed to process a a filed in chunks. 

vUhttp->SET_FLAGS(8 )	; GET send headers
vUhttp->DUMP_FILE_CONTENTS("your.zip", "chunk=256k")

repeat
  vUhttp->GET_INFO("range", vInfo)
  vHeaders = ""
  putitem/id/case vHeaders, "Range", "%%vInfo"
  vUhttp->SEND(vUrl, "GET", "", "", vHeaders, "", vResp)
  vUhttp->DUMP_FILE_CONTENTS("", "")
until (<DefineCondition>)

vUhttp->CLOSE_FILE()

Related Topics