GUI_DOWNLOAD — GUI_DOWNLOAD Function Module for Frontend File Export
GUI_DOWNLOAD transfers the contents of an internal table from the application server to a file on the user's local workstation through the active SAP GUI connection. It is the de facto standard for ad hoc file export in custom ABAP programs, but it is not formally released for customer use, requires a live GUI session, and fails silently or with an exception in background processing.
Covers what GUI_DOWNLOAD actually does, which parameters and exceptions matter in practice, and the recurring mistakes that cause missing or corrupted files. Also covers why it keeps showing up in ATC clean-core findings and what replaces it going forward.
Published 16 Sept 2026· 1,154 words
What it does
GUI_DOWNLOAD writes the rows of an internal table to a file on the presentation server, meaning the workstation running the SAP GUI, not the application server's file system. It is used constantly in custom reports for 'export to Excel', 'export to text file', or building an ad hoc CSV for a business user. It is not part of any officially released public API set; SAP has never granted it release status for customer use, which matters for clean-core assessments even though the module has existed unchanged for decades and is used pervasively, including inside SAP's own standard programs. It only works when a real frontend is attached to the session: an interactive dialog user running SAP GUI for Windows, Java, or similar. RFC calls, background jobs, and headless sessions have no presentation server to write to.
Parameters
- FILENAME - full path and file name on the frontend workstation; a relative name without a drive or path is a common source of confusion about where the file actually lands.
- FILETYPE - 'ASC' for text, 'BIN' for binary, 'DAT' for a delimited format that respects WRITE_FIELD_SEPARATOR differently than 'ASC' does.
- APPEND - if set, appends to an existing file instead of overwriting it.
- WRITE_FIELD_SEPARATOR - character or flag controlling column separation for delimited export.
- TRUNC_TRAILING_BLANKS - strips trailing spaces from character fields before writing.
- CONFIRM_OVERWRITE - triggers a frontend prompt if the target file already exists; if not set, an existing file is overwritten without warning.
- CODEPAGE - character set used for the write; left blank, non-Latin text can come out corrupted.
- DATA_TAB - the tables parameter holding the internal table to export; this is the actual payload.
- FIELDNAMES - optional table of column headers written as the first line.
- FILELENGTH - export parameter returning the number of bytes written, useful for verifying a non-empty result.
Exceptions
- FILE_WRITE_ERROR - the frontend could not write to the path given, usually a permissions issue or a locked file already open in Excel; swallowing this leaves the caller believing export succeeded when no file exists.
- NO_BATCH - raised when the module is called with no GUI attached, most commonly from a background job; this is the single most common real-world failure and is often not checked, so the job finishes green with a missing file and nobody notices until someone asks for the export.
- GUI_REFUSE_FILETRANSFER - the SAP GUI security policy on the workstation blocked the file operation; this is a client-side security setting, not an ABAP bug, and retrying the same code changes nothing.
- INVALID_TYPE - an unsupported FILETYPE value was passed; almost always a typo or copy-paste from another program using a different type constant.
- NO_AUTHORITY - the user lacks authorization for the download action as configured by frontend security rules.
- UNKNOWN_ERROR - a catch-all; if this is swallowed the program has no way to tell the user anything useful went wrong.
- ERROR_NO_GUI / NOT_SUPPORTED_BY_GUI - the connected frontend does not support the requested operation, seen with non-Windows or restricted GUI variants.
How to call it safely
Call it only from a genuinely interactive session, and always populate the EXCEPTIONS addition rather than calling it bare. After the call, check sy-subrc explicitly and branch on it; do not assume a non-fatal return means the file exists, since some frontend-side failures surface as a non-zero subrc with a generic text rather than a specific exception. Where the target audience includes background execution, wrap the download logic behind a check on sy-batch or an explicit test for an active GUI, and route background scenarios to OPEN DATASET against the application server instead of trying to force GUI_DOWNLOAD to work there. If FILELENGTH comes back as zero after a subrc of zero, treat that as suspicious and verify DATA_TAB actually had rows before the call.
ECC vs S/4HANA
GUI_DOWNLOAD is not on SAP's released API list and is consistently flagged by ABAP Test Cockpit clean-core checks as a discouraged dependency for extensions intended to run in a restricted or cloud ABAP environment. It behaves identically on ECC and on-premise S/4HANA because the underlying mechanic, a SAP GUI presentation server, is unchanged. In ABAP environments without a classic SAP GUI frontend, such as steampunk-style cloud development, there is no equivalent presentation server to download to, so the module simply cannot be used and file export has to be designed around a different, browser-based delivery pattern instead of a direct successor function module.
Common pitfalls
- Calling GUI_DOWNLOAD inside a background job: raises NO_BATCH, and if the exception is not listed, the runtime error is easy to miss in a job log full of other output; the fix is never to force a GUI context onto batch, it is to redesign the output path for that scenario.
- Confusing presentation server paths with application server paths: FILENAME is a frontend path, not something on the app server; developers used to OPEN DATASET frequently pass a server-style path and get a file written to an unexpected local folder or a write error.
- Skipping CODEPAGE handling for non-Latin text and getting garbled output that looks like a data problem but is actually an encoding problem introduced at download time.
- Mixing FILETYPE 'ASC' with a field separator meant for 'DAT', producing a file that looks fine in a text editor but imports into Excel as a single column.
- Not setting CONFIRM_OVERWRITE and silently clobbering a file the user was still working in.
- Treating a zero sy-subrc as full success without checking FILELENGTH, missing the case where an empty internal table produced an empty file that satisfies no exception check.
Whose problem this is
This sits with the ABAP development team that wrote the calling program; there is no functional configuration behind it. Basis involvement is limited to frontend security policy, since GUI_REFUSE_FILETRANSFER and related failures trace back to SAP GUI security settings on the workstation or in the security rule file, not to anything in the ABAP stack itself.
Related SAP objects
Reviewed pages this object connects to in the ERPClimb knowledge graph.
Source: ERPClimb — https://erpclimb.com/sap-function-modules/gui-downloadERPClimb is an independent platform and is not affiliated with SAP SE. Reference pages are written and reviewed by SAP consultants for learning and troubleshooting.