ASCIIOutput

ASCIIOutput writes a comma-delimited record to an ASCII file.

This function is valid in TM1® TurboIntegrator processes only.

The ASCII file is opened when the first record is written, and is closed when the TurboIntegrator procedure (Prolog, Metadata, Data, or Epilog) containing the ASCIIIOutput function finishes processing.

When using this function on Planning Analytics Engine, byte order marks are not written to the output file.

Each output record generated by ASCIIOutput is limited to 64 kilobytes. If an output record exceeds 64 kilobytes, the record is truncated and a warning is logged in the TM1ProcessError.log file.

When ASCIIOutput encounters a String argument that pushes the output record beyond the 64 kilobyte limit, it ignores that argument and any further arguments. For example, if there are 10 String arguments and output for the first seven arguments total 65,500 bytes (just under the 64 KB limit) while the output for the eighth argument is 50 bytes, only the output for the first seven arguments will be written to the record, as the eighth argument causes the output to exceed the 64 kilobyte limit. If there are ten String arguments and the first argument is over 64 kilobytes, no output is written to the record.

If you use the ASCIIOutput function to write to the same file in multiple procedures (tabs) of a TurboIntegrator process, the file will be overwritten each time it is opened for a new procedure.

The ASCIIOutput function generates a minor error if an error occurs while writing the ASCII file. In addition, the function returns a value upon execution: 1 if the function successfully writes the ASCII file and 0 on failure.

Note: The error will be generated and the value returned only when ASCIIOutput is writing to a disk other than the one that the server is running on. For example, if the server is running on the C: drive and ASCIIOutput is writing to the F: drive, and the F: drive runs out of space, the error will be trapped and the server remains alive. If the server is running on the C: drive while ASCIIOutput is also writing to the C: drive, and that drive runs out of space, the server will terminate (as expected).
Note: The ability to execute the ASCIIOutput function when the data source is a cube view is determined by the Allow Export as Text capability assignment, which is set per user group. If a user is a member of a group which is denied the ability to export data as text, any attempt by the user to execute ASCIIOutput results in the process exiting with a permission error. The process message log indicates Execution was aborted. No security access for ASCIIOutput.

For details on how the Allow Export as Text capability is set, see Capability Assignments in TM1 Operations.

Note: The ASCIIOutput function places the 0x1A hexadecimal character at the end of all generated files. However, TM1 Web cannot open a Websheet that contains the 0x1A hexadecimal character.

If you use ASCIIOutput to export TM1 data to an ASCII file and then attempt to open the file in a TM1 Websheet, you will encounter the following error.

Error occurred while converting the MS Excel workbook into XML format, hexadecimal value 0x1A is an invalid character.

If you remove the 0x1A hexadecimal character from the Websheet, the file will open in TM1 Web.

Syntax

ASCIIOutput(FileName, String1, String2, ...Stringn);

Argument

Description

FileName

A full path to the ASCII file to which you want to write the record. Path must include a file extension.

When using this function on Planning Analytics Engine, the file must reside in the Planning Analytics Engine content directory or its child directories.

String1...Stringn

A string that corresponds to each field you want to create in the ASCII file. This argument can be a string or a TurboIntegrator variable for a string.

Example

This example writes a record to the NewCube.cma ASCII file. Each field in the record corresponds to a variable assigned by TurboIntegrator to a column in your data source. 

ASCIIOutput('NewCube.cma', V1, V2, V3, V4, V5 );