jsonAction protocol

Standard message pattern for the JSON DB API

The JSON DB API uses a request-response pattern that works over any communications protocol. FairCom has implemented the JSON DB API to work over HTTP.

The typical message pattern is as follows:

The client logs into the server and creates a session using the JSON Admin API "createSession" action. The server sends back an Authorization Token called "authToken" that unique identifies the session. The client includes this information in all subsequent messages to the server so the server can authorize client requests.
The client sends request messages to the FairCom server.
The server returns response messages to the client.

Essential information:

All messages are encoded as JSON.
All JSON Action API action names are case-insensitive.
The structure of each message follows the design specified by jsonAction specification.
Note
The jsonAction specification allows additional properties to be added by an API. FairCom has added additional properties where they are needed. For example, "responseOptions" supports new "includeFields" and "excludeFields" properties that include and exclude database fields from query results.
To support asynchronous communication, such as WebSocket and MQTT:
- The client adds a unique "requestId" property to each request message to allow the client to match a request to a response. The client can assign any JSON value to "requestId" and the server includes the "requestId" and its value in the response message.
- A client can create multiple sessions with the server to process multiple requests in parallel. A client application can use the combination of "authToken" and "requestId" to uniquely identify each message.
FairCom's JSON APIs are stateful because a stateful connection is necessary for data processing tasks, such as retrieving the next set of data from a query or running another step in an ACID transaction.

jsonAction API standard message pattern

jsonAction API

standard message pattern

JSON action API

HTTP

jsonAction request

List of properties in jsonAction request messages

The following properties are part of each jsonAction request message. All are optional except for "action", and "params". APIs often take advantage of the optional properties to implement advanced features.

Example

{
  "requestId": "1",

  "api": "someApi",
  "apiVersion": "1.0",
  "action": "someAction",
  "params": {},

  "responseOptions":
  {
    "binaryFormat":   "hex",
    "dataFormat":     "objects",
    "numberFormat":   "string",
    "includeFields":  [],
    "excludeFields":  [],
    "includePaths":   [],
    "excludePaths":   []
  },
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Properties summary

Table 1. Request message property summaries

Property

Description

Default

Type

Limits (inclusive)

action

contains the name of a remote procedure call that the server can execute

Required - No default value

string

api

(optional) contains the name of an API

""

string

"admin"

"db"

"hub"

"mq"

"transform"

apiVersion

(optional) specifies the major, minor, and patch versions of the API

Latest version of the API

string

0 to 12 bytes

authToken

signifies that the client is authenticated and authorized

Required - No default value

Note

Optional for "pingSession" and "createSession" and defaults to "".

string

0 to 225 bytes

debug

(optional) contains the settings for returning any extra debug information

"none"

string

"none"

"max"

params

(optional) contains the parameters to an action

{}

object

responseOptions

(optional) configures the server to return a customized response

{}

object

responseOptions

.binaryFormat

(optional) specifies how binary values are returned

"base64"

string

One of the following: "base64", "hex", or "byteArray".

responseOptions

.dataFormat

(optional) specifies what format the results will be returned in

"arrays"

string

"default"

"arrays"

"objects"

responseOptions

.excludeFields

(optional) specifies which fields are excluded in the response message

[]

Note

When the array is empty or the property is not specified, the "includeFields" behavior applies

array

responseOptions

.includeFields

(optional) specifies which fields are returned in the response message

[]

Note

When the array is empty or the property is not specified, all fields are returned

array

responseOptions

.numberFormat

(optional) specifies how numbers are formatted in the JSON response message

"number"

string

"number"

"string"

requestId

(optional) contains any JSON value to identify a message as assigned by the client

null

string

number

object

array

Boolean

null

`"responseOptions"`

The "responseOptions" property is an optional object that configures the server to return a customized response.

Essential information:

None of these properties are required, but some are mutually exclusive:
- "includeFields" and "excludeFields" are mutually exclusive.
  Use "includeFields" or "excludeFields" to control which record fields are present in the data.
Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
Use "binaryFormat" to control how binary data is embedded in JSON strings.
Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.

`"binaryFormat"`

The "binaryFormat" property designates how binary values are formatted in the JSON request and JSON response message. The default value is "base64".

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , and "result".
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"dataFormat"`

The "dataFormat" property is an optional, case-insensitive string enum. It defines the format of data being sent to the server. "autoDetect" is the default value.

Note

There are two different-but-similar versions of the "dataFormat" property. One version occurs in a request and another occurs in a response.

Possible values:

"arrays"
This causes the server to return results as an array of arrays, which is most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"autoDetect"
This causes the server to automatically detect the format of the data in the "sourceData" property. This is the default.
Omitted or set to null
This defaults to "autoDetect", which causes the server to automatically detect the format of the data in the "sourceData" property.

`"numberFormat"`

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers returned in a response. "number" is the default value.

Possible values:

"number"
This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
This is most efficient.
JSON represents numbers are base-ten numbers that may have any number of digits.
Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
"string"
This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
This is slightly less efficient because it includes two extra double quote characters
Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
Omitted or set to null
This defaults to "number".

List of properties in jsonAction request messages

jsonAction API

request message properties

jsonAction request

JSON DB API

`"action"`

The "action" property is a required, case-insensitive string enum. It is the name of a remote procedure call that the server can execute. It is required by the jsonAction standard.

Possible values depend on the API being used, for a complete list of "actions" see:

`"api"`

The "api" property is an optional, case-insensitive string enum that contains the name of an API. An API can execute one or more actions. It defaults to whatever API is being used.

Possible values:

"db"
Note
For JSON DB API "api" is always "db".
"mq"
"hub"
"admin"

`"apiVersion"`

The "apiVersion" property is returned by the server. It is always the entire version number of the JSON DB API for troubleshooting.

Essential information

"apiVersion" specifies the major, minor, and patch versions of an API.
Examples include "3", "3.1" , and "3.1.23" .
The number to the left of the decimal point is the major API version.
The middle number is the minor API version, which is required only when a patch number is included.
The rightmost number is an optional patch number.

`"authToken"`

The "authToken" property signifies that the client is authenticated and authorized. It is required except in "pingSession" and "createSession". For "pingSession" and "createSession" it defaults to an empty string.

The server generates a unique authentication token in response to "createSession". Clients must include it in all subsequent requests. If the client does not supply a valid "authToken", the server returns error 12031.

You can create a permanent "authToken" by setting the "permanentSession" property to true when you create a session. A permanent "authToken" works like an API key and does not expire.

`"debug"`

The "debug" property is an optional, case-insensitive string enum that causes the server to return debug information. The default value is "none" which is equivalent to omitting this property or similar to setting it to null.

Essential information

Possible values:
- "none"
- "max"
Setting the "debug" value to anything other than "none" causes the server to pretty-print the JSON that it returns making it easier to troubleshoot.
Setting to "max" causes the server to return a response that includes the maximum amount of extra debug information in the response making it useful for troubleshooting live production data with minimal impact on server resources.
Setting to "none" cause no debug information to be returned which is useful for production environments that are running well.

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

`"requestId"`

The "requestId" property is typically a string or integer but can contain any JSON value that is an identifier assigned by the client. It is optional and defaults to null.

Essential information

"requestId" can contain any JSON value including:
- object
- array
- string
- integer
- Boolean
- null
From the client's perspective, "requestId" uniquely identifies a message where the server returns this identifier to the client in its response message. This allows a client to match a request to a response.
It is particularly useful when a client runs JSON DB API over an asynchronous protocol, such as MQTT or WebSocket.
It can be omitted or set to a zero-length string when the client does not need it.

jsonAction response

List of properties in jsonAction response messages

The following properties are part of each jsonAction response message. All are optional except for "result", "errorCode", and "errorMessage". APIs often take advantage of the optional properties to implement advanced features.

Example

{
  "requestId": "1",
  "result": {},
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo":
  {
    "request":
    {
      "requestId": "1",

      "action": "someAction",
      "params": {},

      "api": "someApi",
      "apiVersion": "1.0",

      "responseOptions": { },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {},
    "errorData": {},
    "warnings": [ { "warningCode": 0, "warningMessage": "", "warningData": {} } ],
    "executionPlan": {}
  }
}

Property summary

Table 2. Response message property summaries

Property

Description

Type

Limits (inclusive)

debugInfo

contains troubleshooting information about a request and its response

object

debugInfo

.errorData

contains data about an error

object

debugInfo

.executionPlan

contains data about the execution of a query

object

debugInfo

.request

contains all properties that can be included in an request

object

debugInfo

.serverSuppliedValues

contains zero or more properties set by the server to default values

object

debugInfo

.warnings

contains a warning object for each warning the server wants to communicate to the client

array of objects

errorCode

indicates an error when set to a non-zero integer or success when 0

integer

-2,147,483,648 to 2,147,483,647

errorMessage

contains a human-readable error message

string

0 to 256 bytes

requestId

contains any JSON value to identify a message as assigned by the client

string

number

object

array

Boolean

null

result

contains the result of an action

object

jsonAction API response message properties

jsonAction API

response message properties

jsonAction response

JSON DB API

`"debugInfo"`

The "debugInfo" property is an optional, case insensitive string enum that causes the server to return no, a minimal, or a maximum amount of debug information in the response message. The default value is "none". The JSON is pretty printed for readability except when set to "none".

Possible values:

"none"
This is the equivalent to omitting the "debug" property or setting to null.
"min"
This causes the server to return a minimal amount of extra debugging information in the response message.
"max"
This causes the server to return a maximum amount of debugging information in the response message which is useful for deep troubleshooting but requires significant computational power and resources for the server to generate this information. It is typically used during development and QA.

"debugInfo": {
    "request": {
      "schema": "faircom.com/schemas/db/v1",
      "requestId": "1",
      "authToken": "1234serverSuppliedAuthToken64Bytes1234",
      "api": "db",
      "apiVersion": "1.0",
      "action": "actionName",
      "params": {},
      "responseOptions": {},
      "debug": "max"
    },
    "serverSuppliedValues": {},
    "errorData": {},
    "warnings": [
      {
        "warningCode": 0,
        "warningMessage": "",
        "warningData": {}
      }
    ],
    "executionPlan": {}
  }

`"errorData"`

The "errorData" property is an object that may contain additional properties. If there is data about an error it is placed in the "errorData" property.

Essential information

If there is no additional data, it is an empty object.
It is always an object.
Its properties may vary depending on the api, action, and error message.

`"request"`

The "request" property contains the original values submitted in the request. It is included when the "debug" property is set to "max". See jsonAction request.

`"warnings"`

The "warnings" property is an optional array of warning objects. It contains one warning object for each warning the server want to communicated to the client.

Table 245. "warnings" property summaries

Property

Description

Type

Limits (inclusive)

"warningCode"

contains a positive or negative integer, non-zero number when there is a warning, contains a 0 when there is no warning

integer

-2,147,483,648 - 2,147,483,647

"warningData"

contains data about an error

object

"warningMessage"

contains a human-readable error message

string

Minimum length: 0

Maximum length: 64

`"errorCode"`

The "errorCode" property occurs only in a response message. It is a signed integer from -2,147,483,648 to 2,147,483,647. A non-zero value indicates an error.

Essential information

When there is no error the value is 0.
When there is an error, it contains a non-zero integer number that uniquely identifies the cause of the error.
FairCom's error codes are listed in the error code reference.

Error codes

Table 4. Error codes from -32768 to -32000 are assigned specific meanings by the jsonAction specification

error.code	error.message	error.meaning
-32700	Parse error	This indicates an error occurred on the server while parsing the request.
-32600	Invalid request	This indicates the request message does not match the requirements of the specified version of the API.
-32601	Method not found	This indicates the action does not exist or is not available.
-32602	Invalid params	This indicates invalid action parameter(s). It occurs when a required property is missing or when an unexpected property is in the message.
-32603	Internal error	This indicates a unexpected jsonAction error.
-32000 through -32099	Server error	These are reserved for future jsonAction errors.

`"errorMessage"`

The "errorMessage" property is a string set by the server. It contains a human-readable error message.

Essential information

It is a zero-length string when there is no error.
It is a non-zero-length string that describes the error.
Look for a non-zero value in the "errorCode" property to know when there is an error.

`"requestId"`

The "requestId" property is typically a string or integer but can contain any JSON value that is an identifier assigned by the client. It is optional and defaults to null.

Essential information

"requestId" can contain any JSON value including:
- object
- array
- string
- integer
- Boolean
- null
From the client's perspective, "requestId" uniquely identifies a message where the server returns this identifier to the client in its response message. This allows a client to match a request to a response.
It is particularly useful when a client runs JSON DB API over an asynchronous protocol, such as MQTT or WebSocket.
It can be omitted or set to a zero-length string when the client does not need it.

`"result"`

The "result" property is a required object set by the server that contains the result of an action.

Essential information:

It is a required part of the jsonAction specification standard.
Its properties vary with each action.

{
  "authToken": "anAuthorizationTokenFromTheServer",
  "requestId": "1",
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "hexadecimal",
    "fields": 
    [
      {
        "name": "id",
        "type": "bigint",
        "length": null,
        "scale": null,
        "autoTimestamp": "none",
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 1
      },
      {
        "name": "name",
        "type": "varchar",
        "length": 30,
        "scale": null,
        "autoTimestamp": "none",
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0
      },
      {
        "name": "birthDate",
        "type": "date",
        "length": null,
        "scale": null,
        "autoTimestamp": "none",
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0
      },
      {
        "name": "favoriteSaying",
        "type": "varchar",
        "length": 500,
        "scale": null,
        "autoTimestamp": "none",
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0
      }
    ],
    "data": [
      {
        "id": 1,
        "name": "Michael Jordan",
        "birthDate": "1963-02-17",
        "favoriteSaying": "There is no 'i' in team but there is in win."
      },
      {
        "id": 2,
        "name": "Babe Ruth",
        "birthDate": "1895-02-06",
        "favoriteSaying": "Every strike brings me closer to the next home run."
      }
    ],
    "requestedRecordCount": 20,
    "returnedRecordCount": 6,
    "totalRecordCount": 6
  },
  "errorCode": 0,
  "errorMessage": ""
}

System limits

Limits of FairCom DB attributes

FairCom JSON API actions use required and optional parameters to complete specific operations. The following table shows the limits of these parameters.

Table 5. System attribute limits

Attribute	Description	Limits
disk read/write	Size of disk reads and writes	Limited on Windows
file ID	The file ID number	1 to 4294963200
file size	Size of a file	1 to 16 Exabytes
fixed-length record	Size of a fixed length record.	1 to 64KB
group	Number of users in a group	0 to 16 per user
indices	Number of indices per data file.	0 to 64 (default)
memory files	Memory file limitations	See Memory File Limitations
open files	Number of concurrently opened files	1 to 32767
password	Password limitations	1 to 64 bytes
records per file	Number of records per file	No limit
segments	Number of segments per index	1 to 16 (default)
SQL CHECK constraint clause	Length of a FairCom DB SQL CHECK constraint clause	20000 bytes
SQL column (NATIONAL CHARACTER)	Length of a FairCom DB SQL column for VARBINARY and VARCHAR specifying the character set designated as NATIONAL CHARACTER	1 to 3275 bytes
SQL column (standard)	Length of a FairCom DB SQL column for standard data types.	0 to 65500 bytes
SQL connection string	Length of a FairCom DB SQL connection string	0 to 100 bytes
SQL default value	FairCom DB SQL default value specification	0 to 8192 bytes
SQL error message	Length of a FairCom DB SQL error message	0 to 511 bytes
SQL identifier	Length of a FairCom DB SQL identifier	1 to 64 bytes
SQL nesting levels	Number of FairCom DB SQL nesting levels for view references	0 to 25
SQL procedure arguments	Number of arguments in a FairCom DB SQL CALL statement	0 to 50
SQL recursion level	Number of FairCom DB SQL recursion levels for stored procedures	0 to 10
SQL statement input parameters	Number of input parameters in a FairCom DB SQL statement	0 to 512
SQL statement length	Length of a FairCom DB SQL statement	1 to 32MB (prior to V10.2, the limit was 35,000 characters)
SQL statement nesting levels	Number of nesting levels in a FairCom DB SQL statement	0 to 25
SQL statement outer references	Number of or outer references in a FairCom DB SQL statement	0 to 25
SQL statement table references	Number of table references in a FairCom DB SQL statement	1 to 250
SQL storage attribute	Length of a FairCom DB storage_attribute	1 to 2000 bytes
SQL table check constraints	Number of check constraints in a FairCom DB SQL table	0 to 4000
SQL table columns	Number of FairCom DB columns in a SQL table	1 to 2500
SQL table foreign constraints	Number of foreign constraints in a FairCom DB SQL table	0 to 4000
SQL table index components	Number of index components for all indexes on a FairCom DB SQL table	0 to 2048 (configurable)
SQL view definition	Length of a FairCom DB SQL view definition	1 to 65000 bytes
table name	Length of a table name	1 to 64 bytes
UNIFRMAT	Support for UNIFRMAT files	Available only for non-transaction processed files.
user name	Length of a FairCom DB user name	1 to 31 bytes POSIX standard
variable-length record	Size of a variable length record	1 to 2GB

Disk reads/writes

A large variable-length record read or write operation could fail with Windows error 1450. To avoid this Windows error see Enforce Maximum Disk Read/Write Sizes on Windows to set the maximum read/write size.

File ID

The file ID number of a transaction-controlled file is incremented each time the file is opened. If error 534, Pending File ID overflow: 534 is written to CTSTATUS.FCS see File ID Overflow.

File size

The file size limit is 16 Exabytes (18 million terabytes). See File Size and Operating System Limits for more information.

Group

The System Administrator can create one or more Groups. Each group is assigned a unique Group ID that is a 32-byte ASCIIZ string.

To provide a convenient way for users with related needs to share information, each user is assigned membership in one to 16 groups. The Administrator adds the groups to the system and assigns users to them. Each user has a default group, which counts as one of the user’s 16 groups. If a user is not assigned to a group, the user’s default group is the GUEST group.

When an application program logs on to the FairCom Server with one of the extended functions, it sends a User ID and user password to the FairCom Server. Logging on with one of the equivalent standard functions or sending a NULL User ID with one of the extended functions automatically assigns the User ID of GUEST and membership in the GUEST group. If a User ID or password that does not exist is sent, the initiating call to the FairCom Server returns an error code and the program is not connected to the FairCom Server.

Indice

The indice limit defaults to 64 but can be increased using MAX_DAT_KEY in ctsrvr.cfg to a theoretical limit of 32767, although a practical limit exists well before this value.

Password

Each User can have an optional user password. The password limit is 64 bytes. For more information about passwords, see Automatically Enforce Password Strength.

Segment

The segment limit defaults to 16 but can be increased using MAX_KEY_SEG in ctsrvr.cfg to a theoretical limit of 32767, although a practical limit exists well before this value.

SQL Table index component

The limits of the table index components are configurable in ctsrvr.cfg by MAX_DAT_KEY (default 64) and MAX_KEY_SEG (default 32).

Table name

Table names must meet the following requirements:

Must be 64 bytes or less in length

Must start with an upper or lowercase letter

Must not contain special characters other than underscore "_"

Can include a mix of upper-lower case characters but are treated as case-insensitive.

Actions that take a “tableName” will return an Error 4054 if the table name does not meet these requirements.

UNIFRMAT

UNIFRMAT support is only available for non-transaction processed files. See Limitations for more information.

User

A user name, user ID, or account name is a 32-byte null-terminated ASCII string, which implies 31 bytes are available. The following characters are allowed in the name:

ABCDEFGHIJKLMNOPQRSTUVWXYZ

abcdefghijklmnopqrstuvwxyz

0123456789

._-

A hyphen character (-) cannot be used as the first character.

The server ignores the case of the ASCII characters. Therefore, the server considers TEST_1.FairCom-4 to be the same as test_1.faircom-4.

Note

FairCom based these limitations on the POSIX standard for the Portable Filename Character Set.

`"responseOptions"`

The "responseOptions" property is an optional object that configures the server to return a customized response.

Essential information:

An API may add additional properties to "responseOptions".
jsonAction APIs should implement the "binaryFormat" and "numberFormat" properties because JSON does not support binary data and JSON parsers often do not adequately handle large numbers.
Use "binaryFormat" to control how binary data is embedded in JSON strings.
Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
Use "omit" to remove a property from a response, such as omitting "errorMessage".

Table 6. "responseOptions" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

"base64"

string

One of the following: "base64", "hex", or "byteArray".

numberFormat

specifies how numbers are formatted in the JSON response message

"number"

string

"number"

"string"

omit

specifies which properties are excluded in the response message

{}

object

`"binaryFormat"`

The "binaryFormat" property designates how binary values are formatted in the JSON request and JSON response message. The default value is "base64".

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , and "result".
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"numberFormat"`

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers returned in a response. "number" is the default value.

Tip

Returning numbers embedded in strings puts your application in charge of how numbers are processed. It ensures JSON parsers and programming languages will not convert numbers to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors.

Possible values:

"number"
- This setting is most efficient because it causes the server to return numeric values as JSON numbers, such as -1.23 .
- JSON numbers are base-ten numbers that may have any number of digits. Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript. This is because they use IEEE floating point numbers, which have binary rounding errors and a limited range.
"string"
- This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
- This is slightly less efficient because it includes two extra double quote characters.
When omitted or set to null, numberFormat defaults to "number".

`"omit"`

The "omit" property is an optional array or strings that contain the name of a JSON property (not a JSON path) that the server should omit from the JSON response. It allows a client to remove jsonAction properties from a response that it does not want.

Things to know:

"omit" reduces the amount of data transferred from server to client and minimizes parsing overhead.
Top-level jsonAction properties can be removed by simply including the property name in the array, such as "errorMessage".
jsonAction properties inside "debugInfo" can be removed by referencing their JSON path, such as "debugInfo.request" and "debugInfo.warnings".
Properties inside "result" can be removed by referencing their JSON path — for example, if an API returns an "extraData" property in "result", it can be removed by specifying "omit": [ "result.extraData" ].
A server requires processing to remove properties from a response; thus, the processing cost of removing properties should be weighed against the network cost of transmitting properties.