sql_insert Function


p result = sql_insert(A connection,c tablename,c fieldValuePairs [, L execute [, P e])


connectionCharacter SQL::Connection

An open SQL::connection object, a connection string, or a named connection string.


Name of the table to update.


Fields to set with corresponding values. A cr-lf list of the form fieldname=value or as JSON string (see Building the fieldValuePairs Argument section below). Date values must be specified using yyyy/mm/dd format.


If false, the SQL is not executed. However, you can still examine the result.sql and result.arguments properties to see what SQL was generated.


A dot variable with with one or more sub-properties. Used in the case where the fieldValuePairs contains dot variables for the value. For example, assume that one line in the cr-lf delimited list of fieldValuePairs contained name=e.whatname and the e variable that was passed in contained e.whatname = "John Smith", the e.whatname in the fieldValuePairs would be resolved before the SQL was executed.



An object with the following properties:


If .t., an error occurred. Otherwise .f..


A detailed description of the error - if any occurred.


The SQL that was generated to execute the insert.


The XML arguments generated for the insert.

lastInsertedIdentityAny Type

The value of the primary key field (if its value was auto-generated.)


Inserts a record in a SQL table.


This function is just a wrapper around the Xbasic AlphaDAO commands to execute a SQL insert statement, but it convenient to use for simple cases.

dim cn as sql::Connection
tablename = "mytable"
fieldsValuePairs = <<%str%
name=fred smith
date of birth=1952/12/18

p = sql_insert(cn,tablename,fieldsValuePairs)

= 5

Building the fieldValuePairs Argument

The fieldValuePairs argument is a CR-LF string of values with the format name=value. The parameter can be built several ways. For a list of static values, the parameter can be built using delimiters. For example:

dim fieldsValuePairs as c 
data = <<%txt%

The fieldValuePairs argument can also be built by concatenating multiple strings together using the + operator and CRLF function. This allows you to dynamically specify the value to populate each field. EG:

dim fieldsValuePairs as c 
fieldsValuePairs = ""
fieldsValuePairs = fieldsValuePairs + "name=" + e.datasubmitted.name + crlf()
fieldsValuePairs = fieldsValuePairs + "city=" +e.datasubmitted.city + crlf()

Field values can also be dynamically populated using the replace_variables_in_string function in combination with delimiters. The replace_variables_in_string() function replaces variables in a character string with the value in the variable. Using this method makes your Xbasic script easier to read:

dim fieldsValuePairs as c 
fieldsValuePairs = <<%txt%

dim e2 as p
e2.name = e.datasubmitted.name 
e2.city = e.datasubmitted.city
fieldsValuePairs = replace_variables_in_string(data,e2,"e2")

The field value pairs can also be specified as a JSON object. For example:

fieldsValuePairs = <<%str%
    "name" : "fred smith",
    "date of birth" : "1954/11/25",
    "salary" : "78000"

See Also