Skip to main content

"listTransactions" (JSON Action)

JSON DB "listTransactions" action returns a list of all active transactions in your current session

Note

The "authToken" property identifies the current session.

  • This action can be used to troubleshoot issues with transactions, such as an application creating multiple sessions and accidentally using the wrong transaction ID with the wrong session.

  • This action does not support pagination because the number of active transactions in a session is unlikely to grow larger than a few transactions.

  • If the logged-in account has administrative privileges, "listTransactions" returns all transactions.

  • The list can be filtered by the "username" property to include transactions only from specific sessions.

Request examples

Minimal

{
  "api": "db",
  "action": "listTransactions",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api": "db",
  "action": "listTransactions",
  "params": {},
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "includeFields": [],
    "excludeFields": []
  },
  "apiVersion": "1.0",
  "requestId": "2",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Success

{
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "authToken",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "username",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "transactionId",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "transactionDescription",
        "type": "varchar",
        "length": 255,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "transactionDescription": "",
        "transactionId": "transactionId1",
        "username": "ADMIN",
        "authToken": "replaceWithAuthTokenFromCreateSession"
      },
      {
        "transactionDescription": "user supplied description of a transaction",
        "transactionId": "transactionId12",
        "username": "ADMIN",
        "authToken": "replaceWithAuthTokenFromCreateSession"
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal response

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "authToken",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "username",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "transactionId",
        "type": "varchar",
        "length": 64,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "transactionDescription",
        "type": "varchar",
        "length": 255,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": []
  },
  "requestId": "00000005",
  "debugInfo": {
    "request": {
      "authToken": "replaceWithAuthTokenFromCreateSession",
      "api": "db",
      "action": "listTransactions",
      "params": {},
      "apiVersion": "1.0",
      "requestId": "00000005",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string",
        "includeFields": [],
        "excludeFields": []
      },
      "debug": "max"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": ""
}

Use the listTransactions JSON API action to return a list of all active transactions that the logged-in account is authorized to see

API actionsJSON DB APIJSON Actiontransaction actionslist transactionslistTransactions

"result"

Table 1. "result" properties summary

Property

Description

Type

Limits (inclusive)

data

is an array of objects or arrays. Each item in the array describes a record. The array is empty if no results are available.

array

The action determines its contents.

dataFormat

identifies the format of the data in the "data" property.

string

"autoDetect"
"arrays"
"objects"

fields

is an array of objects, one for each field. Each object contains the field's characteristics.

array

fields
.autoValue

controls when and how the server automatically sets the field value.

string

"incrementOnInsert"
"none"
"timestampOnInsert"
"timestampOnUpdate"
"timestampOnUpdateAndInsert"
"changeid"
fields
.defaultValue

specifies the default value of a field.

string

0 to 65,500 bytes

fields
.length

specifies the length of a field's value in a record.

integer

1 to 65500

fields
.name

specifies a new name of the field.

string

0 to 64 bytes

fields
.nullable

allows a field to contain a NULL value when true.

Boolean

true
false
fields
.primaryKey

adds a field to the specified ordinal position of the table's primary key when > 0.

integer

0 to 32

fields
.scale

for type "number" and "money", specifies the number of places to the right of the decimal point.

integer

0 to 32

fields
.type

defines the type of field

string

"bit"
"tinyint"
"smallint"
"integer"
"bigint"
"real"
"float"
"number"
"money"
"date"
"time"
"timestamp"
"char"
"varchar"
"lvarchar"
"binary"
"varbinary"
"lvarbinary"
"json"


"autoValue"

This optional property indicates when and how the server automatically sets the field value.

Only one of these values is allowed per field.

  • "none" indicates that the server does not automatically set the field's value.

  • "incrementOnInsert" indicates that the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as "bigint". Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the "id" field as an "incrementOnInsert" field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign  "primaryKey": 1 to it.

  • "timestampOnInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of "timestamp".

    Note

    If you attempt to insert a record and specify a timestamp for a field that has "autoValue" set to "timestampOnInsert", the timestamp you specified is ignored, and the current date and time are assigned to the field.

  • "timestampOnUpdate" indicates that the server automatically sets a field’s value to the current date and time of an update. This setting applies only to timestamp fields.

  • "timestampOnUpdateAndInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of "timestamp".

  • "changeId" indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be "bigint".

    The JSON DB API automatically creates a "changeid" field with change-tracking functionality.

    Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.

Request Example

"fields": [
  {
    "name": "signed_int32",
    "type": "integer",
    "autoValue": "incrementOnInsert"
  }
]

Response Example

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "signed_int32",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "integer"
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

"data"

The "data" property is an array of objects or arrays that contain information about the database. The "dataFormat" property specifies whether the content is arrays or objects. The initiating action defines the data contents. In results messages, when no results are available, it is empty. For path formats, see "path".

Examples

arrays
"data":
[
  ["test1", ".\\test1.dbs\\SQL_SYS", 1003]
]
objects
"data":
[
  {
    "databaseName": "test7",
    "path": ".\\test7.dbs\\SQL_SYS",
    "uid": 1015
  }
]

"dataFormat"

The "dataFormat" property is a case-insensitive string enum that 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".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.

    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.

  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.

    Possible values include:

    • "arrays"

      This 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.

    • "autoDetect"

      This is the default, and the server automatically detects the format of the data in the "sourceData" property.

  • "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.

Example response

{
  "result": {
    "dataFormat": "objects"
  }
}

"fields"

The "fields" property is an array of objects. It is required when creating a table. Each object in the array defines a field by specifying its properties.

Example

"fields": [
  {
    "autoValue": "none",
    "name": "name",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false
  }
]