SQLBeginTran

Starts a database transaction. When you make a transaction, your changes are not written to the database until you call the SQLCommit() function. Alternatively, you can use the SQLRollBack function() to discard all changes made during the transaction.

After you begin a transaction, you need to call either SQLCommit() to save the changes or SQLRollBack() to discard the changes. You need to use one of these functions to complete the transaction and release all database locks. Unless you complete the transaction, you cannot successfully disconnect the SQL connection.

A single database connection can only handle one transaction at a time. After you call SQLBeginTran(), you need to complete that transaction before you can call SQLBeginTran() again.

If you disconnect from a database while a transaction is active (not completed), CitectSCADA automatically "rolls back" the transaction any changes you made to the database in that transaction are discarded.

You do not need to begin a transaction to modify a database. Any changes you make to a database before you call the SQLBeginTran() are automatically committed, and no database locks are held.

The SQLBeginTran() function is not supported by all databases. If the function is not performing as you expect, check that both your database and ODBC driver support transactions. Refer to the documentation for your database for more information on transactions.

Syntax

SQLBeginTran(hSQL)

hSQL:

The handle to the SQL connection, returned from the SQLConnect() function. The SQL connection handle identifies the table where details of the associated SQL connection are stored.

Return Value

0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code, call the SQLErrMsg function).

Related Functions

SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec, SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack, SQLTraceOff, SQLTraceOn

Example

/* Increase each employee's salary and superannuation by a 
specified amount. If any errors occur, the changes are aborted */

INT

FUNCTION

PayIncrease(STRING sIncrease)

	INT hSQL;

	INT Count1;

	INT Count2;

	hSQL = SQLConnect("DRV=QEDBF");

	SQLBeginTran(hSQL);

	SQLExec(hSQL, "UPDATE C:\DATA\EMPLOYEE SET Salary = Salary + " +sIncrease);

	Count1 = SQLNumChange(hSQL);

	SQLExec(hSQL, "UPDATE C:\DATA\EMPLOYEE SET Super = Super + " +sIncrease);

	Count2 = SQLNumChange(hSQL);

	IF Count1 = Count2 THEN

		SQLCommit(hSQL);

	ELSE

		SQLRollBack(hSQL);

	END

	SQLEnd(hSQL);

	SQLDisconnect(hSQL);

END

See Also

SQL Functions