closeCursor

JSON DB "closeCursor" action closes a previously opened cursor

The "closeCursor" action closes a previously opened cursor.

  • 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

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

 

Properties

Request properties ("params")
 

Property Description Default Type Limits (inclusive)

cursorId

The "cursorId" property specifies a unique cursor 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.

Required - No default value

 string 0 to 225 bytes

 

Was this article helpful?

Give feedback about this article

Related Articles