Skip to main content

"closeCursor"

Abstract

closeCursor action closes a previously opened cursor.

The "closeCursor" action closes a previously opened cursor.

Things to know

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

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

Response examples

{
  "authToken": "authToken",
  "errorCode": 0,
  "errorMessage": ""
}
{
  "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": ""
}

"params"

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

Property summary table

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

"cursorId"

contains a unique identifier returned by the server

Required - No default value

string

Minimum length: 0
Maximum length: 255


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

Things to know:
  • 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.