listDatabases

JSON DB "listDatabases" action retrieves all databases on the server

The "listDatabases" action retrieves databases on the server. You can optionally filter which databases are returned by specifying a complete or partial database name. By default, the results are sorted in ascending order.

 

Request examples

Minimal

{
    "action": "listDatabases",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api": "db",
  "action": "listDatabases",
  "params": {
    "partialDatabaseName": "ctr",
    "skipRecords": 0,
    "maxRecords": 20,
    "transactionId": null
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "apiVersion": "1.0",
  "requestId": "00000010",
  "debug": "max"
}
 
 

 

Response examples

Minimal

{
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "databaseName",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "path",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "uid",
        "type": "bigint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "databaseName": "ctreeSQL",
        "path": ".\\ctreeSQL.dbs\\SQL_SYS",
        "uid": 999
      },
      {
        "databaseName": "faircom",
        "path": ".\\faircom.dbs\\SQL_SYS",
        "uid": 1001
      }
    ]
  },
  "requestId": "1",
  "debugInfo": {
    "request": {
      "action": "listDatabases",
      "requestId": "1",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "databaseName",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "path",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "uid",
        "type": "bigint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "databaseName": "ctreeSQL",
        "path": ".\\ctreeSQL.dbs\\SQL_SYS",
        "uid": 999
      }
    ]
  },
  "requestId": "00000010",
  "debugInfo": {
    "request": {
      "authToken": "replaceWithAuthTokenFromCreateSession",
      "api": "db",
      "action": "listDatabases",
      "params": {
        "partialDatabaseName": "ctr",
        "skipRecords": 0,
        "maxRecords": 20,
        "transactionId": null
      },
      "apiVersion": "1.0",
      "requestId": "00000010",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string"
      },
      "debug": "max"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

maxRecords

 The "maxRecords" property specifies the maximum number of records to be returned. It is used with "skipRecords" to paginate the results. If the value is not null or omitted, the server returns the maximum number of results specified by "maxRecords". Optional with default of 20 integer -1 to 65535

partialDatabaseName

The "partialDatabaseName" property filters the returned databases by applying partial matches to the beginning of database names. 

  • The "listDatabases" action returns databases with names that match the beginning of this string.
  • A zero-length string matches all database names.
  • Since it defaults to an empty string you can omit the "partialDatabaseName" property to return all databases.
 Optional with default of "" string 0 to 64 bytes

skipRecords

 The "skipRecords" property specifies the number of records to skip over when paginating the results. It is used with "maxRecords" to paginate the results. If the value is not null or omitted, the server returns results from the beginning. If it is > 0, the server skips over the specified number of records and returns results starting from that point up until it returns the maximum number of results as defined by "maxRecords". Optional with default of 0 integer 0 to 9223372036854775807

transactionId

 The "transactionId" property identifies a transaction in which the specified action will be included. Optional with default of "" string 0 to 255 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

 The "data" property specifies an array or object that the server returns, such as records returned by a query. It is an empty array when no results are available. array Its contents are determined by the action

dataFormat

The "dataFormat" property defines the format of the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

  • "dataFormat" in the response shows the client how the server formatted the "data" property.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
 string "autoDetect"
"arrays"
"objects"

fields

 The "fields" property specifies an array of objects set by the server, where each object is the definition of a field in a table defining the details of each field returned by a query. array

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

fields

.autoValue

 The "autoValue" property specifies when and how the server automatically sets the field value. See  for more details. string "none"
"incrementOnInsert"
"timestampOnInser"
"timestampOnUpdate"
"timestampOnUpdateAndInsert"
"changeid"

fields

.defaultValue

 The "defaultValue" property specifies the default value of a field. It is used when a record is inserted without specifying a value for the field. The server coerces the string value into the proper field type. string 0 to 65,500 bytes

fields

.length

 The "length" property specifies the length of a field's value in a record. integer 1 to 65500

fields

.name

 The "name" property specifies the new name of the field. string 0 to 64 bytes

fields

.nullable

 The "nullable" property allows a field to contain a NULL value when true. Boolean true
false

fields

.primaryKey

 The "primaryKey" property adds a field to the specified ordinal position of the table's primary key when > 0. integer 0 to 32

fields

.scale

 The "scale" property specifies the number of places to the right of the decimal point for "number" and "money" type fields. integer 0 to 32

fields

.type

 Identifies the type of the field. See Data types. string "bit"
"tinyint"
"smallint"
"integer"
"bigint"
"real"
"float"
"number"
"money"
"date"
"time"
"timestamp"
"char"
"varchar"
"lvarchar"
"binary"
"varbinary"
"lvarbinary"
"json"

 

Was this article helpful?

Give feedback about this article

Related Articles