`"closeCursor"`

The closeCursor action closes a previously opened cursor

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"
  }
}

Maximal request example

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

Response examples

Minimal response example

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

Maximal response example

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

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.

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.