Documents the internal _dm_db procs

content/language/internal/_dm_db_close.md

@@ -0,0 +1,17 @@
++++
+title = "_dm_db_close"
+[[extra.args]]
+name = "db_obj"
+description = "An internal database object, db_conn or db_query"
+[extra.return]
+type = "num" # AUTOGEN SKIP
+description = "`TRUE` if the object was closed, otherwise `FALSE`"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+"Closes" the [`db_conn`](./_dm_db_new_con.md) or [`db_query`](./_dm_db_new_query.md), resetting the object to its initial state.
+
+It's important to ensure that `db_conn` instances always close their connection at the end of their lifetime,<br>
+as failing to do so can cause hanging connections that are impossible to close.

content/language/internal/_dm_db_columns.md

@@ -0,0 +1,52 @@
++++
+title = "_dm_db_columns"
+[[extra.args]]
+name = "db_query"
+description = "A database query"
+[[extra.args]]
+name = "column_type"
+description = "Path that represents column data"
+[extra.return]
+type = "list" # AUTOGEN SKIP
+description = "An associative list of text keys to instance values"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Once a query is [executed](./_dm_db_execute.md), the `db_query` can be used to create a list of names along with their column data, which is useful for iterating over a set of rows.
+
+Each entry will have the name of the column as the key and an instance of the provided path as the value.
+For example, the query:
+```sql
+SELECT `first_name`, `last_name`, `dob` IN `my_table`;
+```
+will create this list:
+```dm
+list(
+	"first_name" = new /column(...),
+	"last_name" = new /column(...),
+	"dob" = new /column(...),
+)
+```
+
+Each database instance is created with **index-based** arguments.
+The arguments that are provided will differ based on the database driver.
+
+## MySql
+```dm
+/column/New(
+	name, // column name
+	table, // also column name
+	position, // column index, 0-index (BYOND is 1-index)
+	type, // appears to always be 0
+	flag, // column definition flags
+	length, // appears to always be a huge number
+	max_length // appears to always be a huge number
+)
+```
+
+## SQLite
+```dm
+// TODO
+```

content/language/internal/_dm_db_connect.md

@@ -0,0 +1,48 @@
++++
+title = "_dm_db_connect"
+[[extra.args]]
+name = "db_conn"
+description = "A database connection"
+[[extra.args]]
+name = "dsn"
+description = "The data source name (DSN) of the connection"
+[[extra.args]]
+name = "username"
+description = "Username for login credentials"
+[[extra.args]]
+name = "password"
+description = "Password for login credentials"
+[[extra.args]]
+name = "cursor_type"
+description = "Cursor type that the query will use"
+[[extra.args]]
+name = "?"
+description = "The purpose of this argument is unknown"
+[extra.return]
+type = "num" # AUTOGEN SKIP
+description = "`TRUE` if a connection was established successfully, otherwise `FALSE`"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Establishes a remote connection to a database.
+
+The format for a DSN in BYOND is:<br>
+```
+dbi:[driver]:[identifier]:[address]:[port]
+dbi:mysql:my_database:192.168.0.1:3306
+```
+
+Database drivers currently supported by BYOND:
+- MySQL (`mysql`)
+- SQLite (`unknown identifier`)
+
+{% parity() %}
+It is currently unknown if the database changes the values for `cursor_type`.
+{% end %}
+
+`cursor_type` changes how the query is handled:
+- `0` uses the database's default cursor behaviour.
+- `1` uses client cursor.
+- `2` uses server cursor.

content/language/internal/_dm_db_error_msg.md

@@ -0,0 +1,14 @@
++++
+title = "_dm_db_error_msg"
+[[extra.args]]
+name = "db_obj"
+description = "An internal database object, db_conn or db_query"
+[extra.return]
+type = "text" # AUTOGEN SKIP
+description = "The error given by the database object"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+If the provided object did not create an error during its previous action, the error message will be empty text. \(`""`\)

content/language/internal/_dm_db_execute.md

@@ -0,0 +1,35 @@
++++
+title = "_dm_db_execute"
+[[extra.args]]
+name = "db_query"
+description = "A database query"
+[[extra.args]]
+name = "query"
+description = "The query being sent to the database"
+[[extra.args]]
+name = "db_conn"
+description = "A database connection"
+[[extra.args]]
+name = "cursor_type"
+description = "Cursor type that the query will use"
+[[extra.args]]
+name = "?"
+description = "The purpose of this argument is unknown"
+[extra.return]
+type = "num" # AUTOGEN SKIP
+description = "`TRUE` if the query executed successfully, otherwise `FALSE`"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Performs a query on a [`db_conn`](./_dm_db_new_con.md) and stores the result in a [`db_query`](./_dm_db_new_query.md).<br>
+
+{% parity() %}
+It is currently unknown if the database changes the values for `cursor_type`.
+{% end %}
+
+`cursor_type` changes how the query is handled:
+- `0` uses the database's default cursor behaviour.
+- `1` uses client cursor.
+- `2` uses server cursor.

content/language/internal/_dm_db_is_connected.md

@@ -0,0 +1,12 @@
++++
+title = "_dm_db_is_connected"
+[[extra.args]]
+name = "db_conn"
+description = "A database connection"
+[extra.return]
+type = "num" # AUTOGEN SKIP
+description = "`TRUE` if a database connection is open, otherwise `FALSE`"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++

content/language/internal/_dm_db_new_con.md

@@ -0,0 +1,15 @@
++++
+title = "_dm_db_new_con"
+[extra.return]
+type = "db_conn" # AUTOGEN SKIP
+description = "A new connection object"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+Creates and returns an internal object we call a `db_conn`.
+
+`db_conn` is a special data type, different from a {{ datum() }} but still treated as an object.<br>
+It is used to perform database operations.
+
+{{ database() }} also internally creates a `db_conn`.

content/language/internal/_dm_db_new_query.md

@@ -0,0 +1,13 @@
++++
+title = "_dm_db_new_query"
+[extra.return]
+type = "db_query" # AUTOGEN SKIP
+description = "A new query object"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+Creates and returns an internal object we call a `db_query`.
+
+`db_query` is a special data type, different from a {{ datum() }} but still treated as an object.<br>
+It is used to store the results of a [query](./_dm_db_execute.md).

content/language/internal/_dm_db_next_row.md

@@ -0,0 +1,27 @@
++++
+title = "_dm_db_next_row"
+[[extra.args]]
+name = "db_query"
+description = "A database query"
+[[extra.args]]
+name = "items"
+description = "Container for the row items"
+[[extra.args]]
+name = "conversions"
+description = "A list"
+[extra.return]
+type = "num" # AUTOGEN SKIP
+description = "`TRUE` if another row was selected, otherwise `FALSE`"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+{% parity() %}
+Behaviour of `conversions` is currently unknown.
+{% end %}
+
+If possible, inserts the values of the next row into `items`.
+
+Calling this proc repeatedly will continue stepping through rows until there are no more rows in the selection.<br>
+It is not possible to step backwards.

content/language/internal/_dm_db_quote.md

@@ -0,0 +1,15 @@
++++
+title = "_dm_db_quote"
+[[extra.args]]
+name = "db_conn"
+description = "A database connection"
+[extra.return]
+type = "text" # AUTOGEN SKIP
+description = "Sanitized form of the input text"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Asks the connection to escape the provided text (Ex: `this 'dangerous' text` to `this \\'dangerous\\' text`).<br>
+Very important for treating user input, as it can prevent [malicious attacks](https://en.wikipedia.org/wiki/SQL_injection) on databases.

content/language/internal/_dm_db_row_count.md

@@ -0,0 +1,14 @@
++++
+title = "_dm_db_row_count"
+[[extra.args]]
+name = "db_query"
+description = "A database query"
+[extra.return]
+type = "num, null" # AUTOGEN SKIP
+description = "The number of rows, or `null` if not applicable"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Returns the number of rows that were **found** by the query's execution.

content/language/internal/_dm_db_rows_affected.md

@@ -0,0 +1,14 @@
++++
+title = "_dm_db_rows_affected"
+[[extra.args]]
+name = "db_query"
+description = "A database query"
+[extra.return]
+type = "num, null" # AUTOGEN SKIP
+description = "The number of rows, or `null` if not applicable"
+
+[extra]
+od_unimplemented = true # AUTOGEN FIELD
++++
+
+Returns the number of rows that were **altered** by the query's execution.

content/language/internal/_index.md

@@ -0,0 +1,9 @@
++++
+title = "Internal Procs"
+weight = 0
+page_template = "proc.html"
++++
+{% parity() %}
+Because these are meant for internal use and undocumented,<br>
+OpenDream's implementation of these procs may vary in accuracy.
+{% end %}