Skip to main content

"closeCursor"

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 request

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

Maximal request

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

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 response

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

Maximal response

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

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

API actionsJSON DB APIjsonActionquery actionsclose cursorcloseCursor

"params"

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

Properties summary

Table 1. "params" properties summary

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.

Essential information

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