sql_insert Function

Syntax

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

Arguments

connectionCharacter SQL::Connection: An open SQL::connection object, a connection string, or a named connection string.
tablenameCharacter: Name of the table to update.
fieldValuePairsCharacter: 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.
executeLogical: 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.
ePointer: 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.

Returns

resultPointer

An object with the following properties:

errorLogical: If .t., an error occurred. Otherwise .f..
errorTextCharacter: A detailed description of the error - if any occurred.
sqlCharacter: The SQL that was generated to execute the insert.
ArgumentsCharacter: The XML arguments generated for the insert.
lastInsertedIdentityAny Type: The value of the primary key field (if its value was auto-generated.)

Description

Inserts a record in a SQL table.

Discussion

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
cn.open("::Name::myconnstring")
tablename = "mytable"
fieldsValuePairs = <<%str%
name=fred smith
date of birth=1952/12/18
salary=78000
%str%

p = sql_insert(cn,tablename,fieldsValuePairs)

?p.lastInsertedIdentity
= 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%
name=Fred
city=Boston
%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%
name=e2.name
city=e2.city
%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"
}
%str%