Data Persistence

From ALFA
Jump to: navigation, search

ALFA uses MySQL for data persistence, as well as NWN2's default Campaign Database. This article focuses on MySQL.

The following functions are available for use in scripts to store persistent data (available across server resets). Be sure to delete any data that is no longer needed or to set expiration on data that you know will only be relevant for a fixed duration. This will help keep the size of the database down and minimize latency on queries (that can lag the game). These functions are provided by the acr_db_persist_i.nss.

General Functions

void ACR_SQLQuery( string sSQL ) 
This function executes an SQL statement.
sSQL: The SQL string to execute
Returns: Nothing
string ACR_SQLEncodeSpecialChars( string sString ) 
Handles special characters (like ') for database storage. Problems can arise with SQL commands if variables or values have single or double quotes in their names. This function encodes these quotes so the underlying database can safely store them.
sString: The string to encode
Returns: Encoded string
int ACR_SQLGetAffectedRows() 
Returns the number of rows that were affected by the last INSERT, UPDATE, or DELETE operation.
Returns: Number of rows affected
void ACR_DeletePersistentVariable( object oObject, string sVarName ) 
Deletes a persistent record.
oObject: The object for which the data is being deleted
sVarName: The unique variable name

Conversion

string ACR_LocationToString( location lLocation )
location ACR_StringToLocation( string sLocation )
string ACR_VectorToString( vector vVector )
vector ACR_StringToVector( string sVector )

Retrieving Data

int ACR_SQLFetch( string mode = " " ) 
Retrieves the next row of the result set returned by the most recent query. Call this before using ACR_SQLGetData().
mode: Selects a result set in a multiset result. Leave the parameter empty to advance to the next row in the resultset. Pass "NEXT" as parameter to fetch the first row of the next resultset.
Returns: SQL_SUCCESS if there is a row, SQL_ERROR if there are no more rows.
string ACR_SQLGetData( int nCol = 0 ) 
Retrieves the data in a specific column within the current row of the result set.
nCol: The index of the column to retrieve (max column size 65K) in the result row
Returns: The data in column nCol
string ACR_GetPersistentString( object oObject, string sVarName ) 
Retrieves a persistent string.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or an empty string on error.
int ACR_GetPersistentInt( object oObject, string sVarName ) 
Retrieves a persistent int.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or 0 on error.
float ACR_GetPersistentFloat( object oObject, string sVarName ) 
Retrieves a persistent float.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or 0.0 on error.
location ACR_GetPersistentLocation( object oObject, string sVarname ) 
Retrieves a persistent location.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or <"",0,0,0> on error.
vector ACR_GetPersistentVector( object oObject, string sVarName ) 
Retrieves a persistent vector.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or <0,0,0> on error
object ACR_GetPersistentObject( object oObject, string sVarName ) 
Retrieves a persistent object.
oObject: The object for which the data is being retrieved
sVarName: The unique variable name
Returns: The value stored, or OBJECT_INVALID on error.
string ACR_GetPCPublicCDKey( object oPC ) 
Retrieves the CD Key of the player
oPC: player whose CD Key to retrieve
Returns: oPC's CD Key
int ACR_GetCharacterID( object oPC ) 
Retrieves the Character ID of the player character (useful for direct queries using ACR_SQLQuery()).
oPC: player whose character ID to retrieve
Returns: oPC's character ID, or 0 on error.

Storing Data

void ACR_SetPersistentString( object oObject, string sVarName, string sValue, int iExpiration = 0 ) 
Stores a persistent string.
oObject: The object for which the data is being stored
sVarName: The unique variable name
sValue: The value to record
iExpiration (optional): The number of days the persistent variable should be kept in database (default: 0=forever)
Returns: Nothing
void ACR_SetPersistentInt( object oObject, string sVarName, int iValue, int iExpiration = 0 ) 
Stores a persistent integer.
oObject: The object for which the data is being stored
sVarName: The unique variable name
iValue: The value to record
iExpiration (optional): The number of days the persistent variable should be kept in database (default: 0=forever)
Returns: Nothing
void ACR_SetPersistentFloat( object oObject, string sVarName, float fValue, int iExpiration = 0 ) 
Stores a persistent float.
oObject: The object for which the data is being stored
sVarName: The unique variable name
fValue: The value to record
iExpiration (optional): The number of days the persistent variable should be kept in database (default: 0=forever)
Returns: Nothing
void ACR_SetPersistentLocation( object oObject, string sVarName, location lValue, int iExpiration = 0 ) 
Stores a persistent location.
oObject: The object for which the data is being stored
sVarName: The unique variable name
lValue: The value to record
iExpiration (optional): The number of days the persistent variable should be kept in database (default: 0=forever)
Returns: Nothing
void ACR_SetPersistentVector( object oObject, string sVarName, vector vValue, int iExpiration = 0 ) 
Stores a persistent vector.
oObject: The object for which the data is being stored
sVarName: The unique variable name
vValue: The value to record
iExpiration (optional): The number of days the persistent variable should be kept in database (default: 0=forever)
Returns: Nothing