• <GetStart>
  • CSPro User's Guide
    • The CSPro System
    • Data Dictionary Module
    • The CSPro Language
    • Data Entry Module
    • Batch Editing Applications
    • Tabulation Applications
    • Data Sources
    • CSPro Statements and Functions
    • Text Templates
    • Templated Reporting System
    • HTML, Markdown, and JavaScript Integration
    • Action Invoker
      • Overview
      • Execution Environments
      • Security, Resource Management, and Formatting Options
        • Access Token
        • Binary Data Representation
        • Resource IDs
      • Base Actions
      • Application Namespace
      • Clipboard Namespace
      • Data Namespace
      • Dictionary Namespace
      • File Namespace
      • Hash Namespace
      • Localhost Namespace
      • Logic Namespace
      • Message Namespace
      • Path Namespace
      • Settings Namespace
      • Sqlite Namespace
      • System Namespace
      • UI Namespace
    • Appendix
  • <CSEntry>
  • <CSBatch>
  • <CSTab>
  • <DataManager>
  • <TextView>
  • <TblView>
  • <CSFreq>
  • <CSDeploy>
  • <CSPack>
  • <CSDiff>
  • <CSConcat>
  • <Excel2CSPro>
  • <CSExport>
  • <CSIndex>
  • <CSReFmt>
  • <CSSort>
  • <ParadataConcat>
  • <ParadataViewer>
  • <CSCode>
  • <CSDocument>
  • <CSView>
  • <CSWeb>

Binary Data in the Action Invoker

The Action Invoker does not directly allow binary data as an input or return it as an output, so it uses routines to convert binary data to and from string representations.
Inputs: Converting a String to Binary Data
When specifying a format to describe binary data passed to the Action Invoker as an input, typically using the argument bytesFormat, there are six options, with the default option, if none is specified, as "autodetect":
  • "autodetect": When autodetecting the format, the binary data string's prefix is examined. If it begins with "data:", it is processed as if it were a data URL. If it begins with "cscache:", it is processed as if the bytes are stored in memory. If the prefix matches neither of those values, it is processed as if it were encoded as Base64.
  • "Base64": The binary data string represents bytes in Base64 format.
  • "cache": The binary data string represents bytes previously stored in memory when "cache" was used as the output format for binary data returned by another action. By default, once the bytes are accessed, they are cleared from the cache. If you want to keep the bytes in memory for future use, append "?clear=false" to the cache key.
  • "dataUrl": The binary data string contains a data URL.
  • "hex": The binary data string represents bytes in hexadecimal format.
  • "text": The binary data string contains text that is converted to bytes in its UTF-8 representation.
An exception is thrown if the input binary data string is not valid when using a data URL, a cache key, or hexadecimal characters.
Outputs: Returning Binary Data as a String
When specifying a format for the binary data that Action Invoker returns, there are five options, with the default option, if none is specified, as "dataUrl":
  • "Base64": The string returned represents bytes in Base64 format.
  • "cache": The bytes are stored in memory and the string returned contains a key that can be used by other actions to retrieve the bytes. This key is only valid as long as the application is running.
  • "dataUrl": The string returned contains a data URL.
  • "hex": The string returned represents bytes in hexadecimal format. The hexadecimal characters are returned in lowercase.
  • "localhostUrl": The string returned contains a localhost URL that can be used to access the binary data, served using a local web server. This URL is only valid as long as the application is running.
No exceptions are thrown while returning binary data.
Example
Here is the presentation of the text "Hello, World!" in the four direct input formats:
  • Base64: "SGVsbG8sIFdvcmxkIQ=="
  • Data URL: "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="
  • Hex: "48656c6c6f2c20576f726c6421"
  • Text: "Hello, World!"
Here is what the text may look like when returned as a format that is only valid when the application is running:
  • Cache: "cscache:819"
  • Localhost URL: "http://localhost:50505/vf/1"
See also: Data URL, Localhost URL