WriteColumnToFile

Definition:

WriteColumnToFile(filename, datasource, column)

 

Description:

Output a specified column in the current record for a specified Data Source to a local file on the mobile device.

 

Platforms:

Android, Universal Windows, Windows Desktop

 

Parameters:

filename - required

Specify the name of the file to output the column to. You must include the full path with the file name.

 

Specify one of the following values:

"" - Specify an empty string to allow the user to browse for and select the file to write to at runtime.

 

 

<filename> - Specify a file name without a path, e.g. MyFile.txt, to write to a file located within the default folder (see Notes below).

 

 

Documents\<subfolderpath>\<filename> - Specify the path and file name of a file located in the device's Documents library, or one of its subfolders, using this special format, e.g. Documents\MyApp\DataFiles\MyData.xlsx. This option requires permission to directly access the device's Documents library (see Notes below).

 

Specify the name of the file to output the column to.

If you include a fully qualified path name with the file name, the Client will use the specified folder, otherwise it will use a default folder (see Notes below).

 

 

datasource - required

Specifies the Data Source to which the file will be written – click here for the format of this parameter.

 

column - required

Name of the column to output to the file.

 

Returns:

nothing

 

Notes:

  • If the specified file doesn't already exist, it will be created.

  • If the file already exists the data string will literally be appended to the end of any existing content in the file.

  • You can use this Method to output binary data such as an image or pdf file.

  • If you want to overwrite an existing file instead of appending data to it, you can delete the existing file first using the DeleteFile Method.

From Android 11 onwards, changes to the Android Operating System affect the ability of your apps to access certain files and folders when calling WriteColumnToFile. This will only affect files and folders in shared storage outside the normal folders accessible to an individual app.

If you want your app to be able to access such files and folders, you will need to build a pre-configured Client or Standalone App which includes a request for permission to do so. This requires you to select the Allow All Files option under the Permissions tab within the pre-configured Client or Standalone App build request dialog box. Then, the first time a user runs the Client or Standalone App on a device, they will be asked to grant permission for the Client or app to access these files and folders. If the user grants permission, your Client or app will be able to access files and folders in shared storage outside its own folders. If the user refuses permission, your app will not be able to access these files and folders and calls to WriteColumnToFile involving such files or folders will fail silently. The user can always change their decision later within the device's Settings.

  • If you upgrade a device from an earlier version of Android to Android 11 or above, this change may cause a previously working app to fail. If, after upgrading, calls to WriteColumnToFile fail, try rebuilding (or building) your pre-configured Client or Standalone App with the Allow All Files option selected and upgrade your Client or Standalone App.
  • The Access All Files option will generally give your app access to files and folders which are held in shared storage on the device, but doesn't give unlimited access to all files and folders, e.g. it won't allow you to access files and folders held within another app's private storage.

 

Note the following:

  • If you specify an empty string as the parameter to this Method, the operating system controls which files the user can select and write to.

  • If you specify just a file name as the parameter to this Method, you can write to any file in the default folder. The default folder varies depending upon whether you are running the app within the Universal Windows Client or as a Standalone App:

    Digitise Apps Client:

    C:\Users\<user>\AppData\Local\Packages\<appGUID>\LocalCache\Applications\<appname>\docs

    Standalone App:

    C:\Users\<user>\AppData\Local\Packages\<appGUID>\LocalCache\<appname>\Applications\<appname>\docs

    where appGUID is a unique identifier assigned to an app by the operating system. You can recognise the relevant GUID for your app or Digitise Apps Client by looking for the app name within the GUID or, in the case of a Client, the GUID will contain 'MXUniversalClient' within it, e.g. a Digitise Apps Client GUID will look something like: com.ndl.mx.MxUniversalClient_1a2b3c4e5f6g7.

  • If you are creating a Standalone App and you want to directly access files in the device's Document library using this Method, you will need to turn on this capability within the build request to the Digitise Apps Build System. You do this by selecting the Access Documents Library option under the Permissions tab when configuring the Standalone App build request in App Studio. If you select Access Documents Library, you then need to create a list of file extensions determining which files in the Documents library the Scripting Methods are allowed to operate on.

    Note that when creating a store version of a Standalone App, selecting Access Documents Library affects the process by which you submit the app to the Store and requires you to justify your use of this option to Microsoft.

    For a pre-configured version of the Universal Windows Client, Access Documents Library is always selected and you only need to specify a list of file extensions, determining which files in the Documents library the Scripting Methods are allowed to operate on, under the File Extensions tab in the build request.

    You can only specify a file using the Documents\<subfolderpath>\<filename> format as a parameter to this Method if Access Documents Library is selected.

    However, the file specified can only be written to if its file extension is included in your list of file extensions in the build request. If you specify a file with an unlisted file extension the Method will fail silently.

    The standard NDL-signed Digitise Apps Client supplied in the Digitise Apps Product Download, has Access Documents Library disabled and cannot directly access files and folders in the Documents library.

 

If you omit the path from the file name specified in the filename parameter, the Method will use a default folder. The default folder varies depending upon whether you are running the app within the Windows Desktop Client or as a Standalone App:

Digitise Apps Client:

C:\Users\<user>\AppData\Roaming\ndl-metascybe\MXClient.2013\Applications\<appname>\docs

 

Standalone App:

C:\Users\<user>\AppData\Roaming\ndl-metascybe\MXClient.<appName>\Applications\<appName>\docs

 

See also:

DeleteFile