.CLIENT DOWNLOAD FILE

This subroutine will download a file to the user's PC.

Usage:

      PASS         <status_code>              FIELD            SHARE? Y
      PASS         <dest_file>                FIELD            SHARE? Y
      PASS         <source_file>              FIELD            SHARE? N
      PASS         <convert_flag>             FIELD            SHARE? N
      GOSUB    --- .CLIENT DOWNLOAD FILE
      *        check for errors
      IF       --- .CLIENT DOWNLOAD FILE      NE

Description:

This subroutine will download a file to the user's PC. The first three parameters are required, if any are missing the subroutine will CANCEL. The <convert_flag> is optional. If the <dest_file> exists on the user's PC, it will be overwritten without warning (if permissions allow it).

<status_code> is the code returned to indicate if the transfer was successful (Required). This field must be PASSed with Share "Y" to receive the value. A value of 1 indicates the transfer was not successful and 0 indicates success. If the transfer failed, you can check --- .CLIENT DOWNLOAD FILE for more information. Note that <status_code> might indicate success and --- .CLIENT DOWNLOAD FILE might contain a warning message. <status_code> is the final authority on whether the transfer worked or not.

<dest_file> is the destination on the user's PC (Required). You can refer to macro names in the destination, ie, you can use any of the names you see in the [LocalPaths] section of the Desktop Client preferences, just prefix them with a $ and surround them with parentheses, ie, $(userHome). If you PASS this field shared, then it will contain the expanded path after the upload. If --- .CLIENT DOWNLOAD FILE contains 'Dest filenam truncated', it means your field was too short to contain the expanded name. This does not mean the actual file name on disk was truncated.

<source_file> is the is the full path and file name on the Appx server that you want to transfer to the user's PC (Required). This must be a file readable by user 'appx' (Linux/Unix) or the current user (Windows).

<convert_flag> indicates if any file conversion is required (Optional). The allowable values are:

• NO - no conversion will be done. This is the default if not PASSed.
• AUTO-EXT - convert the file automatically based on the filename extension.
• AUTO-CONTENT - convert the file automatically based on the contents of the file (ie, it won't convert binary files).
• YES - Do the conversion regardless of file type.

If conversion is requested, this routine will make a temporary copy of the file, converting as necessary, then upload the converted file. The temporary copy will be deleted. The temporary copy is created in the applications 'Tmpdata' folder, same as the working files for a restructure.

The routine considers the following file extensions to be text files:

If a <convert_flag> of AUTO-CONTENT is passed, the routine will read approximately the first 1000 bytes of the file and look for characters in the range ASCII 0 to 9 (0x00 to 0x09), or ASCII 14 to 31 (0x0e to 0x1f). If any are found, the file is assumed to be binary and no conversion will take place.

If the file is determined to be a text file (either by extension or the lack of binary characters), the routine looks for the presense of a CR/LF pair in the first ~1000 characters of the source file to determine if it's in Unix or Windows format and then uses the following matrix to decide if the file really needs to be converted:

Host      Client      Source
OS        OS          File Type       Conversion
--------  ----------  --------------  -------------------------
UNIX      UNIX        UNIX            No conversion needed.
UNIX      UNIX        WINDOWS         CR/LF to LF
UNIX      WINDOWS     UNIX            LF to CR/LF
UNIX      WINDOWS     WINDOWS         No conversion needed.
WINDOWS   WINDOWS     WINDOWS         No conversion needed.
WINDOWS   WINDOWS     UNIX            LF to CR/LF
WINDOWS   UNIX        WINDOWS         CR/LF to LF
WINDOWS   UNIX        UNIX            No conversion needed.

HTML Client Considerations

Downloading files to the HTML client normally requires a Local Connector (See AppxHTMLClient for a discussion of the Local Connector). Starting in Release 5.4.5, you can download files without the Local Connector. See .CLIENT CHECK FOR GUI to how to determine which client the user is running.

You have 2 options to send to the client without using the Local Connector:

• Prefix the destination file name with $(pushAndOpen), e.g. $(pushAndOpen)/openthis.pdf). This tells the HTML client that you want the browser download the file and to try to open it. If the browser doesn't support opening that file type then it will ask the user to save file, which is normal browser behavior. The file will open an a new tab in the browser for one time viewing, i.e., the tab cannot be refreshed or the link shared.
• Prefix the destination file name with $(pushAndSave), e.g. $(pushAndSave)/savethis.pdf. This tells the HTML client that you want the browser to handle downloading and saving the file. The behaviour is browser specific, i.e., some browsers will automatically save the file to the default download location, and others may display a 'Save File' dialog box.

When using these options, the APPX Server Connector stores the file in the mongo database, then passes the URL to the HTML client. The HTML client accesses the file from the mongo database. Once the file has been accessed, it is removed from the mongo database to manage storage. This means the link cannot be reused or the tab refreshed.

NOTES:

• $(pushAndOpen) and $(pushAndSave) are case senstive, you must use them exactly as shown.
• Although you can pass the destination name shared, you will not get a meaningful name back when using $(pushAndOpen) or $(pushAndSave).
• These options do not work with the APPX Desktop Client

Comments:

Read what other users have said about this page or add your own comments.

-- JeanNeron - 2012-01-31