From 5b9f3402b69cde83ffac9d1b032a2f233f8ce8f8 Mon Sep 17 00:00:00 2001 From: Jacob Schmidt Date: Sat, 22 Mar 2025 16:31:59 -0500 Subject: [PATCH] docs: add comprehensive documentation and usage examples for ramdb --- addons/db/functions/fnc_save.sqf | 2 - docs/basic/delete.md | 49 +++++++++++++++++++++ docs/basic/fetch.md | 39 +++++++++++++++++ docs/basic/get.md | 55 +++++++++++++++++++++++ docs/basic/load.md | 48 ++++++++++++++++++++ docs/basic/save.md | 56 ++++++++++++++++++++++++ docs/basic/set.md | 58 ++++++++++++++++++++++++ docs/core/addTask.md | 67 ++++++++++++++++++++++++++++ docs/core/handler.md | 64 +++++++++++++++++++++++++++ docs/core/init.md | 46 ++++++++++++++++++++ docs/core/printAddonName.md | 53 ++++++++++++++++++++++ docs/core/processQueue.md | 57 ++++++++++++++++++++++++ docs/core/scheduler.md | 57 ++++++++++++++++++++++++ docs/core/test.md | 61 ++++++++++++++++++++++++++ docs/hash/hashDelete.md | 61 ++++++++++++++++++++++++++ docs/hash/hashDeleteId.md | 69 +++++++++++++++++++++++++++++ docs/hash/hashGet.md | 74 +++++++++++++++++++++++++++++++ docs/hash/hashGetAll.md | 73 +++++++++++++++++++++++++++++++ docs/hash/hashGetAllId.md | 74 +++++++++++++++++++++++++++++++ docs/hash/hashGetId.md | 75 ++++++++++++++++++++++++++++++++ docs/hash/hashRemove.md | 67 ++++++++++++++++++++++++++++ docs/hash/hashRemoveId.md | 72 ++++++++++++++++++++++++++++++ docs/hash/hashSet.md | 72 ++++++++++++++++++++++++++++++ docs/hash/hashSetBulk.md | 72 ++++++++++++++++++++++++++++++ docs/hash/hashSetId.md | 73 +++++++++++++++++++++++++++++++ docs/hash/hashSetIdBulk.md | 73 +++++++++++++++++++++++++++++++ docs/list/listAdd.md | 66 ++++++++++++++++++++++++++++ docs/list/listDelete.md | 71 ++++++++++++++++++++++++++++++ docs/list/listGet.md | 70 +++++++++++++++++++++++++++++ docs/list/listLoad.md | 74 +++++++++++++++++++++++++++++++ docs/list/listRemove.md | 72 ++++++++++++++++++++++++++++++ docs/list/listSet.md | 73 +++++++++++++++++++++++++++++++ 32 files changed, 1991 insertions(+), 2 deletions(-) create mode 100644 docs/basic/delete.md create mode 100644 docs/basic/fetch.md create mode 100644 docs/basic/get.md create mode 100644 docs/basic/load.md create mode 100644 docs/basic/save.md create mode 100644 docs/basic/set.md create mode 100644 docs/core/addTask.md create mode 100644 docs/core/handler.md create mode 100644 docs/core/init.md create mode 100644 docs/core/printAddonName.md create mode 100644 docs/core/processQueue.md create mode 100644 docs/core/scheduler.md create mode 100644 docs/core/test.md create mode 100644 docs/hash/hashDelete.md create mode 100644 docs/hash/hashDeleteId.md create mode 100644 docs/hash/hashGet.md create mode 100644 docs/hash/hashGetAll.md create mode 100644 docs/hash/hashGetAllId.md create mode 100644 docs/hash/hashGetId.md create mode 100644 docs/hash/hashRemove.md create mode 100644 docs/hash/hashRemoveId.md create mode 100644 docs/hash/hashSet.md create mode 100644 docs/hash/hashSetBulk.md create mode 100644 docs/hash/hashSetId.md create mode 100644 docs/hash/hashSetIdBulk.md create mode 100644 docs/list/listAdd.md create mode 100644 docs/list/listDelete.md create mode 100644 docs/list/listGet.md create mode 100644 docs/list/listLoad.md create mode 100644 docs/list/listRemove.md create mode 100644 docs/list/listSet.md diff --git a/addons/db/functions/fnc_save.sqf b/addons/db/functions/fnc_save.sqf index 36bf3c3..65a0972 100644 --- a/addons/db/functions/fnc_save.sqf +++ b/addons/db/functions/fnc_save.sqf @@ -23,9 +23,7 @@ * * Examples: * [] call ramdb_db_fnc_save (Server or Singleplayer Only) - * [true] call ramdb_db_fnc_save (Server or Singleplayer Only) * [] remoteExecCall ["ramdb_db_fnc_save", 2, false] (Multiplayer Only) - * [true] remoteExecCall ["ramdb_db_fnc_save", 2, false] (Multiplayer Only) * * Public: Yes */ diff --git a/docs/basic/delete.md b/docs/basic/delete.md new file mode 100644 index 0000000..3e19eaa --- /dev/null +++ b/docs/basic/delete.md @@ -0,0 +1,49 @@ +--- +title: ArmaRAMDb - Delete Key +icon: mdi:file-text-outline +excerpt: Remove the specified key from RAMDb. +--- + +# ramdb_db_fnc_delete + +## Description +Removes the specified key from the database. This function deletes the key-value pair completely from storage. + +## Syntax +```sqf +[_key] call ramdb_db_fnc_delete +``` + +## Parameters +| Parameter | Type | Description | +|-----------|--------|-------------------------------------------| +| `_key` | String | Name of the key to delete from the database | + +## Return Value +None. The operation runs asynchronously. + +## Examples +### Delete a key in singleplayer or on the server: +```sqf +["playerData"] call ramdb_db_fnc_delete; +``` + +### Delete a key on the server from a client: +```sqf +["playerData"] remoteExecCall ["ramdb_db_fnc_delete", 2, false]; +``` + +## Notes +- This operation is permanent and cannot be undone +- If the key doesn't exist, the operation will have no effect +- This function only affects specific keys, not hash tables or lists + +## Related Functions +- `ramdb_db_fnc_get`: Retrieves a value by key +- `ramdb_db_fnc_set`: Stores a value by key + +## Links + +[Delete Key](delete) | +[Get Key](get) | +[Set Key](set) \ No newline at end of file diff --git a/docs/basic/fetch.md b/docs/basic/fetch.md new file mode 100644 index 0000000..c9e2a50 --- /dev/null +++ b/docs/basic/fetch.md @@ -0,0 +1,39 @@ +# ramdb_db_fnc_fetch + +## Description +Handles data chunks received from the database extension when data is too large to be returned in a single callback. This function collects all chunks of data, reassembles them in the correct order, and then passes the complete data to the handler function. + +## Syntax +```sqf +[_uniqueID, _function, _index, _total, _datachunk, _call, _netId] call ramdb_db_fnc_fetch +``` + +## Parameters +| Parameter | Type | Description | +|-------------|-----------|-------------------------------------------------------------| +| `_uniqueID` | String | Unique identifier for this data fetch operation | +| `_function` | String | Name of the function to call after data is assembled | +| `_index` | Number | Current chunk index (0-based) | +| `_total` | Number | Total number of chunks expected | +| `_datachunk`| String | The chunk of data being received | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | +| `_netId` | String | (Optional) NetID of the player to whom the data belongs | + +## Return Value +None. When all chunks are received, the function will: +1. Assemble the complete data string +2. Parse it as a simple array +3. Call the specified handler function with the parsed data + +## Examples +This function is typically not called directly but is triggered by the extension's callback mechanism when large datasets are retrieved. + +## Notes +- The function stores received chunks in the global array `ramdb_db_fetch_array` +- Chunks are sorted by their index to ensure correct assembly regardless of arrival order +- After successful processing, the chunks for this uniqueID are removed from the array +- This function is essential for handling large datasets that exceed the callback buffer limit + +## Related Functions +- `ramdb_db_fnc_handler`: Receives the assembled data and routes it to the appropriate function +- `ramdb_db_fnc_scheduler`: Manages the callback queue and triggers data fetching diff --git a/docs/basic/get.md b/docs/basic/get.md new file mode 100644 index 0000000..e1adc59 --- /dev/null +++ b/docs/basic/get.md @@ -0,0 +1,55 @@ +--- +title: ArmaRAMDb - Get Key +icon: mdi:file-text-outline +excerpt: Get the value of stored key from RAMDb. +--- + +# ramdb_db_fnc_get + +## Description +Retrieves the value of a stored key from the database. This function performs an asynchronous request to the database and passes the retrieved data to the specified callback function. + +## Syntax +```sqf +[_key, _function, _call, _netId] call ramdb_db_fnc_get +``` + +## Parameters +| Parameter | Type | Description | +|-------------|-----------|-----------------------------------------------------------------| +| `_key` | String | Name of the stored key to retrieve from the database | +| `_function` | String | Name of the function to call when data is retrieved | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | +| `_netId` | String | (Optional) NetID of the player to whom the data should be returned | + +## Return Value +None. When data is retrieved, it will be passed to the specified function. The operation runs asynchronously. + +## Examples +### Retrieve data in singleplayer or on the server: +```sqf +[getPlayerUID player, "ramdb_db_fnc_test"] call ramdb_db_fnc_get; +``` + +### Retrieve data on the server and send to a specific client: +```sqf +[getPlayerUID player, "ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_get", 2, false]; +``` + +## Notes +- The function exit with an error if the key or function parameters are empty +- Data is processed through the scheduler system, which manages callback responses +- For large data that exceeds buffer limits, it will be automatically chunked and reassembled +- The callback function must be defined to accept the retrieved data +- The `_call` parameter determines whether the callback is executed directly or spawned in a separate thread + +## Related Functions +- `ramdb_db_fnc_set`: Stores a value by key +- `ramdb_db_fnc_delete`: Removes a value by key +- `ramdb_db_fnc_scheduler`: Processes the callback response + +## Links + +[Delete Key](delete) | +[Get Key](get) | +[Set Key](set) \ No newline at end of file diff --git a/docs/basic/load.md b/docs/basic/load.md new file mode 100644 index 0000000..03f357c --- /dev/null +++ b/docs/basic/load.md @@ -0,0 +1,48 @@ +--- +title: ArmaRAMDb - Load DB +icon: mdi:file-text-outline +excerpt: Load DB from disc. +--- + +# ramdb_db_fnc_load + +## Description +Loads the database from disk storage. This function restores all data (key-value pairs, hash tables, and lists) from the previously saved database file. + +## Syntax +```sqf +[] call ramdb_db_fnc_load +``` + +## Parameters +None. This function does not require any parameters. + +## Return Value +None. The operation runs synchronously and loads the database immediately. + +## Examples +### Load the database on the server: +```sqf +[] call ramdb_db_fnc_load; +``` + +### Call the load function remotely from a client: +```sqf +[] remoteExecCall ["ramdb_db_fnc_load", 2, false]; +``` + +## Notes +- This function should typically be called during server initialization +- Any existing data in memory will be overwritten with the data from disk +- If no database file exists, nothing will happen +- Loading does not affect ongoing operations, but might replace values in memory +- For safety, it's recommended to call this function only when necessary + +## Related Functions +- `ramdb_db_fnc_save`: Saves the database to disk +- `ramdb_db_fnc_isLoaded`: Checks if the database has been loaded + +## Links + +[Save DB](save) | +[Load DB](load) \ No newline at end of file diff --git a/docs/basic/save.md b/docs/basic/save.md new file mode 100644 index 0000000..9b44d81 --- /dev/null +++ b/docs/basic/save.md @@ -0,0 +1,56 @@ +--- +title: ArmaRAMDb - Save DB +icon: mdi:file-text-outline +excerpt: Save DB to disc. +--- + +# ramdb_db_fnc_save + +## Description +Saves the entire database to disk storage. This function persists all data (key-value pairs, hash tables, and lists) to a file, allowing it to be retrieved later even after server restart. + +## Syntax +```sqf +[_createBackup] call ramdb_db_fnc_save +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------------|---------|------------------------------------------------|---------| +| `_createBackup` | Boolean | Whether to create a backup of the current state | false | + +## Return Value +None. The operation runs synchronously and saves the database immediately. + +## Examples +### Save the database without creating a backup: +```sqf +[] call ramdb_db_fnc_save; +``` + +### Save the database and create a backup: +```sqf +[true] call ramdb_db_fnc_save; +``` + +### Call the save function remotely from a client: +```sqf +[] remoteExecCall ["ramdb_db_fnc_save", 2, false]; +``` + +## Notes +- This function should be called periodically to ensure data persistence +- The backup feature creates a timestamped copy of the database +- Automatic backups can be configured in the extension's config file +- Saving is a resource-intensive operation, so it shouldn't be called too frequently +- Consider saving before mission end or during low-activity periods + +## Related Functions +- `ramdb_db_fnc_load`: Loads the database from disk +- `ramdb_db_fnc_listBackups`: Lists available database backups +- `ramdb_db_fnc_restoreBackup`: Restores from a specific backup + +## Links + +[Save DB](save) | +[Load DB](load) \ No newline at end of file diff --git a/docs/basic/set.md b/docs/basic/set.md new file mode 100644 index 0000000..0e32449 --- /dev/null +++ b/docs/basic/set.md @@ -0,0 +1,58 @@ +--- +title: ArmaRAMDb - Set Key +icon: mdi:file-text-outline +excerpt: Set the value of stored key from RAMDb. +--- + +# ramdb_db_fnc_set + +## Description +Stores a value in the database with the specified key. This function allows saving various data types (arrays, strings, numbers, or booleans) that can be retrieved later using the key. + +## Syntax +```sqf +[_key, _data] call ramdb_db_fnc_set +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|----------------------------------|----------------------------------------------|---------| +| `_key` | String | Name of the key to store the data under | "" | +| `_data` | Array, String, Number, or Boolean| The value to store in the database | [] | + +## Return Value +None. The operation runs asynchronously. + +## Examples +### Store a simple array: +```sqf +["playerInventory", ["item1", "item2", "item3"]] call ramdb_db_fnc_set; +``` + +### Store player data under their UID: +```sqf +[getPlayerUID player, [name player, getPos player, getAllGear player]] call ramdb_db_fnc_set; +``` + +### Call the set function remotely from a client: +```sqf +["serverSetting", [true, 30, "normal"]] remoteExecCall ["ramdb_db_fnc_set", 2, false]; +``` + +## Notes +- The function validates both the key and data before attempting to store +- If the key already exists, its value will be overwritten +- Complex data structures should be serialized into arrays +- There are no size limits for data, but extremely large values might impact performance +- For structured data, consider using hash tables instead of key-value pairs + +## Related Functions +- `ramdb_db_fnc_get`: Retrieves a value by key +- `ramdb_db_fnc_delete`: Removes a value by key +- `ramdb_db_fnc_hashSet`: Stores a value in a hash table for more structured data + +## Links + +[Delete Key](delete) | +[Get Key](get) | +[Set Key](set) \ No newline at end of file diff --git a/docs/core/addTask.md b/docs/core/addTask.md new file mode 100644 index 0000000..c82e574 --- /dev/null +++ b/docs/core/addTask.md @@ -0,0 +1,67 @@ +--- +title: ArmaRAMDb - Add Task +icon: mdi:file-text-outline +excerpt: Add task to queue. +--- + +# ramdb_db_fnc_addTask + +## Description +Adds a task to the database operation queue. This function is used to schedule database operations that can be processed sequentially, providing a way to manage multiple database requests in an organized manner. + +## Syntax +```sqf +[_taskType, _key, _keyField, _index, _value, _function, _call, _netId] call ramdb_db_fnc_addTask +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|----------------------------------|----------------------------------------------------|---------| +| `_taskType` | String | Type of operation to perform (e.g., "hgetall") | "" | +| `_key` | String | Name of the stored key | "" | +| `_keyField` | String | Field name for hash operations | "" | +| `_index` | Number | Index for list operations | -1 | +| `_value` | Array, String, Number, or Boolean| Value to store (for set operations) | [] | +| `_function` | String | Name of function to call with the result | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | NetID of the target to receive the result | "" | + +## Return Value +None. The task is added to the queue and processed asynchronously. + +## Examples +### Add a hash table retrieval task: +```sqf +["hgetall", "", "", -1, [], "ramdb_db_fnc_test"] call ramdb_db_fnc_addTask; +``` + +### Add a player-specific task that returns data to a specific client: +```sqf +["hgetallid", getPlayerUID player, "", -1, [], "ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_addTask", 2, false]; +``` + +### Add a list operation task: +```sqf +["listadd", "playerMessages", "", -1, ["New message content"], ""] call ramdb_db_fnc_addTask; +``` + +## Notes +- Tasks are processed in the order they are added to the queue +- If the queue is not currently being processed, this function will start the processing +- The task type determines which database operation will be performed +- This function is particularly useful for scheduling multiple related operations +- All operations performed through the task queue are logged for debugging + +## Related Functions +- `ramdb_db_fnc_processQueue`: Processes the pending tasks in the queue +- `ramdb_db_fnc_handler`: Handles the results of completed database operations +- `ramdb_db_fnc_scheduler`: Manages callback responses from the database + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/core/handler.md b/docs/core/handler.md new file mode 100644 index 0000000..633faeb --- /dev/null +++ b/docs/core/handler.md @@ -0,0 +1,64 @@ +--- +title: ArmaRAMDb - Handler +icon: mdi:file-text-outline +excerpt: Handle data from DB. +--- + +# ramdb_db_fnc_handler + +## Description +Handles data received from the database and routes it to the appropriate function. This function is a critical component of the callback system, receiving data from database operations and directing it to the specified function, either locally or to a remote client. + +## Syntax +```sqf +[_uniqueID, _function, _call, _data, _netId] call ramdb_db_fnc_handler +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|----------------------------------|-------------------------------------------------------|---------| +| `_uniqueID` | String | Unique identifier for the data chunk | "" | +| `_function` | String | Name of function to receive the data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_data` | Array, String, Number, or Boolean| The data retrieved from the database | [] | +| `_netId` | String | (Optional) NetID of the player to receive the data | nil | + +## Return Value +None. The data is passed to the specified function for processing. + +## Examples +### Process data locally: +```sqf +["0123456789", "ramdb_db_fnc_test", false, ["Hello World!"]] call ramdb_db_fnc_handler; +``` + +### Send data to a specific client: +```sqf +["0123456789", "ramdb_db_fnc_test", false, ["Hello World!"], netId player] remoteExecCall ["ramdb_db_fnc_handler", 2, false]; +``` + +### Process data with direct call (synchronous): +```sqf +["0123456789", "ramdb_db_fnc_processInventory", true, [["weapon1", 30], ["item2", 5]]] call ramdb_db_fnc_handler; +``` + +## Notes +- The function validates that both the function name and data are valid before proceeding +- When a netId is provided, the data is sent to that specific client using remoteExec +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- This function is typically called by the scheduler or other core components rather than directly by user code +- Each handler call is logged, which is useful for debugging data flow + +## Related Functions +- `ramdb_db_fnc_scheduler`: Processes callbacks from the database extension +- `ramdb_db_fnc_fetch`: Assembles data chunks for large datasets +- `ramdb_db_fnc_addTask`: Adds tasks to the database operation queue + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/core/init.md b/docs/core/init.md new file mode 100644 index 0000000..93c6d4b --- /dev/null +++ b/docs/core/init.md @@ -0,0 +1,46 @@ +--- +title: ArmaRAMDb - Initialization +icon: mdi:file-text-outline +excerpt: Initial Extension settings. +--- + +# ramdb_db_fnc_init + +## Description +Initializes the ArmaRAMDb extension and sets up the initial settings. This function loads the extension, checks its version, sets the buffer size, and logs the initialization status. It is automatically called during mission startup. + +## Syntax +```sqf +// This function is automatically called during initialization and doesn't need to be called directly +``` + +## Parameters +None. This function does not require any parameters. + +## Return Value +None. The function sets up internal variables and logs initialization information. + +## Examples +This function is automatically executed during framework initialization and doesn't need to be called manually. + +## Notes +- Sets the global buffer size to 10240 bytes (10KB) +- Logs the DLL version number for reference +- Confirms successful loading of all functions +- Outputs initialization status to the RPT logs +- This is one of the first functions called when the framework loads +- It does not initialize or load any database data - use `ramdb_db_fnc_load` for that + +## Related Functions +- `ramdb_db_fnc_load`: Loads database data from disk +- `ramdb_db_fnc_save`: Saves database data to disk +- `ramdb_db_fnc_isLoaded`: Checks if the database has been loaded + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/core/printAddonName.md b/docs/core/printAddonName.md new file mode 100644 index 0000000..36abf59 --- /dev/null +++ b/docs/core/printAddonName.md @@ -0,0 +1,53 @@ +--- +title: ArmaRAMDb - Print Addon Name +icon: mdi:file-text-outline +excerpt: Displays the addon name in system chat. +--- + +# ramdb_db_fnc_printAddonName + +## Description +Displays a thank you message with the addon name in the system chat. This is a simple utility function that can be used to acknowledge the use of the framework or to verify that the addon is properly loaded. + +## Syntax +```sqf +[] call ramdb_db_fnc_printAddonName +``` + +## Parameters +None. This function does not require any parameters. + +## Return Value +None. The function outputs a message to the system chat. + +## Examples +### Display the addon name message: +```sqf +[] call ramdb_db_fnc_printAddonName; +``` + +### Use in a welcome script: +```sqf +if (isServer) then { + [] remoteExec ["ramdb_db_fnc_printAddonName", 0, true]; +}; +``` + +## Notes +- The function uses the ADDON macro defined in script_component.hpp +- This displays a message directly in the player's system chat +- Can be useful as a quick verification that the addon is loaded correctly +- Often used during development or for first-time users + +## Related Functions +- `ramdb_db_fnc_init`: Initializes the database system +- `ramdb_db_fnc_isLoaded`: Checks if the database is loaded + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) diff --git a/docs/core/processQueue.md b/docs/core/processQueue.md new file mode 100644 index 0000000..b75551b --- /dev/null +++ b/docs/core/processQueue.md @@ -0,0 +1,57 @@ +--- +title: ArmaRAMDb - Process Queue +icon: mdi:file-text-outline +excerpt: Processes a queue of tasks to be executed. +--- + +# ramdb_db_fnc_processQueue + +## Description +Processes the queue of pending database tasks sequentially. This function executes each task in the queue one by one, handling various database operations based on the task type. It continues processing until the queue is empty. + +## Syntax +```sqf +[] spawn ramdb_db_fnc_processQueue +``` + +## Parameters +None. This function does not require any parameters. + +## Return Value +None. The function processes tasks in the queue and updates the processing state. + +## Examples +### Start processing the queue manually: +```sqf +[] spawn ramdb_db_fnc_processQueue; +``` + +### Trigger queue processing from a client: +```sqf +[] remoteExec ["ramdb_db_fnc_processQueue", 2, false]; +``` + +## Notes +- Sets `GVAR(isProcessing)` to true while running and false when complete +- Processes one task per second to prevent overloading +- Handles a wide range of database operations including: + - Key-value operations (get, set, delete) + - Hash table operations (hget, hset, hgetall, etc.) + - List operations (listadd, listrng, listset, etc.) +- Automatically started by `ramdb_db_fnc_addTask` when new tasks are added +- Each task execution is logged for debugging purposes +- Should typically be spawned rather than called to avoid blocking + +## Related Functions +- `ramdb_db_fnc_addTask`: Adds tasks to the queue for processing +- `ramdb_db_fnc_handler`: Handles data returned from database operations +- `ramdb_db_fnc_scheduler`: Manages callback responses from the database + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/core/scheduler.md b/docs/core/scheduler.md new file mode 100644 index 0000000..4be6597 --- /dev/null +++ b/docs/core/scheduler.md @@ -0,0 +1,57 @@ +--- +title: ArmaRAMDb - Scheduler +icon: mdi:file-text-outline +excerpt: Scheduled Environment for extension. +--- + +# ramdb_db_fnc_scheduler + +## Description +Manages the callback system for the ArmaRAMDb extension. This function receives task IDs from the extension's asynchronous callbacks, parses them, and registers them in a hashmap for later processing. It acts as the bridge between the extension's asynchronous operations and the game's execution environment. + +## Syntax +```sqf +[_taskID] call ramdb_db_fnc_scheduler +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|--------|-------------------------------------------------|---------| +| `_taskID` | String | Task identifier returned from extension callback | "" | + +## Return Value +None. The function registers the task ID in a hashmap for later processing. + +## Examples +### Process a callback from the extension: +```sqf +["1689524160123_get"] call ramdb_db_fnc_scheduler; +``` + +### Forward a callback to the server: +```sqf +["1689524160123_hgetall"] remoteExecCall ["ramdb_db_fnc_scheduler", 2, false]; +``` + +## Notes +- Parses the task ID to extract the timestamp and operation type +- Registers the task in a type-specific hashmap using the mission namespace +- Each operation type (get, hgetall, etc.) has its own hashmap for tracking +- The format of task IDs is typically: `[timestamp]_[operation]` +- This function is automatically called by the extension callback mechanism +- Creates hashmaps on demand if they don't already exist +- Critical for handling asynchronous database operations + +## Related Functions +- `ramdb_db_fnc_fetch`: Assembles data chunks for large datasets +- `ramdb_db_fnc_handler`: Processes the data retrieved from database operations +- `ramdb_db_fnc_processQueue`: Executes queued database operations + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/core/test.md b/docs/core/test.md new file mode 100644 index 0000000..2a1be55 --- /dev/null +++ b/docs/core/test.md @@ -0,0 +1,61 @@ +--- +title: ArmaRAMDb - Test +icon: mdi:file-text-outline +excerpt: Test Function. +--- + +# ramdb_db_fnc_test + +## Description +A simple test function for verifying database operations. This function displays the received data in a hint message and logs it to the RPT file. It's primarily used for testing database retrieval operations and callback functionality. + +## Syntax +```sqf +[_value] spawn ramdb_db_fnc_test +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|----------------------------------|----------------------------------|---------| +| `_value` | Array, String, Number, or Boolean| The value to display and log | [] | + +## Return Value +The same value that was passed to the function. Also sets the global variable `ramdb_db_test` to this value. + +## Examples +### Test with a simple string: +```sqf +["Hello World!"] spawn ramdb_db_fnc_test; +``` + +### Test database retrieval by specifying this as callback function: +```sqf +["playerStats", "ramdb_db_fnc_test"] call ramdb_db_fnc_get; +``` + +### Test from client to server: +```sqf +["Database is working!"] remoteExec ["ramdb_db_fnc_test", 2, false]; +``` + +## Notes +- Displays the received value using `hint` +- Logs the same value to the RPT file +- Stores the value in the global variable `ramdb_db_test` for later inspection +- Commonly used as a callback function for database operations +- Useful for debugging and verifying data flow +- Can be called directly or specified as a callback in other functions + +## Related Functions +- `ramdb_db_fnc_get`: Retrieves values from the database +- `ramdb_db_fnc_handler`: Routes data to callback functions +- `ramdb_db_fnc_scheduler`: Manages the callback system + +## Links + +[Add Task](addtask) | +[Handler](handler) | +[Init](init) | +[Process Queue](processqueue) | +[Scheduler](scheduler) | +[Test](test) \ No newline at end of file diff --git a/docs/hash/hashDelete.md b/docs/hash/hashDelete.md new file mode 100644 index 0000000..f1689c7 --- /dev/null +++ b/docs/hash/hashDelete.md @@ -0,0 +1,61 @@ +--- +title: ArmaRAMDb - Hash Delete +icon: mdi:file-text-outline +excerpt: Remove the current client's hash table from database. +--- + +# ramdb_db_fnc_hashDelete + +## Description +Removes the hash table associated with the current client/player from the database. Unlike `hashDeleteId`, this function automatically retrieves the appropriate hash ID based on the caller's identity, making it more convenient for removing the current client's hash data. This is useful for cleanup operations when a player disconnects or when resetting a client's stored data. + +## Syntax +```sqf +[] call ramdb_db_fnc_hashDelete +``` + +## Parameters +None. This function automatically determines the hash ID based on the calling client. + +## Return Value +None. The operation runs synchronously to delete the hash table for the current client. + +## Examples +### Delete the current client's hash table: +```sqf +[] call ramdb_db_fnc_hashDelete; +``` + +### Delete a client's hash table from the server: +```sqf +[] remoteExecCall ["ramdb_db_fnc_hashDelete", 2, false]; +``` + +## Notes +- This function only removes the hash table for the current client/player, not all hash tables +- It's similar to `hashDeleteId` but automatically determines the appropriate ID +- Cannot be undone unless you have a backup +- Should be used during player disconnection or when resetting a player's data +- Useful for cleanup operations to prevent data buildup from disconnected players +- More convenient than `hashDeleteId` when you want to remove the calling client's data +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashDeleteId`: Removes a specific hash ID (when you need to specify the ID) +- `ramdb_db_fnc_hashDeleteField`: Removes a specific field from a hash +- `ramdb_db_fnc_hashSet`: Sets a value in the hash table +- `ramdb_db_fnc_hashGet`: Retrieves a value from the hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) diff --git a/docs/hash/hashDeleteId.md b/docs/hash/hashDeleteId.md new file mode 100644 index 0000000..5510dc8 --- /dev/null +++ b/docs/hash/hashDeleteId.md @@ -0,0 +1,69 @@ +--- +title: ArmaRAMDb - Hash Delete ID +icon: mdi:file-text-outline +excerpt: Remove a specific hash table from database. +--- + +# ramdb_db_fnc_hashDeleteId + +## Description +Removes a specific hash table from the database using its unique identifier. This function deletes all fields and values associated with the specified hash ID. Unlike the global `hashDelete` function, this operation only affects a single hash table entry. + +## Syntax +```sqf +[_key] call ramdb_db_fnc_hashDeleteId +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|--------|-------------------------------------|---------| +| `_key` | String | Identifier of the hash to be deleted | "" | + +## Return Value +None. The operation runs synchronously to delete the specified hash table. + +## Examples +### Delete a specific hash table: +```sqf +["playerStats"] call ramdb_db_fnc_hashDeleteId; +``` + +### Delete a player's hash data: +```sqf +[getPlayerUID player] call ramdb_db_fnc_hashDeleteId; +``` + +### Delete a hash table from a client: +```sqf +["vehicleData"] remoteExecCall ["ramdb_db_fnc_hashDeleteId", 2, false]; +``` + +## Notes +- This operation only removes a single hash table identified by `_key` +- Cannot be undone unless you have a backup +- Validates that the key is not empty before proceeding +- All fields associated with the hash ID are removed +- Useful for clearing player-specific data or resetting entity data +- Executes immediately without confirmation +- Logs the operation for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashDelete`: Removes all hash tables +- `ramdb_db_fnc_hashDeleteField`: Removes a specific field from a hash +- `ramdb_db_fnc_hashSetId`: Sets a value in a specific hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a value from a specific hash table +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) diff --git a/docs/hash/hashGet.md b/docs/hash/hashGet.md new file mode 100644 index 0000000..1db52c6 --- /dev/null +++ b/docs/hash/hashGet.md @@ -0,0 +1,74 @@ +--- +title: ArmaRAMDb - Hash Get +icon: mdi:file-text-outline +excerpt: Get a field value from the current client's hash table in RAMDb. +--- + +# ramdb_db_fnc_hashGet + +## Description +Retrieves the value associated with a specific field in the hash table of the current client/player. This function automatically determines the appropriate hash ID based on the caller's identity, making it more convenient than `hashGetId` which requires manually specifying an ID. It accesses hash data asynchronously and returns the result through a callback function. + +## Syntax +```sqf +[_keyField, _function, _call, _netId] call ramdb_db_fnc_hashGet +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|---------|------------------------------------------------------------|---------| +| `_keyField` | String | Name of the field in the hash to retrieve | "" | +| `_function` | String | Name of the function to receive the retrieved data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | (Optional) NetID of the player to receive the data | "" | + +## Return Value +None. The retrieved data is passed to the specified callback function asynchronously. + +## Examples +### Retrieve a player's loadout: +```sqf +["loadout", "ramdb_db_fnc_test"] call ramdb_db_fnc_hashGet; +``` + +### Retrieve data with synchronous callback: +```sqf +["playerScore", "ramdb_db_fnc_processScore", true] call ramdb_db_fnc_hashGet; +``` + +### Retrieve data and send it to a specific client: +```sqf +["loadout", "ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_hashGet", 2, false]; +``` + +## Notes +- Retrieves a value from the current client's hash table +- The data is retrieved asynchronously through the extension's callback system +- Both the field name and callback function name must be provided +- Input validation ensures both required parameters are non-empty +- When a netId is provided, the data is sent to that specific client +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- This function automatically determines which hash table to use based on the caller's identity +- Use `hashGetId` when you need to specify a particular hash table by ID +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashGetId`: Retrieves a field value from a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashGetAll`: Retrieves all fields from the current client's hash table +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table +- `ramdb_db_fnc_hashSet`: Sets a field value in the current client's hash table +- `ramdb_db_fnc_scheduler`: Processes the callback from the database extension + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashGetAll.md b/docs/hash/hashGetAll.md new file mode 100644 index 0000000..06fcebd --- /dev/null +++ b/docs/hash/hashGetAll.md @@ -0,0 +1,73 @@ +--- +title: ArmaRAMDb - Hash Get All +icon: mdi:file-text-outline +excerpt: Get all fields from the current client's hash table in RAMDb. +--- + +# ramdb_db_fnc_hashGetAll + +## Description +Retrieves all fields and values from the hash table associated with the current client/player. This function automatically determines the appropriate hash ID based on the caller's identity, making it more convenient than `hashGetAllId` which requires manually specifying an ID. It returns the entire hash table data through a callback function, allowing access to all stored key-value pairs at once. + +## Syntax +```sqf +[_function, _call, _netId] call ramdb_db_fnc_hashGetAll +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|---------|------------------------------------------------------------|---------| +| `_function` | String | Name of the function to receive the retrieved data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | (Optional) NetID of the player to receive the data | "" | + +## Return Value +None. The retrieved data is passed to the specified callback function asynchronously. + +## Examples +### Retrieve all client hash data: +```sqf +["ramdb_db_fnc_test"] call ramdb_db_fnc_hashGetAll; +``` + +### Retrieve data with synchronous callback: +```sqf +["ramdb_db_fnc_processAllData", true] call ramdb_db_fnc_hashGetAll; +``` + +### Retrieve data and send it to a specific client: +```sqf +["ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_hashGetAll", 2, false]; +``` + +## Notes +- Returns the complete hash table for the current client with all fields and values as a nested array +- The data is retrieved asynchronously through the extension's callback system +- The callback function name must be provided and is validated +- When a netId is provided, the data is sent to that specific client +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- This function automatically determines which hash table to use based on the caller's identity +- Use `hashGetAllId` when you need to specify a particular hash table by ID +- For large hash tables, retrieving all data may impact performance +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashGet`: Retrieves a specific field value from the current client's hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a specific field value from a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashSet`: Sets a field value in the current client's hash table +- `ramdb_db_fnc_scheduler`: Processes the callback from the database extension + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashGetAllId.md b/docs/hash/hashGetAllId.md new file mode 100644 index 0000000..9e4dacf --- /dev/null +++ b/docs/hash/hashGetAllId.md @@ -0,0 +1,74 @@ +--- +title: ArmaRAMDb - Hash Get All ID +icon: mdi:file-text-outline +excerpt: Get all fields and values from the hash stored at key from RAMDb. +--- + +# ramdb_db_fnc_hashGetAllId + +## Description +Retrieves all fields and values from a specific hash table identified by its key. This function returns the complete hash table data for a specific ID through a callback function, allowing access to all stored key-value pairs associated with that ID. It's particularly useful for retrieving player-specific or entity-specific hash data. + +## Syntax +```sqf +[_key, _function, _call, _netId] call ramdb_db_fnc_hashGetAllId +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|---------|------------------------------------------------------------|---------| +| `_key` | String | Identifier of the hash table to retrieve | "" | +| `_function` | String | Name of the function to receive the retrieved data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | (Optional) NetID of the player to receive the data | "" | + +## Return Value +None. The retrieved data is passed to the specified callback function asynchronously. + +## Examples +### Retrieve a player's complete hash data: +```sqf +[getPlayerUID player, "ramdb_db_fnc_test"] call ramdb_db_fnc_hashGetAllId; +``` + +### Retrieve vehicle data with synchronous callback: +```sqf +["vehicle_123", "ramdb_db_fnc_processVehicleData", true] call ramdb_db_fnc_hashGetAllId; +``` + +### Retrieve data and send it to a specific client: +```sqf +[getPlayerUID player, "ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_hashGetAllId", 2, false]; +``` + +## Notes +- Returns the complete hash table with all fields and values as a nested array +- Both the key and callback function parameters are required and validated +- The data is retrieved asynchronously through the extension's callback system +- When a netId is provided, the data is sent to that specific client +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- This function retrieves from a specific hash table identified by `_key` - use `hashGetAll` for the global hash table +- Player UIDs are commonly used as keys to store player-specific data +- For large hash tables, retrieving all data may impact performance +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashGetAll`: Retrieves all fields from the global hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a specific field value from a specific hash table +- `ramdb_db_fnc_hashGet`: Retrieves a specific field value from the global hash table +- `ramdb_db_fnc_hashSetId`: Sets a field value in a specific hash table +- `ramdb_db_fnc_scheduler`: Processes the callback from the database extension + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashGetId.md b/docs/hash/hashGetId.md new file mode 100644 index 0000000..c7bdbfd --- /dev/null +++ b/docs/hash/hashGetId.md @@ -0,0 +1,75 @@ +--- +title: ArmaRAMDb - Hash Get ID +icon: mdi:file-text-outline +excerpt: Get the value associated with field in hash stored at key from RAMDb. +--- + +# ramdb_db_fnc_hashGetId + +## Description +Retrieves the value of a specific field from a hash table identified by its key. This function allows targeted access to individual fields within a specific hash table, making it ideal for accessing particular attributes of player or entity data. The retrieved data is returned through a callback function. + +## Syntax +```sqf +[_key, _keyField, _function, _call, _netId] call ramdb_db_fnc_hashGetId +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|---------|------------------------------------------------------------|---------| +| `_key` | String | Identifier of the hash table | "" | +| `_keyField` | String | Name of the field in the hash to retrieve | "" | +| `_function` | String | Name of the function to receive the retrieved data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | (Optional) NetID of the player to receive the data | "" | + +## Return Value +None. The retrieved data is passed to the specified callback function asynchronously. + +## Examples +### Retrieve a player's loadout field: +```sqf +[getPlayerUID player, "loadout", "ramdb_db_fnc_test"] call ramdb_db_fnc_hashGetId; +``` + +### Retrieve a specific vehicle property with synchronous callback: +```sqf +["vehicle_123", "fuel", "ramdb_db_fnc_processFuelData", true] call ramdb_db_fnc_hashGetId; +``` + +### Retrieve data and send it to a specific client: +```sqf +[getPlayerUID player, "stats", "ramdb_db_fnc_test", false, netId player] remoteExecCall ["ramdb_db_fnc_hashGetId", 2, false]; +``` + +## Notes +- Retrieves a single field value from a specific hash table +- All three primary parameters (key, keyField, and function) are required and validated +- The data is retrieved asynchronously through the extension's callback system +- When a netId is provided, the data is sent to that specific client +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- This function targets both a specific hash table (`_key`) and a specific field (`_keyField`) +- More efficient than retrieving all hash fields when only one is needed +- Player UIDs are commonly used as keys to store player-specific data +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashGet`: Retrieves a field value from the global hash table +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table +- `ramdb_db_fnc_hashGetAll`: Retrieves all fields from the global hash table +- `ramdb_db_fnc_hashSetId`: Sets a field value in a specific hash table +- `ramdb_db_fnc_scheduler`: Processes the callback from the database extension + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashRemove.md b/docs/hash/hashRemove.md new file mode 100644 index 0000000..017b1f4 --- /dev/null +++ b/docs/hash/hashRemove.md @@ -0,0 +1,67 @@ +--- +title: ArmaRAMDb - Hash Remove +icon: mdi:file-text-outline +excerpt: Remove a field from the current client's hash table. +--- + +# ramdb_db_fnc_hashRemove + +## Description +Removes a specific field from the hash table associated with the current client/player. This function automatically determines the appropriate hash ID based on the caller's identity, making it more convenient than `hashRemoveId` which requires manually specifying an ID. It deletes a single field and its associated value without affecting other fields in the client's hash table. + +## Syntax +```sqf +[_keyField] call ramdb_db_fnc_hashRemove +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|--------|-------------------------------------|---------| +| `_keyField` | String | Name of the field to be removed | "" | + +## Return Value +None. The operation runs synchronously to remove the field. + +## Examples +### Remove a specific field: +```sqf +["loadout"] call ramdb_db_fnc_hashRemove; +``` + +### Remove a field remotely: +```sqf +["playerSettings"] remoteExecCall ["ramdb_db_fnc_hashRemove", 2, false]; +``` + +## Notes +- Only removes a single field from the current client's hash table +- Validates that the key field parameter is not empty before proceeding +- Does not affect other fields in the hash table +- If the field doesn't exist, the operation has no effect +- This function automatically determines which hash table to use based on the caller's identity +- Use `hashRemoveId` when you need to specify a particular hash table by ID +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashRemoveId`: Removes a specific field from a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashDelete`: Removes the current client's hash table +- `ramdb_db_fnc_hashDeleteId`: Removes a specific hash table +- `ramdb_db_fnc_hashSet`: Sets a field value in the current client's hash table +- `ramdb_db_fnc_hashGet`: Retrieves a field value from the current client's hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Remove](hashRemove) | +[Hash Remove ID](hashRemoveId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) diff --git a/docs/hash/hashRemoveId.md b/docs/hash/hashRemoveId.md new file mode 100644 index 0000000..0ce83b6 --- /dev/null +++ b/docs/hash/hashRemoveId.md @@ -0,0 +1,72 @@ +--- +title: ArmaRAMDb - Hash Remove ID +icon: mdi:file-text-outline +excerpt: Remove a field from a specific hash table. +--- + +# ramdb_db_fnc_hashRemoveId + +## Description +Removes a specific field from a specific hash table identified by its key. This function deletes a single field and its associated value from a targeted hash table without affecting other fields. It's ideal for managing player-specific or entity-specific data when only certain attributes need to be removed. + +## Syntax +```sqf +[_key, _keyField] call ramdb_db_fnc_hashRemoveId +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|--------|----------------------------------------------|---------| +| `_key` | String | Identifier of the hash table | "" | +| `_keyField` | String | Name of the field in the hash to be removed | "" | + +## Return Value +None. The operation runs synchronously to remove the field. + +## Examples +### Remove a player's loadout field: +```sqf +[getPlayerUID player, "loadout"] call ramdb_db_fnc_hashRemoveId; +``` + +### Remove a vehicle property: +```sqf +["vehicle_123", "cargo"] call ramdb_db_fnc_hashRemoveId; +``` + +### Remove a field remotely: +```sqf +[getPlayerUID player, "stats"] remoteExecCall ["ramdb_db_fnc_hashRemoveId", 2, false]; +``` + +## Notes +- Removes a single field from a specific hash table identified by `_key` +- Both the key and key field parameters are required and validated +- Does not affect other fields in the hash table +- If the hash table or field doesn't exist, the operation has no effect +- Player UIDs are commonly used as keys to identify player-specific hash tables +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashRemove`: Removes a specific field from the global hash table +- `ramdb_db_fnc_hashDeleteId`: Removes an entire specific hash table +- `ramdb_db_fnc_hashDelete`: Removes all hash tables +- `ramdb_db_fnc_hashSetId`: Sets a field value in a specific hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a field value from a specific hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Remove](hashRemove) | +[Hash Remove ID](hashRemoveId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) diff --git a/docs/hash/hashSet.md b/docs/hash/hashSet.md new file mode 100644 index 0000000..ed17ff0 --- /dev/null +++ b/docs/hash/hashSet.md @@ -0,0 +1,72 @@ +--- +title: ArmaRAMDb - Hash Set +icon: mdi:file-text-outline +excerpt: Set a field value in the current client's hash table in RAMDb. +--- + +# ramdb_db_fnc_hashSet + +## Description +Sets the value of a specified field in the hash table associated with the current client/player. This function automatically determines the appropriate hash ID based on the caller's identity, making it more convenient than `hashSetId` which requires manually specifying an ID. It allows storing various data types (arrays, strings, numbers, or booleans) in a field of the client-specific hash structure. + +## Syntax +```sqf +[_keyField, _data] call ramdb_db_fnc_hashSet +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|----------------------------------|-------------------------------------------|---------| +| `_keyField` | String | Name of the field in the hash to set | "" | +| `_data` | Array, String, Number, or Boolean| The value to store in the hash field | [] | + +## Return Value +None. The operation runs synchronously to store the data. + +## Examples +### Store a player's loadout: +```sqf +["loadout", [getUnitLoadout player]] call ramdb_db_fnc_hashSet; +``` + +### Store player preferences: +```sqf +["settings", [true, 30, "normal"]] call ramdb_db_fnc_hashSet; +``` + +### Store data from a client: +```sqf +["clientInfo", [name player, getPlayerUID player]] remoteExecCall ["ramdb_db_fnc_hashSet", 2, false]; +``` + +## Notes +- Stores a single field-value pair in the current client's hash table +- Both the field name and data parameters are required and validated +- If the field already exists, its value will be overwritten +- Supports various data types: arrays, strings, numbers, and booleans +- This function automatically determines which hash table to use based on the caller's identity +- Use `hashSetId` when you need to specify a particular hash table by ID +- Complex data structures should be serialized into arrays +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashSetId`: Sets a field value in a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashGet`: Retrieves a field value from the current client's hash table +- `ramdb_db_fnc_hashGetAll`: Retrieves all fields from the current client's hash table +- `ramdb_db_fnc_hashSetBulk`: Sets multiple fields in the current client's hash table +- `ramdb_db_fnc_hashDelete`: Removes the current client's hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashSetBulk.md b/docs/hash/hashSetBulk.md new file mode 100644 index 0000000..892a0ca --- /dev/null +++ b/docs/hash/hashSetBulk.md @@ -0,0 +1,72 @@ +--- +title: ArmaRAMDb - Hash Set Bulk +icon: mdi:file-text-outline +excerpt: Set multiple fields in the current client's hash table in RAMDb. +--- + +# ramdb_db_fnc_hashSetBulk + +## Description +Sets multiple field-value pairs in the hash table associated with the current client/player in a single operation. This function automatically determines the appropriate hash ID based on the caller's identity, making it more convenient than `hashSetIdBulk` which requires manually specifying an ID. It allows efficiently storing multiple related fields at once, reducing the number of separate database calls required. + +## Syntax +```sqf +[_data] call ramdb_db_fnc_hashSetBulk +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|-------|---------------------------------------------------------|---------| +| `_data` | Array | Array of alternating field names and values to store | [] | + +## Return Value +None. The operation runs synchronously to store all the data. + +## Examples +### Store player loadout and position: +```sqf +[["loadout", [getUnitLoadout player], "position", [getPosASLVisual player]]] call ramdb_db_fnc_hashSetBulk; +``` + +### Store multiple player settings: +```sqf +[["difficulty", ["regular"], "respawn", [true], "tickets", [500]]] call ramdb_db_fnc_hashSetBulk; +``` + +### Store player data from a client: +```sqf +[["name", [name player], "uid", [getPlayerUID player], "score", [score player]]] remoteExecCall ["ramdb_db_fnc_hashSetBulk", 2, false]; +``` + +## Notes +- The data array must be structured as alternating field names and values: `[field1, value1, field2, value2, ...]` +- Each field name must be a string +- Values can be arrays, strings, numbers, or booleans +- All field-value pairs are stored in a single database operation +- If any of the fields already exist, their values will be overwritten +- This function automatically determines which hash table to use based on the caller's identity +- Use `hashSetIdBulk` when you need to specify a particular hash table by ID +- More efficient than multiple individual `hashSet` calls when setting several fields +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashSet`: Sets a single field value in the current client's hash table +- `ramdb_db_fnc_hashSetIdBulk`: Sets multiple field-value pairs in a specific hash table (when you need to specify the ID) +- `ramdb_db_fnc_hashGetAll`: Retrieves all fields from the current client's hash table +- `ramdb_db_fnc_hashGet`: Retrieves a specific field value from the current client's hash table +- `ramdb_db_fnc_hashDelete`: Removes the current client's hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashSetId.md b/docs/hash/hashSetId.md new file mode 100644 index 0000000..f36ccdc --- /dev/null +++ b/docs/hash/hashSetId.md @@ -0,0 +1,73 @@ +--- +title: ArmaRAMDb - Hash Set ID +icon: mdi:file-text-outline +excerpt: Set the specified field to the respective value in the hash stored at key from RAMDb. +--- + +# ramdb_db_fnc_hashSetId + +## Description +Sets the value of a specified field in a specific hash table identified by its key. This function allows storing various data types (arrays, strings, numbers, or booleans) in a targeted hash table, making it ideal for player-specific or entity-specific data storage. It provides a way to organize related data under a common identifier. + +## Syntax +```sqf +[_key, _keyField, _data] call ramdb_db_fnc_hashSetId +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|----------------------------------|--------------------------------------------|---------| +| `_key` | String | Identifier of the hash table | "" | +| `_keyField` | String | Name of the field in the hash to set | "" | +| `_data` | Array, String, Number, or Boolean| The value to store in the hash field | [] | + +## Return Value +None. The operation runs synchronously to store the data. + +## Examples +### Store a player's loadout under their UID: +```sqf +[getPlayerUID player, "loadout", [getUnitLoadout player]] call ramdb_db_fnc_hashSetId; +``` + +### Store vehicle data: +```sqf +["vehicle_123", "status", [true, 100, 75, "active"]] call ramdb_db_fnc_hashSetId; +``` + +### Store player data from a client: +```sqf +[getPlayerUID player, "stats", [rank player, score player, name player]] remoteExecCall ["ramdb_db_fnc_hashSetId", 2, false]; +``` + +## Notes +- Stores a single field-value pair in a specific hash table identified by `_key` +- All three parameters (key, keyField, and data) are required and validated +- If the hash table doesn't exist, it will be created automatically +- If the field already exists in the hash table, its value will be overwritten +- Supports various data types: arrays, strings, numbers, and booleans +- Player UIDs are commonly used as keys to store player-specific data +- Complex data structures should be serialized into arrays +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashSet`: Sets a field value in the global hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a field value from a specific hash table +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table +- `ramdb_db_fnc_hashSetIdBulk`: Sets multiple field-value pairs in multiple hash tables +- `ramdb_db_fnc_hashDeleteId`: Removes a specific hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/hash/hashSetIdBulk.md b/docs/hash/hashSetIdBulk.md new file mode 100644 index 0000000..fdf5b77 --- /dev/null +++ b/docs/hash/hashSetIdBulk.md @@ -0,0 +1,73 @@ +--- +title: ArmaRAMDb - Hash Set ID Bulk +icon: mdi:file-text-outline +excerpt: Set the specified fields to their respective values in the hash stored at key from RAMDb. +--- + +# ramdb_db_fnc_hashSetIdBulk + +## Description +Sets multiple field-value pairs in a specific hash table identified by its key in a single operation. This function allows efficiently storing multiple related fields at once for a specific identifier, reducing the number of separate database calls required. It's ideal for saving a collection of player-specific or entity-specific data. + +## Syntax +```sqf +[_data] call ramdb_db_fnc_hashSetIdBulk +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|-------|--------------------------------------------------------------------|---------| +| `_data` | Array | Array with key followed by alternating field names and values | [] | + +## Return Value +None. The operation runs synchronously to store all the data. + +## Examples +### Store player loadout and position: +```sqf +[[getPlayerUID player, "loadout", [getUnitLoadout player], "position", [getPosASLVisual player]]] call ramdb_db_fnc_hashSetIdBulk; +``` + +### Store multiple vehicle properties: +```sqf +[["vehicle_123", "fuel", [0.75], "damage", [0.2], "crew", [["player1", "player2"]]]] call ramdb_db_fnc_hashSetIdBulk; +``` + +### Store player data from a client: +```sqf +[[getPlayerUID player, "stats", [score player], "inventory", [getAllGear player]]] remoteExecCall ["ramdb_db_fnc_hashSetIdBulk", 2, false]; +``` + +## Notes +- The data array must be structured with the key first, followed by alternating field names and values: `[key, field1, value1, field2, value2, ...]` +- The key must be a string that identifies the specific hash table +- Each field name must be a string +- Values can be arrays, strings, numbers, or booleans +- All field-value pairs are stored in a single database operation +- If the hash table doesn't exist, it will be created automatically +- If any of the fields already exist in the hash table, their values will be overwritten +- More efficient than multiple individual `hashSetId` calls when setting several fields +- Player UIDs are commonly used as keys to store player-specific data +- The operation is executed immediately and synchronously +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_hashSetId`: Sets a single field value in a specific hash table +- `ramdb_db_fnc_hashSetBulk`: Sets multiple field-value pairs in the global hash table +- `ramdb_db_fnc_hashGetAllId`: Retrieves all fields from a specific hash table +- `ramdb_db_fnc_hashGetId`: Retrieves a specific field value from a specific hash table +- `ramdb_db_fnc_hashDeleteId`: Removes a specific hash table + +## Links + +[Hash Delete](hashDelete) | +[Hash Delete Field](hashDeleteField) | +[Hash Delete ID](hashDeleteId) | +[Hash Get](hashGet) | +[Hash Get All](hashGetAll) | +[Hash Get All ID](hashGetAllId) | +[Hash Get ID](hashGetId) | +[Hash Set](hashSet) | +[Hash Set Bulk](hashSetBulk) | +[Hash Set ID](hashSetId) | +[Hash Set ID Bulk](hashSetIdBulk) \ No newline at end of file diff --git a/docs/list/listAdd.md b/docs/list/listAdd.md new file mode 100644 index 0000000..29fe217 --- /dev/null +++ b/docs/list/listAdd.md @@ -0,0 +1,66 @@ +--- +title: ArmaRAMDb - List Add +icon: mdi:file-text-outline +excerpt: Add element to list stored at key from RAMDb. +--- + +# ramdb_db_fnc_listAdd + +## Description +Adds an element to a list stored in the database under the specified key. This function appends values to an existing list or creates a new list if it doesn't exist. It's particularly useful for logging, event tracking, or maintaining collections of data that grow over time. + +## Syntax +```sqf +[_key, _data] call ramdb_db_fnc_listAdd +``` + +## Parameters +| Parameter | Type | Description | Default | +|-----------|----------------------------------|------------------------------------------|---------| +| `_key` | String | Name of the list to add the element to | "" | +| `_data` | Array, String, Number, or Boolean| The value to insert into the list | [] | + +## Return Value +None. The operation runs synchronously to add the element to the list. + +## Examples +### Add an event log entry: +```sqf +["events", ["Server state saved to DB " + systemTimeUTC]] call ramdb_db_fnc_listAdd; +``` + +### Add a player message: +```sqf +["messages", [name player + ": " + _messageText]] call ramdb_db_fnc_listAdd; +``` + +### Add data from a client: +```sqf +["playerActions", [getPlayerUID player, name player, "logged in"]] remoteExecCall ["ramdb_db_fnc_listAdd", 2, false]; +``` + +## Notes +- Elements are added to the end of the list in the order they are inserted +- If the list doesn't exist, it will be created automatically +- Both the key and data parameters are required and validated +- Lists can store various data types (arrays, strings, numbers, or booleans) +- Useful for maintaining a history of events, logs, or sequential data +- The operation is executed immediately and synchronously +- New elements are always added to the end of the list +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_listGet`: Retrieves a specific element from a list +- `ramdb_db_fnc_listLoad`: Retrieves a range of elements from a list +- `ramdb_db_fnc_listSet`: Replaces a specific element in a list +- `ramdb_db_fnc_listRemove`: Removes a specific element from a list +- `ramdb_db_fnc_listDelete`: Deletes an entire list + +## Links + +[List Add](listAdd) | +[List Delete](listDelete) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) \ No newline at end of file diff --git a/docs/list/listDelete.md b/docs/list/listDelete.md new file mode 100644 index 0000000..23b937b --- /dev/null +++ b/docs/list/listDelete.md @@ -0,0 +1,71 @@ +--- +title: ArmaRAMDb - List Delete +icon: mdi:file-text-outline +excerpt: Delete an entire list stored at a key from RAMDb. +--- + +# ramdb_db_fnc_listDelete + +## Description + +Completely removes a list and all its elements stored at a specified key from the RAMDb database. This function provides a way to delete entire collections of data at once, rather than removing individual elements. It is useful for cleaning up obsolete data, resetting collections, or removing temporary lists that are no longer needed. + +## Syntax + +```sqf +[_key] call ramdb_db_fnc_listDelete +``` + +## Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| _key | String | The key identifying the list to be deleted | "" | + +## Return Value + +None. The operation runs synchronously to delete the list immediately. + +## Examples + +**Delete an event log:** +```sqf +["eventLog"] call ramdb_db_fnc_listDelete; +``` + +**Remove temporary mission data:** +```sqf +["tempMissionData"] call ramdb_db_fnc_listDelete; +``` + +**Delete a list in multiplayer:** +```sqf +["sharedTempData"] remoteExecCall ["ramdb_db_fnc_listDelete", 2, false]; +``` + +## Notes + +- This function deletes the entire list and all its elements associated with the specified key. +- Unlike `listRemove`, which removes a single element by index, this function removes the complete list structure. +- The `_key` parameter must be a non-empty string, otherwise the function will exit without performing any action. +- Once a list is deleted, it cannot be recovered unless you have previously saved or backed up the data. +- If you need to selectively remove elements while preserving the list structure, use `ramdb_db_fnc_listRemove` instead. +- The deletion operation is permanent and cannot be undone. +- All list operations are logged for debugging purposes. + +## Related Functions + +- [ramdb_db_fnc_listAdd](listAdd) +- [ramdb_db_fnc_listGet](listGet) +- [ramdb_db_fnc_listLoad](listLoad) +- [ramdb_db_fnc_listRemove](listRemove) +- [ramdb_db_fnc_listSet](listSet) + +## Links + +[List Add](listAdd) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) | +[List Delete](listDelete) diff --git a/docs/list/listGet.md b/docs/list/listGet.md new file mode 100644 index 0000000..718d0e2 --- /dev/null +++ b/docs/list/listGet.md @@ -0,0 +1,70 @@ +--- +title: ArmaRAMDb - List Get +icon: mdi:file-text-outline +excerpt: Get element of list stored at key from RAMDb. +--- + +# ramdb_db_fnc_listGet + +## Description +Retrieves a specific element from a list stored in the database by its index. This function accesses a single item from a list using its position number and returns the data through a callback function. It's useful for accessing individual pieces of data from a sequence without retrieving the entire list. + +## Syntax +```sqf +[_key, _index, _function, _call, _netId] call ramdb_db_fnc_listGet +``` + +## Parameters +| Parameter | Type | Description | Default | +|-------------|---------|------------------------------------------------------------|---------| +| `_key` | String | Name of the list | "" | +| `_index` | Number | Index position of the element to retrieve (0-based) | -1 | +| `_function` | String | Name of the function to receive the retrieved data | "" | +| `_call` | Boolean | Whether to call the function directly (true) or spawn (false) | false | +| `_netId` | String | (Optional) NetID of the player to receive the data | "" | + +## Return Value +None. The retrieved data is passed to the specified callback function asynchronously. + +## Examples +### Retrieve a specific event log entry: +```sqf +["events", 0, "ramdb_db_fnc_test"] call ramdb_db_fnc_listGet; +``` + +### Retrieve data with synchronous callback: +```sqf +["messages", 5, "ramdb_db_fnc_processMessage", true] call ramdb_db_fnc_listGet; +``` + +### Retrieve data and send it to a specific client: +```sqf +["notifications", 0, "ramdb_db_fnc_displayNotification", false, netId player] remoteExecCall ["ramdb_db_fnc_listGet", 2, false]; +``` + +## Notes +- Retrieves a single element from a list by its index position +- The key, index, and function parameters are required and validated +- Index is zero-based (the first element is at index 0) +- If the index is out of bounds or the list doesn't exist, no data will be returned +- The data is retrieved asynchronously through the extension's callback system +- When a netId is provided, the data is sent to that specific client +- The `_call` parameter determines whether the function is called directly (synchronous) or spawned (asynchronous) +- For retrieving multiple elements, use `listLoad` instead +- All operations are logged for debugging purposes + +## Related Functions +- `ramdb_db_fnc_listAdd`: Adds an element to a list +- `ramdb_db_fnc_listLoad`: Retrieves a range of elements from a list +- `ramdb_db_fnc_listSet`: Replaces a specific element in a list +- `ramdb_db_fnc_listRemove`: Removes a specific element from a list +- `ramdb_db_fnc_scheduler`: Processes the callback from the database extension + +## Links + +[List Add](listAdd) | +[List Delete](listDelete) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) \ No newline at end of file diff --git a/docs/list/listLoad.md b/docs/list/listLoad.md new file mode 100644 index 0000000..aec665c --- /dev/null +++ b/docs/list/listLoad.md @@ -0,0 +1,74 @@ +--- +title: ArmaRAMDb - List Load +icon: mdi:file-text-outline +excerpt: Get all elements of a list stored at a key from RAMDb. +--- + +# ramdb_db_fnc_listLoad + +## Description + +Retrieves all elements of a list stored at a specified key from the RAMDb database. This function is useful when you need to access the complete list data rather than individual elements, allowing operations on the entire dataset. The retrieved data is passed to a callback function for processing. + +## Syntax + +```sqf +[_key, _function, _call, _netId] call ramdb_db_fnc_listLoad +``` + +## Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| _key | String | The key identifying the list to be retrieved | "" | +| _function | String | The name of the function that will receive the retrieved data | "" | +| _call | Boolean | Whether to call the function in an unscheduled environment | false | +| _netId | String | The NetID of the target to return data from the function (multiplayer only) | "" | + +## Return Value + +No value is returned directly. The retrieved list data is passed to the specified callback function asynchronously. + +## Examples + +**Retrieve all event logs:** +```sqf +["events", "myProject_fnc_processEventLogs"] call ramdb_db_fnc_listLoad; +``` + +**Retrieve a player list with synchronous callback:** +```sqf +["playerList", "myProject_fnc_processPlayerList", true] call ramdb_db_fnc_listLoad; +``` + +**Send mission data to a specific client:** +```sqf +["missionData", "myProject_fnc_processMissionData", false, netId player] remoteExecCall ["ramdb_db_fnc_listLoad", 2, false]; +``` + +## Notes + +- This function retrieves the entire list stored at the specified key, making it useful when you need to process multiple elements together. +- Both the `_key` and `_function` parameters are required. The function will exit without action if either is empty. +- The retrieved data is processed asynchronously through the scheduler system and passed to the specified callback function. +- For multiplayer scenarios, you can specify a target client using the `_netId` parameter to send the retrieved data to that specific client. +- The `_call` parameter determines whether the callback function is executed in an unscheduled environment (true) or scheduled environment (false). +- This function uses the underlying "listrng" extension with a range from 0 to -1, which retrieves all elements in the list. +- All list operations are logged for debugging purposes. + +## Related Functions + +- [ramdb_db_fnc_listAdd](listAdd) +- [ramdb_db_fnc_listGet](listGet) +- [ramdb_db_fnc_listSet](listSet) +- [ramdb_db_fnc_listRemove](listRemove) +- [ramdb_db_fnc_listDelete](listDelete) + +## Links + +[List Add](listAdd) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) | +[List Delete](listDelete) \ No newline at end of file diff --git a/docs/list/listRemove.md b/docs/list/listRemove.md new file mode 100644 index 0000000..8b946f4 --- /dev/null +++ b/docs/list/listRemove.md @@ -0,0 +1,72 @@ +--- +title: ArmaRAMDb - List Remove +icon: mdi:file-text-outline +excerpt: Remove an element from a list stored at a key in RAMDb. +--- + +# ramdb_db_fnc_listRemove + +## Description + +Removes a specific element from a list stored at a specified key in the RAMDb database. This function allows for precise control over list content by targeting individual elements by their index, without affecting other elements in the list. This is particularly useful for removing outdated or no longer needed entries. + +## Syntax + +```sqf +[_key, _index] call ramdb_db_fnc_listRemove +``` + +## Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| _key | String | The key identifying the list from which to remove an element | "" | +| _index | Number | The zero-based index of the element to remove from the list | -1 | + +## Return Value + +None. The operation runs synchronously to remove the element immediately. + +## Examples + +**Remove the first element from an event log:** +```sqf +["eventLog", 0] call ramdb_db_fnc_listRemove; +``` + +**Remove a specific player record:** +```sqf +["playerRecords", 5] call ramdb_db_fnc_listRemove; +``` + +**Remove an element from a multiplayer environment:** +```sqf +["sharedData", 2] remoteExecCall ["ramdb_db_fnc_listRemove", 2, false]; +``` + +## Notes + +- This function removes only the element at the specified index. All other elements remain unchanged, though their indices may shift. +- The index is zero-based, meaning the first element is at index 0, the second at index 1, and so on. +- If an invalid index is provided (negative or exceeding the list length), the operation will not remove any elements. +- The `_key` parameter must be a non-empty string, otherwise the function will exit without performing any action. +- After removing an element, all subsequent elements shift down by one index to maintain a contiguous list. +- The removal operation is permanent and cannot be undone except by re-adding the element. +- All list operations are logged for debugging purposes. + +## Related Functions + +- [ramdb_db_fnc_listAdd](listAdd) +- [ramdb_db_fnc_listGet](listGet) +- [ramdb_db_fnc_listLoad](listLoad) +- [ramdb_db_fnc_listSet](listSet) +- [ramdb_db_fnc_listDelete](listDelete) + +## Links + +[List Add](listAdd) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) | +[List Delete](listDelete) \ No newline at end of file diff --git a/docs/list/listSet.md b/docs/list/listSet.md new file mode 100644 index 0000000..a4d2a75 --- /dev/null +++ b/docs/list/listSet.md @@ -0,0 +1,73 @@ +--- +title: ArmaRAMDb - List Set +icon: mdi:file-text-outline +excerpt: Set an element in a list stored at a key in RAMDb. +--- + +# ramdb_db_fnc_listSet + +## Description + +Updates or sets the value of a specific element at a given index in a list stored at a specified key in the RAMDb database. This function allows for precise modification of list contents by targeting individual elements without affecting other elements in the list. It is particularly useful for updating record information, modifying configuration data, or correcting entries. + +## Syntax + +```sqf +[_key, _index, _data] call ramdb_db_fnc_listSet +``` + +## Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| _key | String | The key identifying the list in which to set an element | "" | +| _index | Number | The zero-based index of the element to set in the list | -1 | +| _data | Array/String/Number/Boolean | The value to set at the specified index | [] | + +## Return Value + +None. The operation runs synchronously to update the element immediately. + +## Examples + +**Update an event log entry:** +```sqf +["eventLog", 0, ["Updated event information"]] call ramdb_db_fnc_listSet; +``` + +**Modify player statistics:** +```sqf +["playerStats", 3, [name player, score player, alive player]] call ramdb_db_fnc_listSet; +``` + +**Update configuration in multiplayer:** +```sqf +["missionConfig", 1, ["difficulty", "veteran"]] remoteExecCall ["ramdb_db_fnc_listSet", 2, false]; +``` + +## Notes + +- This function updates only the element at the specified index. All other elements remain unchanged. +- The index is zero-based, meaning the first element is at index 0, the second at index 1, and so on. +- If the specified index does not exist in the list, the operation may fail or have no effect. +- Both the `_key` parameter and `_data` parameter must be valid (non-empty string for key, non-nil for data), otherwise the function will exit without performing any action. +- The function supports various data types, including arrays, strings, numbers, and booleans. +- The update operation is permanent and will overwrite any previous value at the specified index. +- All list operations are logged for debugging purposes. + +## Related Functions + +- [ramdb_db_fnc_listAdd](listAdd) +- [ramdb_db_fnc_listGet](listGet) +- [ramdb_db_fnc_listLoad](listLoad) +- [ramdb_db_fnc_listRemove](listRemove) +- [ramdb_db_fnc_listDelete](listDelete) + +## Links + +[List Add](listAdd) | +[List Get](listGet) | +[List Load](listLoad) | +[List Remove](listRemove) | +[List Set](listSet) | +[List Delete](listDelete) \ No newline at end of file