Xbasic

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%

See Also