Skip to main content

"closeCursor" (JSON Action)

JSON DB "closeCursor" action closes a previously opened cursor

The "closeCursor" action closes a previously opened cursor.

Essential information

  • A cursor is opened when you set a "returnCursor" to true in one of the "getRecords" actions and it returns a valid "cursorId".

  • Calling "closeCursor" with an expired or closed cursor returns a warning instead of an error because the cursor is already closed as desired

  • Since a cursor consumes RAM and storage you will want to immediately close a cursor when it is no longer needed.

  • You can close a cursor with the appropriate "cursorId".

  • When a cursor is closed, its resources are released and its record results are no longer available.

Note

The server does automatically close a cursor when it has not been used in a while. However, this means it is consuming resources for longer than is needed, causing the server to tie up these resources instead of using them for additional work.

Request examples

Minimal

{
  "api": "db",
  "action": "closeCursor",
  "params": {
    "cursorId": "cursorIdSuppliedFromServer"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "requestId": "1",
  "api": "db",
  "action": "closeCursor",
  "params": {
    "cursorId": "cursorIdSuppliedFromServer"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Note

If the target object does not exist, the response returns success, and the debug property contains a warning that the object was not found.

Minimal

{
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "requestId": "1",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "closeCursor",
      "params": {
        "cursorId": "cursorIdSuppliedFromServer"
      },
      "apiVersion": "1.0",
      "requestId": "1",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Use the closeCursor JSON DB API action to close a previously opened cursor

API actionsJSON DB APIJSON Actionquery actionsclose cursorcloseCursor

"params"

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

cursorId

specifies a unique identifier returned by the server

Required - No default value

string

0 to 225 bytes



"cursorId"

The "cursorId" property is a required string from 0 to 255 bytes. It is a unique identifier returned by the server.

  • The "getRecordsFromCursor" action uses it to quickly and efficiently retrieve paginated records.

  • Setting a zero-length "cursorId" in the request is invalid.

  • It is not returned when "returnCursor" is false.

Important

Do not assume the "cursorId" is a number embedded in a string.