.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MONGOC_CURSOR_ERROR_DOCUMENT" "3" "May 07, 2024" "1.27.1" "libmongoc"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_cursor_error_document (mongoc_cursor_t *cursor,
                              bson_error_t *error,
                              const bson_t **reply);
.EE
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBcursor\fP: A \fI\%mongoc_cursor_t\fP\&.
.IP \(bu 2
\fBerror\fP: An optional location for a \fI\%bson_error_t\fP or \fBNULL\fP\&.
.IP \(bu 2
\fBreply\fP: A location for a \fI\%bson_t\fP\&.
.UNINDENT
.SH DESCRIPTION
.sp
This function checks to see if an error has occurred while iterating the cursor.
.sp
If an error occurred client\-side, for example if there was a network error or timeout, or the cursor was created with invalid parameters, then \fBreply\fP is set to an empty BSON document. If an error occurred server\-side, \fBreply\fP is set to the server\(aqs reply document with information about the error.
.SH ERRORS
.sp
Errors are propagated via the \fBerror\fP and \fBreply\fP parameters.
.SH RETURNS
.sp
False if no error has occurred, otherwise true and \fBerror\fP is set.
.sp
If the function returns true and \fBreply\fP is not NULL, then \fBreply\fP is set to a pointer to a BSON document, which is either empty or the server\(aqs error response. The document is invalid after the cursor is freed with \fI\%mongoc_cursor_destroy()\fP\&.
.SH EXAMPLE
.sp
This example shows the difference between a client\-side and server\-side error. If the client cannot connect to the server, for example, the error message includes \(dqNo suitable servers found\(dq and \fBreply\fP is set to an empty BSON document.
.sp
On the other hand, if the client connects to the server successfully and attempts to execute an invalid query, the error message comes from the server and \fBreply\fP is set to the server\(aqs reply document, with fields \fBerrmsg\fP and \fBcode\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void
run_query (const char *uri_str, const bson_t *query)
{
   mongoc_client_t *client;
   mongoc_collection_t *collection;
   mongoc_cursor_t *cursor;
   const bson_t *doc;
   bson_error_t error;
   const bson_t *reply;
   char *str;

   client = mongoc_client_new (uri_str);

   mongoc_client_set_error_api (client, 2);

   collection = mongoc_client_get_collection (client, \(dqdb\(dq, \(dqcollection\(dq);
   cursor = mongoc_collection_find_with_opts (
      collection,
      query,
      NULL,  /* additional options */
      NULL); /* read prefs, NULL for default */

   /* this loop is never run: mongoc_cursor_next immediately returns false */
   while (mongoc_cursor_next (cursor, &doc)) {
   }

   if (mongoc_cursor_error_document (cursor, &error, &reply)) {
      str = bson_as_json (reply, NULL);
      fprintf (stderr, \(dqCursor Failure: %s\enReply: %s\en\(dq, error.message, str);
      bson_free (str);
   }

   mongoc_cursor_destroy (cursor);
   mongoc_collection_destroy (collection);
   mongoc_client_destroy (client);
}

int
main (int argc, char *argv[])
{
   bson_t *good_query;
   bson_t *bad_query;

   mongoc_init ();

   /* find documents matching the query {\(dqx\(dq: 1} */
   good_query = BCON_NEW (\(dqx\(dq, BCON_INT64 (1));

   /* Cause a network error. This will print an error and empty reply document:
    *
    * Cursor Failure: No suitable servers found (\(gaserverSelectionTryOnce\(ga set):
    *     [Failed to resolve \(aqfake\-domain\(aq]
    *
    * Reply: { }
    *
    */
   run_query (\(dqmongodb://fake\-domain/?appname=cursor\-example\(dq, good_query);

   /* invalid: {\(dqx\(dq: {\(dq$badOperator\(dq: 1}} */
   bad_query = BCON_NEW (\(dqx\(dq, \(dq{\(dq, \(dq$badOperator\(dq, BCON_INT64 (1), \(dq}\(dq);

   /* Cause a server error. This will print an error and server reply document:
    *
    * Cursor Failure: unknown operator: $badOperator
    *
    * Reply:
    * {\(dqok\(dq: 0.0,
    *  \(dqerrmsg\(dq:\(dqunknown operator: $badOperator\(dq,
    *  \(dqcode\(dq: 2,
    *  \(dqcodeName\(dq:\(dqBadValue\(dq
    * }
    *
    */
   run_query (\(dqmongodb://localhost/?appname=cursor\-example\(dq, bad_query);

   bson_destroy (good_query);
   bson_destroy (bad_query);

   mongoc_cleanup ();

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.