<commit_before>Using libsqon
=============

This is a short tutorial for using `libsqon`. You can find complete API
documentation [on Delwink's site][1] or by [generating it with Doxygen][2].

The following tutorial provides a basic usage demonstration for this
library. It relies on "fallback" behavior in the library for connectivity with
your database engine; namely, `libsqon` will connect to the database
automatically when querying and then disconnect. This is fine in situations
where only one query is needed, but it is very slow if queries are done in
succession. It would be advisable to call `sqon_connect ()`, do your queries,
then `sqon_close ()`, so that the socket is only opened once. This tutorial
will not be doing that, since it demonstrates a simple, single-query use-case.

The following is a complete program that will print the contents of a
table. Below it, we'll go into detail about each line.

``` c
#include <stdio.h>
#include <sqon.h>

int
main (int argc, char *argv[])
{
  int rc = 0;
  sqon_dbsrv mydb;
  char *output;

  sqon_init ();

  mydb = sqon_new_connection (SQON_DBCONN_MYSQL, "localhost",
			      "myuser", "mypasswd", "mydb");

  rc = sqon_query (&mydb, "SELECT * FROM MyTable", &output, NULL);
  if (rc)
    {
      fprintf (stderr, "Error %d\n", rc);
      return rc;
    }

  puts (output);
  sqon_free (output);

  return 0;
}
```

This example uses a MySQL database, but `libsqon` is designed to be identical
between databases, the only difference being what value is passed as the first
argument to `sqon_new_connection ()`.

Now, let's step through the program.

``` c
#include <stdio.h>
#include <sqon.h>
```

We must include these header files in order to make calls to `libsqon` and give
output to the console.

``` c
int
main (int argc, char *argv[])
{
  ...
}
```

This is the typical declaration of the `main ()` entry point into our
program. Although our program does not take arguments from the command line, it
may need to in the future, and it doesn't hurt to declare the standard `(int,
char **)` parameters.

``` c
int rc = 0;
sqon_dbsrv mydb;
char *output;
```

Here, we declare all the variables we'll need for our program: a place to store
the return value of `int` functions, a `libsqon` database connection object,
and a buffer for the database output.

``` c
sqon_init ();
```

`libsqon` needs to be initialized using this function. Without this, the
library will not be able to properly allocate memory internally.

``` c
mydb = sqon_new_connection (SQON_DBCONN_MYSQL, "localhost",
			    "myuser", "mypasswd", "mydb");
```

Here, we initialize a database connection object. This object will be
referenced when calling the database. Its purpose is to make query function
calls shorter and less error-prone.

The parameters are the type of database we're connecting to, the host of the
database server, the username, the password, and the database name. These
fields are optional based on context, but only the database is optional for
MySQL.

``` c
rc = sqon_query (&mydb, "SELECT * FROM MyTable", &output, NULL);
if (rc)
  {
    fprintf (stderr, "Error %d\n", rc);
    return rc;
  }
```

Finally, we call the database. The parameters are the address of your database
connection object, the SQL query, the output buffer (could be `NULL` if, say,
we were inserting or updating data which does not return anything from the
database), and a string representation of the return value's "primary key". I
use quotes, because this doesn't have to be the actual primary key of the
table. If the primary key value matches a column in the return value, the
output buffer will be organized by that key. Keep in mind that whatever key you
choose must be unique in the return value, or `libsqon` will throw an error.

In this example, we use `NULL` as the primary key, which will simply return
each row of the table as elements of an array, not organized by a particular
key.
<commit_msg>Updated documentation for interface 1.0<commit_after>Using libsqon
=============

This is a short tutorial for using `libsqon`. You can find complete API
documentation [on Delwink's site][1] or by [generating it with Doxygen][2].

The following tutorial provides a basic usage demonstration for this
library. It relies on "fallback" behavior in the library for connectivity with
your database engine; namely, `libsqon` will connect to the database
automatically when querying and then disconnect. This is fine in situations
where only one query is needed, but it is very slow if queries are done in
succession. It would be advisable to call `sqon_connect ()`, do your queries,
then `sqon_close ()`, so that the socket is only opened once. This tutorial
will not be doing that, since it demonstrates a simple, single-query use-case.

The following is a complete program that will print the contents of a
table. Below it, we'll go into detail about each line.

``` c
#include <stdio.h>
#include <sqon.h>

int
main (int argc, char *argv[])
{
  int rc = 0;
  sqon_DatabaseServer *mydb;
  char *output;

  sqon_init ();

  mydb = sqon_new_connection (SQON_DBCONN_MYSQL, "localhost",
			      "myuser", "mypasswd", "mydb", "0");

  rc = sqon_query (mydb, "SELECT * FROM MyTable", &output, NULL);
  sqon_free_connection (mydb);
  if (rc)
    {
      fprintf (stderr, "Error %d\n", rc);
      return rc;
    }

  puts (output);
  sqon_free (output);

  return 0;
}
```

This example uses a MySQL database, but `libsqon` is designed to be identical
between databases, the only difference being what value is passed as the first
argument to `sqon_new_connection ()`.

Now, let's step through the program.

``` c
#include <stdio.h>
#include <sqon.h>
```

We must include these header files in order to make calls to `libsqon` and give
output to the console.

``` c
int
main (int argc, char *argv[])
{
  ...
}
```

This is the typical declaration of the `main ()` entry point into our
program. Although our program does not take arguments from the command line, it
may need to in the future, and it doesn't hurt to declare the standard `(int,
char **)` parameters.

``` c
int rc = 0;
sqon_DatabaseServer *mydb;
char *output;
```

Here, we declare all the variables we'll need for our program: a place to store
the return value of `int` functions, a `libsqon` database connection object,
and a buffer for the query result set.

``` c
sqon_init ();
```

`libsqon` needs to be initialized using this function. Without this, the
library will not be able to properly allocate memory internally.

``` c
mydb = sqon_new_connection (SQON_DBCONN_MYSQL, "localhost",
			    "myuser", "mypasswd", "mydb", "0");
```

Here, we initialize a database connection object. This object will be
referenced when calling the database. Its purpose is to make query function
calls shorter and less error-prone.

The parameters are the type of database we're connecting to, the host of the
database server, the username, the password, the database name, and a string
representation of the port number ("0" uses the default). These fields are
optional based on context, but only the database is optional for MySQL.

``` c
rc = sqon_query (mydb, "SELECT * FROM MyTable", &output, NULL);
sqon_free_connection (mydb);
if (rc)
  {
    fprintf (stderr, "Error %d\n", rc);
    return rc;
  }
```

Finally, we call the database. The parameters are the address of your database
connection object, the SQL query, the output buffer (could be `NULL` if, say,
we were inserting or updating data which does not return anything from the
database), and a string representation of the return value's "primary key". I
use quotes, because this doesn't have to be the actual primary key of the
table. If the primary key value matches a column in the return value, the
output buffer will be organized by that key. Keep in mind that whatever key you
choose must be unique in the return value, or `libsqon` will throw an error.

In this example, we use `NULL` as the primary key, which will simply return
each row of the table as elements of an array, not organized by a particular
key.

After we query the database, we are finished with this connection object, so we
free the memory allocated to it.

{'fraction_non_alphanumeric': 0.08392377229416076, 'fraction_numerical': 0.001832396774981676, 'mean_word_length': 4.1620428751576295, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1738890', 'n_tokens_mistral': 2407, 'n_tokens_neox': 2307, 'n_words': 1230}