Skip to main content

"stringFormat"

The "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

Options

"json" (default)

  • Returns "char", "varchar", "lvarchar", and "variant" string values as hexadecimal numbers embedded as JSON strings, such as "6d7920737472696e67".

  • Returns the raw binary value stored in the field, encoded as a hexadecimal.

  • Always twice the length of the original string.

  • Useful for returning legacy values that are incompatible with UTF-8 so they can be fixed.

  • When the "stringFormat" property is "hex", the API ignores the setting of "fixedLengthCharFormat" because it returns the field's raw value.  It includes pad characters in the hex dump. For example, "value     " in a char(10) field returns "76616c75652020202020".

  • When "variantFormat" is "string" or "json", a variant field returns binary values embedded in a string, such as "6d7920737472696e67". It also returns normal string values stored in a variant as a string, such as "my string". The application cannot reliably determine when a string is normal or contains embedded hexadecimal characters.

    • This setting forces all variant string values to be encoded as hexadecimal, making decoding string values predictable.

    • It overrides "binaryFormat" and always encodes variant strings as hexadecimal.

    • It removes the need to encode strings with JSON escape characters, such as \\ and \n.

      • For example, this setting causes a variant value stored as "my string" to be returned as "6D7920737472696E67".

Example

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "athlete"
  },
  "responseOptions": {
    "stringFormat": "hex",
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "variantFormat": "variantObject"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Implementation steps

  • Add the "stringFormat" property to the "responseOptions" property for all "getRecords…" actions except for "getRecordsUsingSql".

  • Add the "stringFormat" property to the "defaultResponseOptions" property in the "createSession" and "alterSession" actions.

    • It defines the default value for the "stringFormat" property for "getRecords…" actions.

  • Add the "stringFormat" property to services.json under the "jsonActionApiDefaults"."defaultResponseOptions" properties.

    • It defines the default value for the "stringFormat" property for all sessions.