EDI Native API

Extensions

Edi	Database structure.
EdiField	EDI Record field structure.
EdiGrid	Grid structure.
EdiRec	Database record structure.
EdiService	Edi service control structure.

Functions

int	edRemoveColumn(Edi edi, cchar tableName, cchar *columnName)
	Remove a column from a table.
int	ediAddColumn(Edi edi, cchar tableName, cchar *columnName, int type, int flags)
	Add a column to a table.
void	ediAddFieldError(struct EdiRec rec, cchar field, cchar *fmt, ...)
	Add a field error message.
int	ediAddIndex(Edi edi, cchar tableName, cchar columnName, cchar indexName)
	Add an index to a table.
void	ediAddProvider(struct EdiProvider *provider)
	Add a database provider.
int	ediAddTable(Edi edi, cchar tableName)
	Add a table to a database.
int	ediAddValidation(Edi edi, cchar name, cchar tableName, cchar columnName, cvoid *data)
	Add a validation.
int	ediChangeColumn(Edi edi, cchar tableName, cchar *columnName, int type, int flags)
	Change a column schema definition.
Edi*	ediClone(Edi *edi)
	Clone a database.
EdiGrid*	ediCloneGrid(EdiGrid *grid)
	Clone a grid.
void	ediClose(Edi *edi)
	Close a database.
EdiGrid*	ediCreateBareGrid(Edi edi, cchar tableName, int nrows)
	Create a bare grid.
EdiRec*	ediCreateBareRec(Edi edi, cchar tableName, int nfields)
	Create a bare record.
EdiRec*	ediCreateRec(Edi edi, cchar tableName)
	Create a record.
EdiService*	ediCreateService()
	Create the EDI service.
void	ediDefineMigration(struct Edi *edi, EdiMigration forw, EdiMigration back)
	Define migration callbacks.
void	ediDefineValidation(cchar *name, EdiValidationProc vfn)
	Define a field validation procedure.
int	ediDelete(Edi edi, cchar path)
	Delete the database at the given path.
EdiGrid*	ediFilterGridFields(EdiGrid grid, cchar fields, int include)
	Filter the fields of a grid.
EdiRec*	ediFilterRecFields(EdiRec rec, cchar fields, int include)
	Filter the fields of a record.
cchar*	ediFormatField(cchar fmt, EdiField fp)
	Format a field value.
int	ediGetColumnSchema(Edi edi, cchar tableName, cchar columnName, int type, int flags, int cid)
	Get the column schema.
MprList*	ediGetColumns(Edi edi, cchar tableName)
	Get a list of column names.
EdiField*	ediGetField(EdiRec rec, cchar fieldName)
	Get a record field.
int	ediGetFieldType(EdiRec rec, cchar fieldName)
	Get the data type of a record field.
cchar*	ediGetFieldValue(EdiRec rec, cchar fieldName)
	Get a field value.
MprList*	ediGetGridColumns(EdiGrid *grid)
	Get a list of grid column names.
cchar*	ediGetGridSchemaAsJson(EdiGrid *grid)
	Get the schema for a grid and format as JSON.
EdiField*	ediGetNextField(EdiRec rec, EdiField fp, int offset)
	Get the next field in a record This is used as an iterator.
EdiRec*	ediGetNextRec(EdiGrid grid, EdiRec rec)
	Get the next record in a grid This is used as an iterator.
MprHash*	ediGetRecErrors(EdiRec *rec)
	Get record validation errors.
cchar*	ediGetRecSchemaAsJson(EdiRec *rec)
	Get the schema for a record and format as JSON.
int	ediGetTableDimensions(Edi edi, cchar tableName, int numRows, int numCols)
	Get table dimensions information.
cchar*	ediGetTableSchemaAsJson(Edi edi, cchar tableName)
	Get a table schema and format as JSON.
MprList*	ediGetTables(Edi *edi)
	Get a list of database tables.
char*	ediGetTypeString(int type)
	Convert an EDI type to a string.
cchar*	ediGridAsJson(EdiGrid *grid, int flags)
	Convert an EDI database grid into a JSON string.
EdiGrid*	ediJoin(Edi *edi, ...)
	Join grids.
int	ediLoad(Edi edi, cchar path)
	Load the database file.
int	ediLookupField(Edi edi, cchar tableName, cchar *fieldName)
	Lookup a column field by name.
EdiProvider*	ediLookupProvider(cchar *providerName)
	Lookup an EDI provider name.
EdiGrid*	ediMakeGrid(cchar *content)
	Make a grid.
MprHash*	ediMakeHash(cchar *fmt, ...)
	Make a hash container of property values.
MprJson*	ediMakeJson(cchar *fmt, ...)
	Make a JSON container of property values.
EdiRec*	ediMakeRec(cchar *content)
	Make a record.
void	ediManageEdiRec(EdiRec *rec, int flags)
	Manage an EdiRec instance for garbage collection.
Edi*	ediOpen(cchar source, cchar provider, int flags)
	Open a database.
int	ediParseTypeString(cchar *type)
	Parse an EDI type string.
EdiGrid*	ediPivotGrid(EdiGrid *grid, int flags)
	Pivot a grid swapping rows for columns.
EdiGrid*	ediQuery(Edi edi, cchar cmd, int argc, cchar **argv, va_list vargs)
	Run a query.
EdiField	ediReadField(Edi edi, cchar tableName, cchar key, cchar fieldName)
	Read a field from the database.
cchar*	ediReadFieldValue(Edi edi, cchar fmt, cchar tableName, cchar key, cchar fieldName, cchar defaultValue)
	Read a formatted field from the database.
EdiRec*	ediReadRec(Edi edi, cchar tableName, cchar *key)
	Read a record.
EdiRec*	ediReadRecWhere(Edi edi, cchar tableName, cchar fieldName, cchar operation, cchar *value)
	Read one record.
EdiGrid*	ediReadTable(Edi edi, cchar tableName)
	Read a table.
EdiGrid*	ediReadWhere(Edi edi, cchar tableName, cchar fieldName, cchar operation, cchar *value)
	Read matching records.
cchar*	ediRecAsJson(EdiRec *rec, int flags)
	Convert an EDI database record into a JSON string.
int	ediRemoveIndex(Edi edi, cchar tableName, cchar *indexName)
	Remove a table index.
int	ediRemoveRec(Edi edi, cchar tableName, cchar *key)
	Delete a row in a database table.
int	ediRemoveTable(Edi edi, cchar tableName)
	Remove a table from the database.
int	ediRenameColumn(Edi edi, cchar tableName, cchar columnName, cchar newColumnName)
	Rename a column.
int	ediRenameTable(Edi edi, cchar tableName, cchar *newTableName)
	Rename a table.
int	ediSave(Edi *edi)
	Save in-memory database contents to disk.
EdiRec*	ediSetField(EdiRec rec, cchar fieldName, cchar *value)
	Set a record field without writing to the database.
EdiRec*	ediSetFields(EdiRec rec, MprJson data)
	Set record fields without writing to the database.
void	ediSetPrivate(Edi *edi, bool on)
	Create a private database for each client.
void	ediSetReadonly(Edi *edi, bool on)
	Control whether the database accepts updates.
int	ediUpdateField(Edi edi, cchar tableName, cchar key, cchar fieldName, cchar *value)
	Write a value to a database table field.
int	ediUpdateRec(Edi edi, EdiRec rec)
	Write a record to the database.
bool	ediValidateRec(EdiRec *rec)
	Validate a record.
void	espDumpGrid(EdiGrid *grid)
	Display the grid to the debug log.

Typedefs

EdiProvider	Database provider interface.
EdiValidation	Validation structure.
EdiValidationProc	Field validation callback procedure.

Defines

#define	EDI_AUTO_INC 0x1
	Field flag Automatic increments on new row.
#define	EDI_AUTO_SAVE 0x2
	Auto-save database if modified in memory.
#define	EDI_CREATE 0x1
	Create database if not present.
#define	EDI_FOREIGN 0x8
	Field flag Column is a foreign key.
#define	EDI_GRID_READ_ONLY 0x1
	Grid contains pure database records, must not be modified.
#define	EDI_INDEX 0x4
	Field flag Column is indexed.
#define	EDI_KEY 0x2
	Field flag Column is the ID key.
#define	EDI_LITERAL 0x8
	Literal schema in ediOpen source parameter.
#define	EDI_NO_SAVE 0x4
	Prevent saving to disk.
#define	EDI_NOT_NULL 0x10
	Field flag Column must not be null (not implemented).
#define	EDI_PRIVATE 0x20
	Create private clone of the database.
#define	EDI_SUPPRESS_SAVE 0x10
	Temporarily suppress auto-save.
#define	EDI_TYPE_BINARY 1
	Arbitrary binary data.
#define	EDI_TYPE_BOOL 2
	Boolean true\|false value.
#define	EDI_TYPE_DATE 3
	Date type.
#define	EDI_TYPE_FLOAT 4
	Floating point number.
#define	EDI_TYPE_INT 5
	Integer number.
#define	EDI_TYPE_MAX 8
	Max type + 1.
#define	EDI_TYPE_STRING 6
	String.
#define	EDI_TYPE_TEXT 7
	Multi-line text.

Edi

Database structure.

Description:: The Embedded Database Interface (EDI) defines an abstract interface atop various relational database providers. Providers are supplied for SQLite and for the ESP Memory Database (MDB).

Fields:

EdiMigration	back	Backward migration callback.
char *	errMsg	Last error message.
int	flags	Database flags.
EdiMigration	forw	Forward migration callback.
MprMutex *	mutex	Multithread lock.
cchar *	path	Database path.
struct EdiProvider *	provider	Database provider.
MprHash *	schemaCache	Cache of table schema in JSON.
MprHash *	validations	Validations.

int ediAddColumn (Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)

Add a column to a table.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.
type	Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
flags	Control column attributes. Set to a set of: EDI_AUTO_INC for auto incrementing columns, EDI_KEY if the column is the key column and/or EDI_INDEX to create an index on the column.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediAddIndex (Edi *edi, cchar *tableName, cchar *columnName, cchar *indexName)

Add an index to a table.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.
indexName	Ignored. Set to null.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediAddTable (Edi *edi, cchar *tableName)

Add a table to a database.

Parameters:

edi	Database handle.
tableName	Database table name. Table names should be singular. Certain routines like ediJoin rely on being able to map foreign key fields of the form NameId by converting the Name to a database table.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediAddValidation (Edi *edi, cchar *name, cchar *tableName, cchar *columnName, cvoid *data)

Add a validation.

Description:: Validations are run when calling ediUpdateRec. A validation is used to validate field data using builtin validators.

Parameters:

edi	Database handle.
name	Validation name. Select from: banned to validate field data against a regular express for banned content. boolean to validate field data as "true" or "false" date to validate field data as a date or time. format to validate field data against a regular expression supplied in the "data" argument integer to validate field data as an integral value number to validate field data as a number. It may be an integer or floating point number. present to validate field data as not null. unique to validate field data as being unique in the database table.
tableName	Database table name.
columnName	Database column name.
data	Argument data for the validator. For example: the "format" validator requires a regular expression.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediChangeColumn (Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)

Change a column schema definition.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.
type	Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
flags	Control column attributes. Set to a set of: EDI_AUTO_INC for auto incrementing columns, EDI_KEY if the column is the key column and/or EDI_INDEX to create an index on the column.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

Edi * ediClone (Edi *edi)

Clone a database.

Parameters:

edi	Database to clone.

Returns:: A copy of the database.

API Stability:: Internal.

See Also:

EdiGrid * ediCloneGrid (EdiGrid *grid)

Clone a grid.

Parameters:

grid

to clone.

Returns:: A complete copy of a grid.

API Stability:: Prototype.

See Also:

void ediClose (Edi *edi)

Close a database.

Parameters:

edi	Database handle.

API Stability:: Evolving.

See Also:

EdiGrid * ediCreateBareGrid (Edi *edi, cchar *tableName, int nrows)

Create a bare grid.

Description:: This creates an empty grid based on the given table's schema.

Parameters:

edi	Database handle.
tableName	Database table name.
nrows	Number of rows to reserve in the grid.

Returns:: EdiGrid instance.

API Stability:: Evolving.

See Also:

EdiRec * ediCreateBareRec (Edi *edi, cchar *tableName, int nfields)

Create a bare record.

Description:: This creates an empty record based on the given table's schema.

Parameters:

edi	Database handle.
tableName	Database table name.
nfields	Number of fields to reserve in the record.

Returns:: EdiGrid instance.

API Stability:: Evolving.

See Also:

EdiRec * ediCreateRec (Edi *edi, cchar *tableName)

Create a record.

Description:: This will create a record using the given database tableName to supply the record schema. Use ediCreateBareRec to create a free-standing record without requiring a database. The record is allocated and room is reserved to store record values. No record field values are stored.

Parameters:

edi	Database handle.
tableName	Database table name.

Returns:: Record instance.

API Stability:: Evolving.

See Also:

int ediDelete (Edi *edi, cchar *path)

Delete the database at the given path.

Parameters:

edi	Database handle. This is required to identify the database provider. The database should be closed before deleting.
path	Database path name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

cchar * ediFormatField (cchar *fmt, EdiField *fp)

Format a field value.

Parameters:

fmt	Printf style format string.
fp	Field whoes value will be formatted.

Returns:: Formatted value string.

API Stability:: Evolving.

See Also:

MprList * ediGetColumns (Edi *edi, cchar *tableName)

Get a list of column names.

Parameters:

edi	Database handle.
tableName	Database table name.

Returns:: An MprList of column names in the given table.

API Stability:: Evolving.

See Also:

int ediGetColumnSchema (Edi *edi, cchar *tableName, cchar *columnName, int *type, int *flags, int *cid)

Get the column schema.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.
type	Output parameter to receive the column data type. Will be set to one of: EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT. Set to null if this data is not required.
flags	Output parameter to receive the column control flags. Will be set to one or more of: EDI_AUTO_INC, EDI_KEY and/or EDI_INDEX Set to null if this data is not required.
cid	Output parameter to receive the ordinal column index in the database table. Set to null if this data is not required.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

EdiField * ediGetField (EdiRec *rec, cchar *fieldName)

Get a record field.

Parameters:

rec	Database record.
fieldName	Field in the record to extract.

Returns:: An EdiField structure containing the record field value and details.

API Stability:: Evolving.

See Also:

int ediGetFieldType (EdiRec *rec, cchar *fieldName)

Get the data type of a record field.

Parameters:

rec	Record to examine.
fieldName	Field to examine.

Returns:: The field type. Returns one of: EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

API Stability:: Evolving.

See Also:

cchar * ediGetFieldValue (EdiRec *rec, cchar *fieldName)

Get a field value.

Parameters:

rec	Database record.
fieldName	Field in the record to extract.

Returns:: A field value as a string. Returns ZZ.

API Stability:: Evolving.

See Also:

MprList * ediGetGridColumns (EdiGrid *grid)

Get a list of grid column names.

Parameters:

grid	Database grid.

Returns:: An MprList of column names in the given grid.

API Stability:: Evolving.

See Also:

MprHash * ediGetRecErrors (EdiRec *rec)

Get record validation errors.

Parameters:

rec	Database record.

Returns:: A hash of validation errors. If validation passed, then this call returns NULL.

API Stability:: Evolving.

See Also:

int ediGetTableDimensions (Edi *edi, cchar *tableName, int *numRows, int *numCols)

Get table dimensions information.

Parameters:

edi	Database handle.
tableName	Database table name.
numRows	Output parameter to receive the number of rows in the table Set to null if this data is not required.
numCols	Output parameter to receive the number of columns in the table Set to null if this data is not required.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

MprList * ediGetTables (Edi *edi)

Get a list of database tables.

Parameters:

edi	Database handle.

Returns:: An MprList of table names in the database.

API Stability:: Evolving.

See Also:

cchar * ediGetTableSchemaAsJson (Edi *edi, cchar *tableName)

Get a table schema and format as JSON.

Parameters:

edi	Database handle.
tableName	Name of table to examine.

API Stability:: Prototype.

See Also:

char * ediGetTypeString (int type)

Convert an EDI type to a string.

Parameters:

type	Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

Returns:: Type string. This will be set to one of: "binary", "bool", "date", "float", "int", "string" or "text".

API Stability:: Evolving.

See Also:

cchar * ediGridAsJson (EdiGrid *grid, int flags)

Convert an EDI database grid into a JSON string.

Parameters:

grid	EDI grid.
flags	Reserved. Set to zero.

Returns:: JSON string.

API Stability:: Prototype.

See Also:

EdiGrid * ediJoin (Edi *edi, ...)

Join grids.

Parameters:

edi	Database handle.
...	Null terminated list of data grids. These are instances of EdiGrid.

Returns:: A joined grid.

API Stability:: Evolving.

See Also:

int ediLoad (Edi *edi, cchar *path)

Load the database file.

Parameters:

edi	Database handle.
path	Database path name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediLookupField (Edi *edi, cchar *tableName, cchar *fieldName)

Lookup a column field by name.

Parameters:

edi	Database handle.
tableName	Database table name.
fieldName	Database column field name.

Returns:: The ordinal column index in the table if the column field is found. Otherwise returns a negative MPR error code.

API Stability:: Evolving.

See Also:

EdiProvider * ediLookupProvider (cchar *providerName)

Lookup an EDI provider name.

Parameters:

providerName

Name of the EDI provider.

Returns:: The EDI provider object. Returns null if the provider cannot be found.

API Stability:: Evolving.

See Also:

EdiGrid * ediMakeGrid (cchar *content)

Make a grid.

\par \b Description: This call makes a free-standing data grid based on the JSON format content string

Parameters:

content

JSON format content string. The content should be an array of objects where each object is a set of property names and values.

Returns:: An EdiGrid instance.

Example:: : grid = ediMakeGrid("[ \
{ id: '1', country: 'Australia' }, \
{ id: '2', country: 'China' }, \
]");.

API Stability:: Evolving.

See Also:

MprHash * ediMakeHash (cchar *fmt, ...)

Make a hash container of property values.

Description:: This routine formats the given arguments, parses the result as a JSON string and returns an equivalent hash of property values.

Parameters:

fmt	Printf style format string.
...	arguments.

Returns:: MprHash instance.

API Stability:: Evolving.

See Also:

MprJson * ediMakeJson (cchar *fmt, ...)

Make a JSON container of property values.

Description:: This routine formats the given arguments, parses the result into a JSON object.

Parameters:

fmt	Printf style format string.
...	arguments.

Returns:: MprJson instance.

API Stability:: Evolving.

See Also:

EdiRec * ediMakeRec (cchar *content)

Make a record.

Description:: This call makes a free-standing data record based on the JSON format content string.

Parameters:

content

JSON format content string. The content should be a set of property names and values.

Returns:: An EdiRec instance.

Example:: : rec = ediMakeRec("{ id: 1, title: 'Message One', body: 'Line one' }");.

API Stability:: Evolving.

See Also:

void ediManageEdiRec (EdiRec *rec, int flags)

Manage an EdiRec instance for garbage collection.

Parameters:

rec	Record instance.
flags	GC management flag.

API Stability:: Evolving.

See Also:

Edi * ediOpen (cchar *source, cchar *provider, int flags)

Open a database.

Description:: This opens a database using the specified database provider.

Parameters:

source	Database path name. If using the "mdb" provider with the EDI_LITERAL flag, then the source argument can be set to a literal JSON database content string.
provider	Database provider. Set to "mdb" for the Memory Database or "sqlite" for the SQLite provider.
flags	Set to: EDI_CREATE Create database if not present. EDI_AUTO_SAVE Auto-save database if modified in memory. This option is only supported by the "mdb" provider. EDI_NO_SAVE Prevent saving to disk. This option is only supported by the "mdb" provider. EDI_LITERAL Literal schema in ediOpen source parameter. This option is only supported by the "mdb" provider.

Returns:: If successful, returns an EDI database instance object. Otherwise returns zero.

API Stability:: Evolving.

See Also:

int ediParseTypeString (cchar *type)

Parse an EDI type string.

Parameters:

type	Type string set to one of: "binary", "bool", "date", "float", "int", "string" or "text".

Returns:: Type code. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

API Stability:: Evolving.

See Also:

EdiGrid * ediQuery (Edi *edi, cchar *cmd, int argc, cchar **argv, va_list vargs)

Run a query.

Description:: This runs a provider dependant query. For the SDB SQLite provider, this runs an SQL statement. The "mdb" provider does not implement this API. To do queries using the "mdb" provider, use: ediReadRec, ediReadRecWhere, ediReadWhere, ediReadField and ediReadTable. The query may contain positional parameters via argc/argv or via a va_list. These are recommended to mitigate SQL injection risk.

Parameters:

edi	Database handle.
cmd	Query command to execute.
argc	Number of query parameters in argv.
argv	Query parameter arguments.
vargs	Query parameters supplied in a NULL terminated va_list.

Returns:: If succesful, returns tabular data in the form of an EgiGrid structure. Returns NULL on errors.

API Stability:: Evolving.

See Also:

EdiField ediReadField (Edi *edi, cchar *tableName, cchar *key, cchar *fieldName)

Read a field from the database.

Description:: This reads a field from the database.

Parameters:

edi	Database handle.
tableName	Database table name.
key	Row key column value to read.
fieldName	Column name to read.

Returns:: Field value or null if the no record is found. May return null or empty if the field is null or empty.

API Stability:: Evolving.

See Also:

cchar * ediReadFieldValue (Edi *edi, cchar *fmt, cchar *tableName, cchar *key, cchar *fieldName, cchar *defaultValue)

Read a formatted field from the database.

Description:: This reads a field from the database and formats the result using an optional format string. If the field has a null or empty value, the supplied defaultValue will be returned.

Parameters:

edi	Database handle.
fmt	Reserved. Set to NULL.
tableName	Database table name.
key	Row key column value to read.
fieldName	Column name to read.
defaultValue	Default value to return if the field is null or empty.

Returns:: Field value or default value if field is null or empty. Returns null if no matching record is found.

API Stability:: Evolving.

See Also:

EdiRec * ediReadRec (Edi *edi, cchar *tableName, cchar *key)

Read a record.

Description:: Read a record from the given table as identified by the key value.

Parameters:

edi	Database handle.
tableName	Database table name.
key	Key value of the record to read.

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

See Also:

EdiRec * ediReadRecWhere (Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read one record.

Description:: This runs a simple query on the database and selects the first matching record. The query selects a row that has a "field" that matches the given "value".

Parameters:

edi	Database handle.
tableName	Database table name.
fieldName	Database field name to evaluate.
operation	Comparision operation. Set to "==", "!=", "<", ">", "<=" or ">=".
value	Data value to compare with the field values.

Returns:: First matching record. Returns NULL if no matching records.

API Stability:: Evolving.

See Also:

EdiGrid * ediReadTable (Edi *edi, cchar *tableName)

Read a table.

Description:: This reads all the records in a table and returns a grid containing the results.

Parameters:

edi	Database handle.
tableName	Database table name.

Returns:: A grid containing all records in the table. Returns NULL if no matching records.

API Stability:: Evolving.

See Also:

EdiGrid * ediReadWhere (Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read matching records.

Description:: This runs a simple query on the database and returns matching records in a grid. The query selects all rows that have a "field" that matches the given "value".

Parameters:

edi	Database handle.
tableName	Database table name.
fieldName	Database field name to evaluate.
operation	Comparision operation. Set to "==", "!=", "<", ">", "<=" or ">=".
value	Data value to compare with the field values.

Returns:: A grid containing all matching records. Returns NULL if no matching records.

API Stability:: Evolving.

See Also:

cchar * ediRecAsJson (EdiRec *rec, int flags)

Convert an EDI database record into a JSON string.

Parameters:

rec	EDI record.
flags	Reserved. Set to zero.

Returns:: JSON string.

API Stability:: Prototype.

See Also:

int ediRemoveIndex (Edi *edi, cchar *tableName, cchar *indexName)

Remove a table index.

Parameters:

edi	Database handle.
tableName	Database table name.
indexName	Ignored. Set to null. This call will remove the table index.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediRemoveRec (Edi *edi, cchar *tableName, cchar *key)

Delete a row in a database table.

Parameters:

edi	Database handle.
tableName	Database table name.
key	Row key column value to delete.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediRemoveTable (Edi *edi, cchar *tableName)

Remove a table from the database.

Parameters:

edi	Database handle.
tableName	Database table name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediRenameColumn (Edi *edi, cchar *tableName, cchar *columnName, cchar *newColumnName)

Rename a column.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.
newColumnName	New column name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediRenameTable (Edi *edi, cchar *tableName, cchar *newTableName)

Rename a table.

Parameters:

edi	Database handle.
tableName	Database table name.
newTableName	New database table name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediSave (Edi *edi)

Save in-memory database contents to disk.

Description:: How this call behaves is provider dependant. If the provider is "mdb" and the database is not opened with AutoSave, then this call will save the in-memory contents. If the "mdb" database is opened with AutoSave, then this call will do nothing. For the "sdb" SQLite provider, this call does nothing.

Parameters:

edi	Database handle.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

EdiRec * ediSetField (EdiRec *rec, cchar *fieldName, cchar *value)

Set a record field without writing to the database.

Description:: This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use ediUpdateRec

Parameters:

rec	Record to update.
fieldName	Record field name to update.
value	Value to update.

Returns:: The record instance if successful, otherwise NULL.

API Stability:: Evolving.

See Also:

EdiRec * ediSetFields (EdiRec *rec, MprJson *data)

Set record fields without writing to the database.

Description:: This routine updates the record object with the given values. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: ediSetFields(rec, mprParseJson("{ name: '%s', address: '%s' }", name, address)) The record will not be written to the database. To write to the database, use ediUpdateRec

Parameters:

rec	Record to update.
data	Json object of field to use for the update.

Returns:: The record instance if successful, otherwise NULL.

API Stability:: Evolving.

See Also:

void ediSetPrivate (Edi *edi, bool on)

Create a private database for each client.

Parameters:

edi	Database handle.
on	Set to true to clone the database for each connected client.

API Stability:: Internal.

See Also:

void ediSetReadonly (Edi *edi, bool on)

Control whether the database accepts updates.

Parameters:

edi	Database handle.
on	Set to true to make the database readonly, i.e. to disable all updates.

API Stability:: Prototype.

See Also:

int ediUpdateField (Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)

Write a value to a database table field.

Description:: Update the value of a table field in the selected table row. Note: field validations are not run.

Parameters:

edi	Database handle.
tableName	Database table name.
key	Key value for the table row to update.
fieldName	Column name to update.
value	Value to write to the database field.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

int ediUpdateRec (Edi *edi, EdiRec *rec)

Write a record to the database.

Description:: If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record.

Parameters:

edi	Database handle.
rec	Record to write to the database.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

bool ediValidateRec (EdiRec *rec)

Validate a record.

Description:: Run defined field validations and return true if the record validates. Field validations are defined via ediAddValidation calls. If any validations fail, error messages will be added to the record and can be retrieved via ediGetRecErrors

Parameters:

rec	Record to validate.

Returns:: True if all field valiations pass.

API Stability:: Evolving.

See Also:

int edRemoveColumn (Edi *edi, cchar *tableName, cchar *columnName)

Remove a column from a table.

Parameters:

edi	Database handle.
tableName	Database table name.
columnName	Database column name.

Returns:: Zero if successful. Otherwise a negative MPR error code.

API Stability:: Evolving.

See Also:

void espDumpGrid (EdiGrid *grid)

Display the grid to the debug log.

Parameters:

grid

EDI grid.

API Stability:: Prototype.

See Also:

EdiField

EDI Record field structure.

Description:: The EdiField stores record field data and minimal schema information such as the data type and source column name.

Fields:

int	flags	Field flags. Flag mask set to EDI_AUTO_INC, EDI_KEY and/or EDI_INDEX.
cchar *	name	Field name. Sourced from the database column name.
int	type	Field data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
int	valid	Field validity. Set to true if valid.
cchar *	value	Field data value.

EdiGrid

Grid structure.

Description:: A grid is a tabular (grid) of rows and records. Grids may capture database table data, or may be free-standing without a backing database.

Fields:

struct Edi *	edi	Database handle.
int	flags	Grid flags.
int	nrecords	Number of records in grid.
EdiRec *	records[ARRAY_FLEX]	Grid records.
cchar *	tableName	Base table name for grid.

EdiGrid * ediFilterGridFields (EdiGrid *grid, cchar *fields, int include)

Filter the fields of a grid.

Parameters:

grid	Grid to modify and filter.
fields	Space separated list of record field names.
include	Set to true to interpret the names as fields to include. If false, interpret the names as fields to reject.

Returns:: The filtered grid. Same reference as the input grid.

API Stability:: Internal.

See Also:

cchar * ediGetGridSchemaAsJson (EdiGrid *grid)

Get the schema for a grid and format as JSON.

Parameters:

grid	Grid to examine.

API Stability:: Prototype.

See Also:

EdiRec * ediGetNextRec (EdiGrid *grid, EdiRec *rec)

Get the next record in a grid This is used as an iterator.

For the first call, set rec to NULL

Parameters:

grid	Grid whose records are iterated.
rec	Record pointer.

Returns:: The next record object. Returns NULL after the last record.

API Stability:: Prototype.

See Also:

EdiGrid * ediPivotGrid (EdiGrid *grid, int flags)

Pivot a grid swapping rows for columns.

Parameters:

grid	Source grid.
flags	Control flags. Set to EDI_PIVOT_FIELD_NAMES to use field names as the first column of data.

Returns:: New pivoted grid.

API Stability:: Evolving.

See Also:

EdiRec

Database record structure.

Description:: Records may capture database row data, or may be free-standing without a backing database.

Fields:

struct Edi *	edi	Database handle.
MprHash *	errors	Hash of record errors.
EdiField	fields[ARRAY_FLEX]	Field records.
cchar *	id	Record key ID.
int	index	Grid index for iteration.
int	nfields	Number of fields in record.
cchar *	tableName	Base table name for record.

EdiRec * ediFilterRecFields (EdiRec *rec, cchar *fields, int include)

Filter the fields of a record.

Parameters:

rec	Record to modify and filter.
fields	Space separated list of record field names.
include	Set to true to interpret the names as fields to include. If false, interpret the names as fields to reject.

Returns:: The filtered record. Same reference as the input record.

API Stability:: Internal.

See Also:

EdiField * ediGetNextField (EdiRec *rec, EdiField *fp, int offset)

Get the next field in a record This is used as an iterator.

For the first call, set fp to NULL

Parameters:

rec	Record whose fields are iterated.
fp	Field pointer.
offset	Initial offset. Set to 1 to step over the ID field.

Returns:: The next field object. Returns NULL after the last field.

API Stability:: Prototype.

See Also:

cchar * ediGetRecSchemaAsJson (EdiRec *rec)

Get the schema for a record and format as JSON.

Parameters:

rec

API Stability:: Prototype.

See Also:

EdiService

Edi service control structure.

Fields:

void ediAddFieldError (struct EdiRec *rec, cchar *field, cchar *fmt, ...)

Add a field error message.

Parameters:

rec	Record to update.
field	Field name for the error message.
fmt	Message format string.

API Stability:: Prototype.

See Also:

void ediAddProvider (struct EdiProvider *provider)

Add a database provider.

Description:: This should only be called by database providers.

API Stability:: Evolving.

See Also:

EdiService * ediCreateService ()

Create the EDI service.

Returns:: EdiService object.

API Stability:: Evolving.

See Also:

void ediDefineMigration (struct Edi *edi, EdiMigration forw, EdiMigration back)

Define migration callbacks.

Parameters:

edi	Database handle.
forw	Forward migration callback. Of the form: int forw(Edi *edit); A successful return should be zero.
back	Backward migration callback. Of the form: int back(Edi *edit); A successful return should be zero.

API Stability:: Evolving.

See Also:

void ediDefineValidation (cchar *name, EdiValidationProc vfn)

Define a field validation procedure.

Parameters:

name	Validation name.
vfn	Validation callback to invoke when validating field data.

API Stability:: Evolving.

See Also:

Functions

Typedefs

typedef cchar*(* EdiValidationProc)(struct EdiValidation *vp, struct EdiRec *rec, cchar *fieldName, cchar *value).

Field validation callback procedure.

Parameters:

vp	Validation structure reference.
rec	Record to validate.
fieldName	Field name to validate.
value	Field value to validate.

API Stability:: Evolving.

See Also:

EdiProvider

Database provider interface.

Fields:

EdiValidation

Validation structure.

API Stability:: Evolving.

Fields:

cvoid *	data	Custom data (managed).
cvoid *	mdata	Custom data (unmanaged).
cchar *	name	Validation name.
EdiValidationProc	vfn	Validation callback procedure.