padValue

The "padValue" property is used by the server as a byte value to pad all "char" and "binary" fields in a table when the contents of these fixed-length fields is shorter than the field size. This property is an optional integer with a default of 32.

All fixed-length fields in a table are padded with the same pad value. 

Note Padding does not apply to the variable-length fields of the table, including "varchar", "lvarchar", "varbinary", and "lvarbinary".

Reasons to use fixed-length fields:
  • Fixed-length fields are an optimization for the specific use case of storing fixed-length data that matches the exact length of the field.
  • For fixed-length fields, the following use cases work well:
    • Bit flags
      • A "binary" field is useful for efficiently storing a fixed set of bit flags where each bit represents a different on/off setting.
    • Legacy identifiers
      • A "char" field is useful for efficiently storing legacy fixed-length identifiers, such as a VIN number, where characters in specific positions represent different subsets of data.
    • Very small strings
      • A "char" field is useful for efficiently storing strings that are smaller than six characters because they do not have the overhead of requiring two extra bytes to track the length of the field.
  • A fixed-length field is more efficient than a variable-length field because it does not require extra bytes to track the length of the field:
    • The "varchar" and "varbinary" fields require two extra bytes to track the length of the field, which can be up to 64K. 
    • The "lvarchar", "lvarchar",  and "lvarbinary" fields require four extra bytes to track the length of the field, which can be up to 2GB.
Reasons for padding fixed-length fields:
  • Padding is required for fixed-length fields because data can be assigned to a field with a shorter length than the field's length.
  • Padding is useful in the following use cases:
    • The padding value of 0 in a "char" field makes a fixed-length string behave like a variable-length string. It works because the database can treat a fixed-length string as a null-terminated string that can be smaller than the fixed width.
    • A padding value of 32 in a "char" field is the ASCII space character, which automatically left-aligns fixed-length strings.
    • The padding value of 0 in a "binary" field works for bit flags when zero is the desired default state of a bit. Otherwise, padding in a "binary" field is rarely a good thing because it alters the binary value.
How padding works:
  • When the server assigns a value to a "char" or "binary" field (which are fixed-length field types), it puts the value in the field starting on the left and uses the pad value to fill in any remaining bytes on the right.
  • In other words, when the number of bytes in a value being assigned to a "char" or "binary" field is less than the number of bytes in the field, the server fills in the remaining bytes with the pad value.
CHAR padding behavior:
  • The pad value of 0 causes a special padding behavior for "char" fields.
    • It causes the JSON DB API to treat fixed-length string fields as if they were variable-length strings with a maximum length.
    • In other words, the same string value going into a "char" field comes out the same, no padding is added — for example, when a table's "padValue" is set to 0 and a JSON string of "12" is inserted into a "char" field, the JSON string of "12" is returned from that field.
  • When you want the server to add padding to strings that are stored in a "char" field, set the "padValue" property to a non-zero number that is the ASCII character you want to pad the string.
    • For example, set "padValue" to 32 to pad strings with the space character. When a table's "padValue" is set to 32 and a JSON string of "12" is inserted into a "char" field with a "length" of 4 bytes, the JSON string of "12 " is returned from that field.
BINARY padding behavior:
  • The server always applies padding when the number of bytes in a binary value is less than the number of bytes in the fixed-length, "binary" field. When the server adds padding to a binary value, it permanently modifies the binary value. If this is not desirable, ensure the binary value exactly matches the size of the "binary" field.
  • The JSON DB API always returns the entire stored value of a "binary" field. This binary value is encoded as a JSON array of bytes or a string containing a base64 or hexadecimal representation of the binary value. The length of the JSON string encoded in base64 or hexadecimal is always longer than the length of the binary field.
  • If a table's "padValue" is set to 0, and a binary value of 0x3132 is stored in a "binary" field with a "length" of 4 bytes, the server pads the value and stores the value of 0x31320000 into the field. When the value is returned by the JSON DB API, it is returned as 0x31320000. Thus, padding alters a binary value when the value is smaller than the field. The default padding behavior of a "binary" field is different from the default padding behavior of a "char" field because the server can assume that an ASCII NULL padding value is a string terminator, but it cannot assume the same for a binary value.
Example 1. Turning off padding

If a table's "padValue" is set to 0, the ASCII NULL character with the hexadecimal value of 0x00 is used to pad unfilled byte positions. So when the JSON string "12" is inserted into a "char" field that has a "length" of 4 bytes, the binary value of 0x31320000 is stored in the field. The value returned is a JSON string of "12" because it recognizes the ASCII NULL character as a string terminator.

In other words, the ASCII NULL character allows the server to automatically trim the length of a string that is stored in a fixed-length field before it returns the string in JSON. So, by default, the same JSON string inserted into a "char" field is always returned by the JSON DB API. This behavior is safe for UTF-8 strings, which is the string encoding used by JSON.

 

Example 2. Padding s a string with spaces

When a table's "padValue" is set to 32, which is hexadecimal 0x20, and a JSON string of "12" is assigned to a "char" field that has a "length" of 4 bytes, the binary value of 0x31322020 is stored in the field. When the JSON DB API retrieves the value, it returns it as a JSON string of "12". This is because the value 32 is the ASCII space character " ".

 

Example 3. Padding a string with hyphens

If a table's "padValue" is set to 54, which is hexadecimal 0x36, and a JSON string of "12" is assigned to a "char" field that has a "length" of 4 bytes, the binary value of 0x31323636 is stored in the field. When the JSON DB API retrieves the value, it returns it as a JSON string of "12--". This is because the value 54 is the ASCII character "-".

 

Example 4. Manually padding a string

Assigning "12**" to a "char" field that has a "length" of 4 bytes stores "12**" into the field regardless of the table's "padValue".

 

Example 5. Right-aligning a value in a string

Assigning " $12.34" to a "char" field that has a "length" of 8 bytes stores " $12.34" into the field regardless of the table's "padValue".

 

Example 6. Avoiding padding

Use the variable-length char and binary field types ("varchar", "lvarchar", "lvarchar", "varbinary", and "lvarbinary"). 

Each of these field types is stored in the table with length information, so the data returned matches the data stored.

 

Request example

{
  "api": "db",
  "action": "createTable",
  "params": {
    "padValue": 32
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Was this article helpful?

Give feedback about this article

Related Articles