EDI API

Extensions

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

Functions

intedRemoveColumn(Edi *edi, cchar *tableName, cchar *columnName)
 Remove a column from a table.
intediAddColumn(Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)
 Add a column to a table.
voidediAddFieldError(struct EdiRec *rec, cchar *field, cchar *fmt, ...)
 Add a field error message.
intediAddIndex(Edi *edi, cchar *tableName, cchar *columnName, cchar *indexName)
 Add an index to a table.
voidediAddProvider(struct EdiProvider *provider)
 Add a database provider.
intediAddTable(Edi *edi, cchar *tableName)
 Add a table to a database.
intediAddValidation(Edi *edi, cchar *name, cchar *tableName, cchar *columnName, cvoid *data)
 Add a validation.
intediChangeColumn(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.
voidediClose(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, free-standing record.
EdiRec *ediCreateRec(Edi *edi, cchar *tableName)
 Create a new record based on the table's schema.
EdiService *ediCreateService(void)
 Create the EDI service.
voidediDefineMigration(struct Edi *edi, EdiMigration forw, EdiMigration back)
 Define database migration callbacks.
voidediDefineValidation(cchar *name, EdiValidationProc vfn)
 Define a field validation procedure.
intediDelete(Edi *edi, cchar *path)
 Delete the database at the given path.
voidediDumpGrid(cchar *message, EdiGrid *grid)
 Display the grid to the debug log.
voidediDumpRec(cchar *message, EdiRec *rec)
 Display a record to the debug log.
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.
EdiGrid *ediFindGrid(Edi *edi, cchar *tableName, cchar *query)
 Read matching records in a table.
EdiRec *ediFindRec(Edi *edi, cchar *tableName, cchar *query)
 Read one record.
cchar *ediFormatField(cchar *fmt, EdiField *fp)
 Format a field value.
intediGetColumnSchema(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 database column names.
EdiField *ediGetField(EdiRec *rec, cchar *fieldName)
 Get a record field.
intediGetFieldType(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.
intediGetTableDimensions(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.
intediLoad(Edi *edi, cchar *path)
 Load the database file.
intediLookupField(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)
MprJson *ediMakeJson(cchar *fmt, ...)
 Make a JSON container of property values.
EdiRec *ediMakeRec(cchar *content)
 Make a record.
EdiRec *ediMakeRecFromJson(cchar *tableName, MprJson *fields)
 Make a record from a JSON fields object.
voidediManageEdiRec(EdiRec *rec, int flags)
 Manage an EdiRec instance for garbage collection.
Edi *ediOpen(cchar *source, cchar *provider, int flags)
 Open a database.
intediParseTypeString(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 database query query.
EdiFieldediReadField(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.
cchar *ediRecAsJson(EdiRec *rec, int flags)
 Convert an EDI database record into a JSON string.
intediRemoveIndex(Edi *edi, cchar *tableName, cchar *indexName)
 Remove a table index.
intediRemoveRec(Edi *edi, cchar *tableName, cchar *key)
 Delete a row in a database table identified by a key value.
intediRemoveTable(Edi *edi, cchar *tableName)
 Remove a table from the database.
intediRenameColumn(Edi *edi, cchar *tableName, cchar *columnName, cchar *newColumnName)
 Rename a column.
intediRenameTable(Edi *edi, cchar *tableName, cchar *newTableName)
 Rename a table.
intediSave(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 *ediSetFieldFmt(EdiRec *rec, cchar *fieldName, cchar *fmt, ...)
 Set a record field using a format string.
EdiRec *ediSetFields(EdiRec *rec, MprJson *data)
 Set record fields without writing to the database.
voidediSetPrivate(Edi *edi, bool on)
 Create a private database for each client.
voidediSetReadonly(Edi *edi, bool on)
 Control whether the database accepts updates.
intediUpdateField(Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)
 Write a value to a database table field.
intediUpdateFieldFmt(Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *fmt, ...)
 Write a formatted value to a database table field.
intediUpdateRec(Edi *edi, EdiRec *rec)
 Write a record to the database.
boolediValidateRec(EdiRec *rec)
 Validate a record.

Typedefs

EdiProviderDatabase provider interface.
EdiValidationValidation structure.
EdiValidationProcField validation callback procedure.

Defines

#defineEDI_AUTO_INC   0x1
 Field flag Automatic increments on new row.
#defineEDI_AUTO_SAVE   0x2
 Auto-save database if modified in memory.
#defineEDI_CREATE   0x1
 Create database if not present.
#defineEDI_FOREIGN   0x8
 Field flag Column is a foreign key.
#defineEDI_GRID_READ_ONLY   0x1
 Grid contains pure database records, must not be modified.
#defineEDI_INDEX   0x4
 Field flag Column is indexed.
#defineEDI_KEY   0x2
 Field flag Column is the ID key.
#defineEDI_LITERAL   0x8
 Literal schema in ediOpen source parameter.
#defineEDI_NO_SAVE   0x4
 Prevent saving to disk.
#defineEDI_NOT_NULL   0x10
 Field flag Column must not be null (not implemented).
#defineEDI_PRIVATE   0x20
 Create private clone of the database.
#defineEDI_READ_ONLY   0x20
 Field flag Field is read-only (not implemented).
#defineEDI_SUPPRESS_SAVE   0x10
 Temporarily suppress auto-save.
#defineEDI_TYPE_BINARY   1
 Arbitrary binary data.
#defineEDI_TYPE_BOOL   2
 Boolean true|false value.
#defineEDI_TYPE_DATE   3
 Date type (stored as epoch).
#defineEDI_TYPE_FLOAT   4
 Floating point number.
#defineEDI_TYPE_INT   5
 Integer number.
#defineEDI_TYPE_MAX   8
 Max type + 1.
#defineEDI_TYPE_STRING   6
 String.
#defineEDI_TYPE_TEXT   7
 Multi-line text.

Edi

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:
EdiMigrationback Backward migration callback.
char *errMsg Last error message.
intflags Database flags.
EdiMigrationforw 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:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
typeColumn 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.
flagsControl 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:
Stable.
int ediAddIndex (Edi *edi, cchar *tableName, cchar *columnName, cchar *indexName)

Add an index to a table.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
indexNameIgnored. Set to null.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediAddTable (Edi *edi, cchar *tableName)

Add a table to a database.

Parameters:
ediDatabase handle.
tableNameDatabase 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:
Stable.
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:
ediDatabase handle.
nameValidation 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.
tableNameDatabase table name.
columnNameDatabase column name.
dataArgument 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:
Stable.
int ediChangeColumn (Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)

Change a column schema definition.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
typeColumn 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.
flagsControl 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:
Stable.
Edi * * ediClone (Edi *edi)

Clone a database.

Parameters:
ediDatabase to clone.
Returns:
A copy of the database.
API Stability:
Internal.
EdiGrid * * ediCloneGrid (EdiGrid *grid)

Clone a grid.

Parameters:
gridto clone.
Returns:
A complete copy of a grid.
API Stability:
Stable.
void ediClose (Edi *edi)

Close a database.

Parameters:
ediDatabase handle.
API Stability:
Stable.
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:
ediDatabase handle.
tableNameDatabase table name.
nrowsNumber of rows to reserve in the grid.
Returns:
EdiGrid instance.
API Stability:
Stable.
EdiRec * * ediCreateBareRec (Edi *edi, cchar *tableName, int nfields)

Create a bare, free-standing record.

Description:
This creates an empty record based. The tableName and number of fields are defined in the record, but otherwise, the record's fields are uninitialized. This API is a low level API used internally by ESP and EDI.
Parameters:
ediDatabase handle.
tableNameDatabase table name.
nfieldsNumber of fields to reserve in the record.
Returns:
EdiGrid instance.
API Stability:
Stable.
EdiRec * * ediCreateRec (Edi *edi, cchar *tableName)

Create a new record based on the table's schema.

Description:
This will create an empty record using the given database tableName to supply the record schema. It will not be saved to the database as the field values have not been assigned. Set field values using ediSetField and ediSetFields and then save to the database using ediUpdateRec. Create a record based on the table's schema. Not saved to the database. 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:
ediDatabase handle.
tableNameDatabase table name.
Returns:
Record instance.
API Stability:
Stable.
int ediDelete (Edi *edi, cchar *path)

Delete the database at the given path.

Parameters:
ediDatabase handle. This is required to identify the database provider. The database should be closed before deleting.
pathDatabase path name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
void ediDumpGrid (cchar *message, EdiGrid *grid)

Display the grid to the debug log.

Description:
Used for debugging only.
Parameters:
messagePrefix message to output.
gridEDI grid.
API Stability:
Stable.
void ediDumpRec (cchar *message, EdiRec *rec)

Display a record to the debug log.

Description:
Used for debugging only.
Parameters:
messagePrefix message to output.
recRecord to log.
API Stability:
Stable.
EdiGrid * * ediFindGrid (Edi *edi, cchar *tableName, cchar *query)

Read matching records in a table.

Description:
This runs a SQL like query on the database and returns matching records in a grid. The query selects the rows that have matching fields.
Parameters:
ediDatabase handle.
tableNameDatabase table name.
querySQL like query expression. This arg is a printf style format string. When expanded, this will contain a SQL style query expression of the form: "Field Op Value AND field OP value ... LIMIT offset, limit". All fields may be matched by using the pseudo column name "*". Where OP is "==", "!=", "<", ">", "<=", ">=" or "><".
Returns:
A grid containing all matching records. Returns NULL if no matching records.
API Stability:
Stable.
EdiRec * * ediFindRec (Edi *edi, cchar *tableName, cchar *query)

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:
ediDatabase handle.
tableNameDatabase table name.
querySQL like query expression. This arg is a printf style format string. When expanded, this will contain a SQL style query expression of the form: "Field Op Value AND field OP value ... LIMIT offset, limit". All fields may be matched by using the pseudo column name "*". Where OP is "==", "!=", "<", ">", "<=", ">=" or "><".
Returns:
First matching record. Returns NULL if no matching records.
API Stability:
Deprecated.
cchar * * ediFormatField (cchar *fmt, EdiField *fp)

Format a field value.

Parameters:
fmtPrintf style format string.
fpField whoes value will be formatted.
Returns:
Formatted value string.
API Stability:
Stable.
MprList * * ediGetColumns (Edi *edi, cchar *tableName)

Get a list of database column names.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
Returns:
An MprList of column names in the given table.
API Stability:
Stable.
int ediGetColumnSchema (Edi *edi, cchar *tableName, cchar *columnName, int *type, int *flags, int *cid)

Get the column schema.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
typeOutput 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.
flagsOutput 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.
cidOutput 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:
Stable.
EdiField * * ediGetField (EdiRec *rec, cchar *fieldName)

Get a record field.

Parameters:
recDatabase record.
fieldNameField in the record to extract.
Returns:
An EdiField structure containing the record field value and details.
API Stability:
Stable.
int ediGetFieldType (EdiRec *rec, cchar *fieldName)

Get the data type of a record field.

Parameters:
recRecord to examine.
fieldNameField 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:
Stable.
cchar * * ediGetFieldValue (EdiRec *rec, cchar *fieldName)

Get a field value.

Parameters:
recDatabase record.
fieldNameField in the record to extract.
Returns:
A field value as a string.
API Stability:
Stable.
MprList * * ediGetGridColumns (EdiGrid *grid)

Get a list of grid column names.

Parameters:
gridDatabase grid.
Returns:
An MprList of column names in the given grid.
API Stability:
Stable.
MprHash * * ediGetRecErrors (EdiRec *rec)

Get record validation errors.

Parameters:
recDatabase record.
Returns:
A hash of validation errors. If validation passed, then this call returns NULL.
API Stability:
Stable.
int ediGetTableDimensions (Edi *edi, cchar *tableName, int *numRows, int *numCols)

Get table dimensions information.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
numRowsOutput parameter to receive the number of rows in the table Set to null if this data is not required.
numColsOutput 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:
Stable.
MprList * * ediGetTables (Edi *edi)

Get a list of database tables.

Parameters:
ediDatabase handle.
Returns:
An MprList of table names in the database.
API Stability:
Stable.
cchar * * ediGetTableSchemaAsJson (Edi *edi, cchar *tableName)

Get a table schema and format as JSON.

Parameters:
ediDatabase handle.
tableNameName of table to examine.
API Stability:
Stable.
char * * ediGetTypeString (int type)

Convert an EDI type to a string.

Parameters:
typeColumn 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:
Stable.
cchar * * ediGridAsJson (EdiGrid *grid, int flags)

Convert an EDI database grid into a JSON string.

Parameters:
gridEDI grid.
flagsReserved. Set to MPR_JSON_PRETTY for a prettier format.
Returns:
JSON string.
API Stability:
Stable.
EdiGrid * * ediJoin (Edi *edi, ...)

Join grids.

Parameters:
ediDatabase handle.
...Null terminated list of data grids. These are instances of EdiGrid.
Returns:
A joined grid.
API Stability:
Stable.
int ediLoad (Edi *edi, cchar *path)

Load the database file.

Parameters:
ediDatabase handle.
pathDatabase path name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediLookupField (Edi *edi, cchar *tableName, cchar *fieldName)

Lookup a column field by name.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
fieldNameDatabase 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:
Stable.
EdiProvider * * ediLookupProvider (cchar *providerName)

Lookup an EDI provider name.

Parameters:
providerNameName of the EDI provider.
Returns:
The EDI provider object. Returns null if the provider cannot be found.
API Stability:
Stable.
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. @param content JSON format content string. The content should be an array of objects where each object is a set of property names and values. @return An EdiGrid instance \par \b Example: : grid = ediMakeGrid("[ \\ \n { id: '1', country: 'Australia' }, \ \n { id: '2', country: 'China' }, \ \n ]");
API Stability:
Stable.
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:
fmtPrintf style format string.
...arguments.
Returns:
MprJson instance.
API Stability:
Stable.
EdiRec * * ediMakeRec (cchar *content)

Make a record.

Description:
This call makes a free-standing data record based on the JSON format content string.
Parameters:
contentJSON 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:
Stable.
EdiRec * * ediMakeRecFromJson (cchar *tableName, MprJson *fields)

Make a record from a JSON fields object.

Description:
This call makes a free-standing data record based on the JSON fields.
Parameters:
tableNameName of the database table to initialize in the record.
fieldsJSON object.
Returns:
An EdiRec instance.
API Stability:
Stable.
See Also:
ediMakeGrid, ediMakeRec
void ediManageEdiRec (EdiRec *rec, int flags)

Manage an EdiRec instance for garbage collection.

Parameters:
recRecord instance.
flagsGC management flag.
API Stability:
Stable.
Edi * * ediOpen (cchar *source, cchar *provider, int flags)

Open a database.

Description:
This opens a database using the specified database provider.
Parameters:
sourceDatabase 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.
providerDatabase provider. Set to "mdb" for the Memory Database or "sqlite" for the SQLite provider.
flagsSet 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:
Stable.
int ediParseTypeString (cchar *type)

Parse an EDI type string.

Parameters:
typeType 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:
Stable.
EdiGrid * * ediQuery (Edi *edi, cchar *cmd, int argc, cchar **argv, va_list vargs)

Run a database query 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: ediFindRec, ediFindGrid and ediReadField. The query may contain positional parameters via argc/argv or via a va_list. These are recommended to mitigate SQL injection risk.
Parameters:
ediDatabase handle.
cmdQuery command to execute.
argcNumber of query parameters in argv.
argvQuery parameter arguments.
vargsQuery 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:
Stable.
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:
ediDatabase handle.
tableNameDatabase table name.
keyRow key column value to read.
fieldNameColumn 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:
Stable.
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:
ediDatabase handle.
fmtReserved and not yet implemented. Set to NULL.
tableNameDatabase table name.
keyRow key column value to read.
fieldNameColumn name to read.
defaultValueDefault 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:
Stable.
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:
ediDatabase handle.
tableNameDatabase table name.
keyKey value of the record to read.
Returns:
Record instance of EdiRec.
API Stability:
Stable.
cchar * * ediRecAsJson (EdiRec *rec, int flags)

Convert an EDI database record into a JSON string.

Parameters:
recEDI record.
flagsReserved. Set to zero.
Returns:
JSON string.
API Stability:
Stable.
int ediRemoveIndex (Edi *edi, cchar *tableName, cchar *indexName)

Remove a table index.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
indexNameIgnored. Set to null. This call will remove the table index.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediRemoveRec (Edi *edi, cchar *tableName, cchar *key)

Delete a row in a database table identified by a key value.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
keyKey column value to delete.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediRemoveTable (Edi *edi, cchar *tableName)

Remove a table from the database.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediRenameColumn (Edi *edi, cchar *tableName, cchar *columnName, cchar *newColumnName)

Rename a column.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
newColumnNameNew column name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediRenameTable (Edi *edi, cchar *tableName, cchar *newTableName)

Rename a table.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
newTableNameNew database table name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
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:
ediDatabase handle.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
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:
recRecord to update.
fieldNameRecord field name to update.
valueValue to update.
Returns:
The record instance if successful, otherwise NULL.
API Stability:
Stable.
EdiRec * * ediSetFieldFmt (EdiRec *rec, cchar *fieldName, cchar *fmt, ...)

Set a record field using a format string.

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:
recRecord to update.
fieldNameRecord field name to update.
fmtFormat string.
...Variable arguments for the format string.
Returns:
The record instance if successful, otherwise NULL.
API Stability:
Stable.
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 the fieldNames and values. The data may come from the request params() or it can be manually created via #ediMakeJson. 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:
recRecord to update.
dataJson object of field to use for the update.
Returns:
The record instance if successful, otherwise NULL.
API Stability:
Stable.
void ediSetPrivate (Edi *edi, bool on)

Create a private database for each client.

Parameters:
ediDatabase handle.
onSet to true to clone the database for each connected client.
API Stability:
Internal.
void ediSetReadonly (Edi *edi, bool on)

Control whether the database accepts updates.

Parameters:
ediDatabase handle.
onSet to true to make the database readonly, i.e. to disable all updates.
API Stability:
Stable.
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.
Parameters:
ediDatabase handle.
tableNameDatabase table name.
keyKey value for the table row to update.
fieldNameColumn name to update.
valueValue to write to the database field.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
int ediUpdateFieldFmt (Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *fmt, ...)

Write a formatted 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:
ediDatabase handle.
tableNameDatabase table name.
keyKey value for the table row to update.
fieldNameColumn name to update.
fmtValue format string.
...Variable arguments for the format string.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
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:
ediDatabase handle.
recRecord to write to the database.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.
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:
recRecord to validate.
Returns:
True if all field valiations pass.
API Stability:
Stable.
int edRemoveColumn (Edi *edi, cchar *tableName, cchar *columnName)

Remove a column from a table.

Parameters:
ediDatabase handle.
tableNameDatabase table name.
columnNameDatabase column name.
Returns:
Zero if successful. Otherwise a negative MPR error code.
API Stability:
Stable.

EdiField

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:
intflags 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.
inttype 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
intvalid Field validity. Set to true if valid.
cchar *value Field data value.

EdiGrid

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:
intcount Total count of available records matching query.
struct Edi *edi Database handle.
intflags Grid flags.
intnrecords 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:
gridGrid to modify and filter.
fieldsSpace separated list of record field names.
includeSet 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.
cchar * * ediGetGridSchemaAsJson (EdiGrid *grid)

Get the schema for a grid and format as JSON.

Parameters:
gridGrid to examine.
API Stability:
Stable.
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:
gridGrid whose records are iterated.
recRecord pointer.
Returns:
The next record object. Returns NULL after the last record.
API Stability:
Stable.
EdiGrid * * ediPivotGrid (EdiGrid *grid, int flags)

Pivot a grid swapping rows for columns.

Parameters:
gridSource grid.
flagsControl flags. Set to EDI_PIVOT_FIELD_NAMES to use field names as the first column of data.
Returns:
New pivoted grid.
API Stability:
Stable.

EdiRec

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.
EdiFieldfields[ARRAY_FLEX] Field records.
cchar *id Record key ID.
intindex Grid index for iteration.
intnfields 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:
recRecord to modify and filter.
fieldsSpace separated list of record field names.
includeSet 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.
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:
recRecord whose fields are iterated.
fpField pointer.
offsetInitial offset. Set to 1 to step over the ID field.
Returns:
The next field object. Returns NULL after the last field.
API Stability:
Stable.
cchar * * ediGetRecSchemaAsJson (EdiRec *rec)

Get the schema for a record and format as JSON.

Parameters:
rec
API Stability:
Stable.

EdiService

EdiService

Edi service control structure.

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

Add a field error message.

Parameters:
recRecord to update.
fieldField name for the error message.
fmtMessage format string.
API Stability:
Stable.
void ediAddProvider (struct EdiProvider *provider)

Add a database provider.

Description:
This should only be called by database providers.
API Stability:
Stable.
EdiService * * ediCreateService (void )

Create the EDI service.

Returns:
EdiService object.
API Stability:
Stable.
void ediDefineMigration (struct Edi *edi, EdiMigration forw, EdiMigration back)

Define database migration callbacks.

Parameters:
ediDatabase handle.
forwForward migration callback. Of the form: int forw(Edi *edit); A successful return should be zero.
backBackward migration callback. Of the form: int back(Edi *edit); A successful return should be zero.
API Stability:
Stable.
void ediDefineValidation (cchar *name, EdiValidationProc vfn)

Define a field validation procedure.

Parameters:
nameValidation name.
vfnValidation callback to invoke when validating field data.
API Stability:
Stable.

Functions

Typedefs

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

Field validation callback procedure.

Parameters:
vpValidation structure reference.
recRecord to validate.
fieldNameField name to validate.
valueField value to.
API Stability:
Stable.
EdiProvider

Database provider interface.

Fields:
EdiValidation

Validation structure.

API Stability:
Stable.
Fields:
cvoid *data Custom data (managed).
cvoid *mdata Custom data (unmanaged).
cchar *name Validation name.
EdiValidationProcvfn Validation callback procedure.

© Embedthis Software. All rights reserved.