PowerScript supports standard embedded SQL statements and dynamic SQL statements in scripts. In general, PowerScript supports all DBMS-specific clauses and reserved words that occur in the supported SQL statements. For example, PowerBuilder supports DBMS-specific built-in functions within a SELECT command.
For information about embedded SQL, see Using Embedded SQL in Connecting to Your Database.
Referencing PowerScript variables in scripts
Wherever constants can be referenced in SQL statements, PowerScript variables preceded by a colon (:) can be substituted. Any valid PowerScript variable can be used. This INSERT statement uses a constant value:
INSERT INTO EMPLOYEE ( SALARY ) VALUES ( 18900 ) ;
The same statement using a PowerScript variable to reference the constant might look like this:
int Sal_var Sal_var = 18900 INSERT INTO EMPLOYEE ( SALARY ) VALUES ( :Sal_var ) ;
Using indicator variables
PowerBuilder supports indicator variables, which are used to identify null values or conversion errors after a database retrieval. Indicator variables are integers that are specified in the HostVariableList of a FETCH or SELECT statement.
Each indicator variable is separated from the variable it is indicating by a space (but no comma). For example, this statement is a HostVariableList without indicator variables:
:Name, :Address, :City
The same HostVariableList with indicator variables looks like this:
:Name :IndVar1, :Address :IndVar2, :City :IndVar3
Indicator variables have one of these values:
Error reporting
Not all DBMSs return a conversion error when the datatype of a column does not match the datatype of the associated variable.
The following statement uses the indicator variable IndVar2 to see if Address contains a null value:
if IndVar2 = -1 then...
You can also use the PowerScript IsNull function to accomplish the same result without using indicator variables:
if IsNull( Address ) then ...
This statement uses the indicator variable IndVar3 to set City to null:
IndVar3 = -1
You can also use the PowerScript SetNull function to accomplish the same result without using indicator variables:
SetNull( City )
Error handling in scripts
The scripts shown in the SQL examples above do not include error handling, but it is good practice to test the success and failure codes (the SQLCode attribute) in the transaction object after every statement. The codes are:
Value |
Meaning |
---|---|
0 |
Success. |
100 |
Fetched row not found. |
-1 |
Error; the statement failed. Use SQLErrText or SQLDBCode to obtain the detail. |
After certain statements, such as DELETE, FETCH, and UPDATE, you should also check the SQLNRows property of the transaction object to make sure the action affected at least one row.
About SQLErrText and SQLDBCode
The string SQLErrText in the transaction object contains the database vendor-supplied error message. The long named SQLDBCode in the transaction object contains the database vendor-supplied status code:
IF SQLCA.SQLCode = -1 THEN MessageBox("SQL error", SQLCA.SQLErrText) END IF
Painting standard SQL
You can paint the following SQL statements in scripts and functions:
-
Declarations of SQL cursors and stored procedures
-
Cursor FETCH, UPDATE, and DELETE statements
-
Noncursor SELECT, INSERT, UPDATE, and DELETE statements
For more information about scope, see Where to declare variables.
You can declare cursors and stored procedures at the scope of global, instance, shared, or local variables. A cursor or procedure can be declared in the Script view using the Paste SQL button in the PainterBar.
You can paint standard embedded SQL statements in the Script view, the Function painter, and the Interactive SQL view in the Database painter using the Paste SQL button in the PainterBar or the Paste Special>SQL item from the pop-up menu.
Supported SQL statements
In general, all DBMS-specific features are supported in PowerScript if they occur within a PowerScript-supported SQL statement. For example, PowerScript supports DBMS-specific built-in functions within a SELECT command.
However, any SQL statement that contains a SELECT clause must also contain a FROM clause in order for the script to compile successfully. To solve this problem, add a FROM clause that uses a "dummy" table to SELECT statements without FROM clauses. For example:
string resselect user_name() into:res from dummy; select db_name() into:res from dummy; select date('2001-01-02:21:20:53') into:res from dummy;
Disabling database connection when compiling and building
When PowerBuilder compiles an application that contains embedded SQL, it connects to the database profile last used in order to check for database access errors during the build process. For applications that use multiple databases, this can result in spurious warnings during the build since the embedded SQL can be validated only against that single last-used database and not against the databases actually used by the application. In addition, an unattended build, such as a lengthy overnight rebuild, can stall if the database connection cannot be made.
To avoid these issues, you can select the Disable Database Connection When Compiling and Building check box on the general page of the System Options dialog box.
Caution
Select the check box only when you want to compile without signing on to the database. Compiling without connecting to a database prevents the build process from checking for database errors and may therefore result in runtime errors later.
Description
Closes the SQL cursor CursorName; ends processing of CursorName.
Syntax
CLOSE CursorName ;
Usage
This statement must be preceded by an OPEN statement for the same cursor. The USING TransactionObject clause is not allowed with CLOSE; the transaction object was specified in the statement that declared the cursor.
CLOSE often appears in the script that is executed when the SQL code after a fetch equals 100 (not found).
Error handling
It is good practice to test the success/failure code after executing a CLOSE cursor statement.
Examples
This statement closes the Emp_cursor cursor:
CLOSE Emp_cursor ;
Description
Closes the SQL procedure ProcedureName; ends processing of ProcedureName.
DBMS-specific
Not all DBMSs support stored procedures.
Syntax
CLOSE ProcedureName;
Usage
This statement must be preceded by an EXECUTE statement for the same procedure. The USING TransactionObject clause is not allowed with CLOSE; the transaction object was specified in the statement that declared the procedure.
Use CLOSE only to close procedures that return result sets. PowerBuilder automatically closes procedures that do not return result sets (and sets the return code to 100).
CLOSE often appears in the script that is executed when the SQL code after a fetch equals 100 (not found).
Error handling
It is good practice to test the success/failure code after executing a CLOSE Procedure statement.
Examples
This statement closes the stored procedure named Emp_proc:
CLOSE Emp_proc ;
Description
Permanently updates all database operations since the previous COMMIT, ROLLBACK, or CONNECT for the specified transaction object.
Syntax
COMMIT {USING TransactionObject};
Parameter |
Description |
---|---|
TransactionObject |
The name of the transaction object for which you want to permanently update all database operations since the previous COMMIT, ROLLBACK, or CONNECT. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
COMMIT does not cause a disconnect, but it does close all open cursors or procedures. (But note that the DISCONNECT statement in PowerBuilder does issue a COMMIT.)
Error handling
It is good practice to test the success/failure code after executing a COMMIT statement.
Examples
Example 1
This statement commits all operations for the database specified in the default transaction object:
COMMIT ;
Example 2
This statement commits all operations for the database specified in the transaction object named Emp_tran:
COMMIT USING Emp_tran ;
Description
Connects to a specified database.
Syntax
CONNECT {USING TransactionObject};
Parameter |
Description |
---|---|
TransactionObject |
The name of the transaction object containing the required connection information for the database to which you want to connect. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
This statement must be executed before any actions (such as INSERT, UPDATE, or DELETE) can be processed using the default transaction object or the specified transaction object.
Error handling
It is good practice to test the success/failure code after executing a CONNECT statement.
Examples
Example 1
This statement connects to the database specified in the default transaction object:
CONNECT ;
Example 2
This statement connects to the database specified in the transaction object named Emp_tran:
CONNECT USING Emp_tran ;
Description
Declares a cursor for the specified transaction object.
Syntax
DECLARE CursorName CURSOR FOR SelectStatement {USING TransactionObject};
Parameter |
Description |
---|---|
CursorName |
Any valid PowerBuilder name. |
SelectStatement |
Any valid SELECT statement. |
TransactionObject |
The name of the transaction object for which you want to declare the cursor. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
DECLARE Cursor is a nonexecutable command and is analogous to declaring a variable.
To declare a local cursor, open the script in the Script view and select Paste SQL from the PainterBar or the Edit>Paste Special menu. To declare a global, instance, or shared cursor, select Declare from the first drop-down list in the Script view and Global Variables, Instance Variables, or Shared Variables from the second drop-down list, then select Paste SQL.
For information about global, instance, shared, and local scope, see Where to declare variables.
Examples
This statement declares the cursor called Emp_cur for the database specified in the default transaction object. It also references the Sal_var variable, which must be set to an appropriate value before you execute the OPEN Emp_cur command:
DECLARE Emp_cur CURSOR FOR SELECT employee.emp_number, employee.emp_name FROM employee WHERE employee.emp_salary > :Sal_var ;
Description
Declares a procedure for the specified transaction object.
DBMS-specific
Not all DBMSs support stored procedures.
Syntax
DECLARE ProcedureName PROCEDURE FOR StoredProcedureName @Param1=Value1, @Param2=Value2,... {USING TransactionObject};
Parameter |
Description |
---|---|
ProcedureName |
Any valid PowerBuilder name. |
StoredProcedureName |
Any stored procedure in the database. |
@Paramn=Valuen |
The name of a parameter (argument) defined in the stored procedure and a valid PowerBuilder expression; represents the number of the parameter and value. |
TransactionObject |
The name of the transaction object for which you want to declare the procedure. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
DECLARE Procedure is a nonexecutable command. It is analogous to declaring a variable.
To declare a local procedure, open the script in the Script view and select Paste SQL from the PainterBar or the Edit>Paste Special menu. To declare a global, instance, or shared procedure, select Declare from the first drop-down list in the Script view and Global Variables, Instance Variables, or Shared Variables from the second drop-down list, then select Paste SQL.
For information about global, instance, shared, and local scope, see Where to declare variables.
Examples
Example 1
This statement declares the SAP ASE procedure Emp_proc for the database specified in the default transaction object. It references the Emp_name_var and Emp_sal_var variables, which must be set to appropriate values before you execute the EXECUTE Emp_proc command:
DECLARE Emp_proc procedure for GetName @emp_name = :Emp_name_var, @emp_salary = :Emp_sal_var ;
Example 2
This statement declares the ORACLE procedure Emp_proc for the database specified in the default transaction object. It references the Emp_name_var and Emp_sal_var variables, which must be set to appropriate values before you execute the EXECUTE Emp_proc command:
DECLARE Emp_proc procedure for GetName (:Emp_name_var, :Emp_sal_var) ;
Description
Deletes the rows in TableName specified by Criteria.
Syntax
DELETE FROM TableName WHERE Criteria {USING TransactionObject};
Parameter |
Description |
---|---|
TableName |
The name of the table from which you want to delete rows. |
Criteria |
Criteria that specify which rows to delete. |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
Error handling
It is good practice to test the success/failure code after executing a DELETE statement. To see if the DELETE was successful, you can test SLQCode for a failure code. However, if nothing matches the WHERE clause and no rows are deleted, SQLCode is still set to zero. To make sure the delete affected at least one row, check the SQLNRows property of the transaction object.
Examples
Example 1
This statement deletes rows from the Employee table in the database specified in the default transaction object where Emp_num is less than 100:
DELETE FROM Employee WHERE Emp_num < 100 ;
Example 2
These statements delete rows from the Employee table in the database named in the transaction object named Emp_tran where Emp_num is equal to the value entered in the SingleLineEdit sle_number:
int Emp_num Emp_num = Integer(sle_number.Text) DELETE FROM Employee WHERE Employee.Emp_num = :Emp_num ;
The integer Emp_num requires a colon in front of it to indicate it is a variable when it is used in a WHERE clause.
Description
Deletes the row in which the cursor is positioned.
DBMS-specific
Not all DBMSs support DELETE Where Current of Cursor.
Syntax
DELETE FROM TableName WHERE CURRENT OF CursorName;
Parameter |
Description |
---|---|
TableName |
The name of the table from which you want to delete a row |
CursorName |
The name of the cursor in which the table was specified |
Usage
The USING TransactionObject clause is not allowed with this form of DELETE Where Current of Cursor; the transaction object was specified in the statement that declared the cursor.
Error handling
It is good practice to test the success/failure code after executing a DELETE Where Current of Cursor statement.
Examples
This statement deletes from the Employee table the row in which the cursor named Emp_cur is positioned:
DELETE FROM Employee WHERE current of Emp_curs ;
Description
Executes a COMMIT for the specified transaction object and then disconnects from the specified database.
Syntax
DISCONNECT {USING TransactionObject};
Parameter |
Description |
---|---|
TransactionObject |
The name of the transaction object that identifies the database you want to disconnect from and in which you want to permanently update all database operations since the previous COMMIT, ROLLBACK, or CONNECT. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
Error handling
It is good practice to test the success/failure code after executing a DISCONNECT statement.
Examples
Example 1
This statement disconnects from the database specified in the default transaction object:
DISCONNECT ;
Example 2
This statement disconnects from the database specified in the transaction object named Emp_tran:
DISCONNECT USING Emp_tran ;
Description
Executes the previously declared procedure identified by ProcedureName.
Syntax
EXECUTE ProcedureName;
Parameter |
Description |
---|---|
ProcedureName |
The name assigned in the DECLARE statement of the stored procedure you want to execute. The procedure must have been declared previously. ProcedureName is not necessarily the name of the procedure stored in the database. |
Usage
The USING TransactionObject clause is not allowed with EXECUTE; the transaction object was specified in the statement that declared the procedure.
Error handling
It is good practice to test the success/failure code after executing an EXECUTE statement.
Examples
This statement executes the stored procedure Emp_proc:
EXECUTE Emp_proc ;
Description
Fetches the row after the row on which Cursor | Procedure is positioned.
Syntax
FETCH Cursor | Procedure INTO HostVariableList;
Parameter |
Description |
---|---|
Cursor or Procedure |
The name of the cursor or procedure from which you want to fetch a row |
HostVariableList |
PowerScript variables into which data values will be retrieved |
Usage
The USING TransactionObject clause is not allowed with FETCH; the transaction object was specified in the statement that declared the cursor or procedure.
If your DBMS supports formats of FETCH other than the customary (and default) FETCH NEXT, you can specify FETCH FIRST, FETCH PRIOR, or FETCH LAST.
Error handling
It is good practice to test the success/failure code after executing a FETCH statement. To see if the FETCH was successful, you can test SLQCode for a failure code. However, if nothing matches the WHERE clause and no rows are fetched, SQLCode is still set to 100. To make sure the fetch affected at least one row, check the SQLNRows property of the transaction object.
Examples
Example 1
This statement fetches data retrieved by the SELECT clause in the declaration of the cursor named Emp_cur and puts it into Emp_num and Emp_name:
int Emp_num string Emp_name FETCH Emp_cur INTO :Emp_num, :Emp_name ;
Example 2
If sle_emp_num and sle_emp_name are SingleLineEdits, these statements fetch from the cursor named Emp_cur, store the data in Emp_num and Emp_name, and then convert Emp_num from an integer to a string, and put them in sle_emp_num and sle_emp_name:
int Emp_num string Emp_name FETCH Emp_cur INTO :emp_num, :emp_name ; sle_emp_num.Text = string(Emp_num) sle_emp_name.Text = Emp_name
Description
Inserts one or more new rows into the table specified in RestOfInsertStatement.
Syntax
INSERT RestOfInsertStatement {USING TransactionObject} ;
Parameter |
Description |
---|---|
RestOfInsertStatement |
The rest of the INSERT statement (the INTO clause, list of columns and values or source). |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
Error handling
It is good practice to test the success/failure code after executing an INSERT statement.
Examples
Example 1
These statements insert a row with the values in EmpNbr and EmpName into the Emp_nbr and Emp_name columns of the Employee table identified in the default transaction object:
int EmpNbr string EmpName ... INSERT INTO Employee (employee.Emp_nbr, employee.Emp_name) VALUES (:EmpNbr, :EmpName) ;
Example 2
These statements insert a row with the values entered in the SingleLineEdits sle_number and sle_name into the Emp_nbr and Emp_name columns of the Employee table in the transaction object named Emp_tran:
int EmpNbr string EmpName EmpNbr = Integer(sle_number.Text) EmpName = sle_name.Text INSERT INTO Employee (employee.Emp_nbr, employee.Emp_name) VALUES (:EmpNbr, :EmpName) USING Emp_tran ;
Description
Causes the SELECT specified when the cursor was declared to be executed.
Syntax
OPEN CursorName ;
Usage
The USING TransactionObject clause is not allowed with OPEN; the transaction object was specified in the statement that declared the cursor.
Error handling
It is good practice to test the success/failure code after executing an OPEN Cursor statement.
Examples
This statement opens the cursor Emp_curs:
OPEN Emp_curs ;
Description
Cancels all database operations in the specified database since the last COMMIT, ROLLBACK, or CONNECT.
Syntax
ROLLBACK {USING TransactionObject} ;
Parameter |
Description |
---|---|
TransactionObject |
The name of the transaction object that identifies the database in which you want to cancel all operations since the last COMMIT, ROLLBACK, or CONNECT. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
ROLLBACK does not cause a disconnect, but it does close all open cursors and procedures.
Error handling
It is good practice to test the success/failure code after executing a ROLLBACK statement.
Examples
Example 1
This statement cancels all database operations in the database specified in the default transaction object:
ROLLBACK ;
Example 2
This statement cancels all database operations in the database specified in the transaction object named Emp_tran:
ROLLBACK USING emp_tran ;
Description
Selects a row in the tables specified in RestOfSelectStatement.
Syntax
SELECT RestOfSelectStatement {USING TransactionObject} ;
Parameter |
Description |
---|---|
RestOfSelectStatement |
The rest of the SELECT statement (the column list INTO, FROM, WHERE, and other clauses). |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
An error occurs if the SELECT statement returns more than one row.
Error handling
It is good practice to test the success/failure code after executing a SELECT statement. You can test SQLCode for a failure code.
When you use the INTO clause, PowerBuilder does not verify whether the datatype of the retrieved column matches the datatype of the host variable; it only checks for the existence of the columns and tables. You are responsible for checking that the datatypes match. Keep in mind that not all database datatypes are the same as PowerBuilder datatypes.
Examples
The following statements select data in the Emp_LName and Emp_FName columns of a row in the Employee table and put the data into the SingleLineEdits sle_LName and sle_FName (the transaction object Emp_tran is used):
int Emp_num string Emp_lname, Emp_fname Emp_num = Integer(sle_Emp_Num.Text) SELECT employee.Emp_LName, employee.Emp_FName INTO :Emp_lname, :Emp_fname FROM Employee WHERE Employee.Emp_nbr = :Emp_num USING Emp_tran ; IF Emp_tran.SQLCode = 100 THEN MessageBox("Employee Inquiry", & "Employee Not Found") ELSEIF Emp_tran.SQLCode > 0 then MessageBox("Database Error", & Emp_tran.SQLErrText, Exclamation!) END IF sle_Lname.text = Emp_lname sle_Fname.text = Emp_fname
Description
Selects a single blob column in a row in the table specified in RestOfSelectStatement.
Syntax
SELECTBLOB RestOfSelectStatement {USING TransactionObject} ;
Parameter |
Description |
---|---|
RestOfSelectStatement |
The rest of the SELECT statement (the INTO, FROM, and WHERE clauses). |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
An error occurs if the SELECTBLOB statement returns more than one row.
Error handling
It is good practice to test the success/failure code after executing an SELECTBLOB statement. To make sure the update affected at least one row, check the SQLNRows property of SQLCA or the transaction object. The SQLCode or SQLDBCode property will not indicate the success or failure of the SELECTBLOB statement.
You can include an indicator variable in the host variable list (target parameters) in the INTO clause to check for an empty blob (a blob of zero length) and conversion errors.
Database information
SAP ASE users must set the AutoCommit property of the transaction object to true before calling the SELECTBLOB function. For information about the AutoCommit property, see Connecting to Your Database.
Examples
The following statements select the blob column Emp_pic from a row in the Employee table and set the picture p_1 to the bitmap in Emp_id_pic (the transaction object Emp_tran is used):
Blob Emp_id_pic SELECTBLOB Emp_pic INTO :Emp_id_pic FROM Employee WHERE Employee.Emp_Num = 100 USING Emp_tran ; p_1.SetPicture(Emp_id_pic)
The blob Emp_id_pic requires a colon to indicate that it is a host (PowerScript) variable when you use it in the INTO clause of the SELECTBLOB statement.
Description
Updates the rows specified in RestOfUpdateStatement.
Syntax
UPDATE TableName RestOfUpdateStatement {USING TransactionObject} ;
Parameter |
Description |
---|---|
TableName |
The name of the table in which you want to update rows. |
RestOfUpdateStatement |
The rest of the UPDATE statement (the SET and WHERE clauses). |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
Error handling
It is good practice to test the success/failure code after executing a UPDATE statement. You can test SQLCode for a failure code. However, if nothing matches the WHERE clause and no rows are updated, SQLCode is still set to zero. To make sure the update affected at least one row, check the SQLNRows property of the transaction object.
Examples
These statements update rows from the Employee table in the database specified in the transaction object named Emp_tran, where Emp_num is equal to the value entered in the SingleLineEdit sle_Number:
int Emp_num Emp_num=Integer(sle_Number.Text ) UPDATE Employee SET emp_name = :sle_Name.Text WHERE Employee.emp_num = :Emp_num USING Emp_tran ; IF Emptran.SQLNRows > 0 THEN COMMIT USING Emp_tran ; END IF
The integer Emp_num and the SingleLineEdit sle_name require a colon to indicate they are host (PowerScript) variables when you use them in an UPDATE statement.
Description
Updates the rows in TableName in BlobColumn.
Syntax
UPDATEBLOB TableName SET BlobColumn = BlobVariable RestOfUpdateStatement {USING TransactionObject} ;
Parameter |
Description |
---|---|
TableName |
The name of the table you want to update. |
BlobColumn |
The name of the column you want to update in TableName. The datatype of this column must be blob. |
BlobVariable |
A PowerScript variable of the datatype blob. |
RestOfUpdateStatement |
The rest of the UPDATE statement (the WHERE clause). |
TransactionObject |
The name of the transaction object that identifies the database containing the table. This clause is required only for transaction objects other than the default (SQLCA). |
Usage
Error handling
It is good practice to test the success/failure code after executing an UPDATEBLOB statement. To make sure the update affected at least one row, check the SQLNRows property of SQLCA or the transaction object. The SQLCode or SQLDBCode property will not indicate the success or failure of the UPDATEBLOB statement.
Database information
SAP ASE users must set the AutoCommit property of the transaction object to True before calling the UPDATEBLOB function. For information about the AutoCommit property, see Connecting to Your Database.
Examples
These statements update the blob column emp_pic in the Employee table, where emp_num is 100:
int fh blob Emp_id_pic fh = FileOpen("c:\emp_100.bmp", StreamMode!) IF fh <> -1 THEN FileRead(fh, emp_id_pic) FileClose(fh) UPDATEBLOB Employee SET emp_pic = :Emp_id_pic WHERE Emp_num = 100 USING Emp_tran ; END IF IF Emptran.SQLNRows > 0 THEN COMMIT USING Emp_tran ; END IF
The blob Emp_id_pic requires a colon to indicate it is a host (PowerScript) variable in the UPDATEBLOB statement.
Description
Updates the row in which the cursor is positioned using the values in SetStatement.
Syntax
UPDATE TableName SetStatement WHERE CURRENT OF CursorName ;
Parameter |
Description |
---|---|
TableName |
The name of the table in which you want to update the row |
SetStatement |
The word SET followed by a comma-separated list of the form ColumnName = value |
CursorName |
The name of the cursor in which the table is referenced |
Usage
The USING Transaction Object clause is not allowed with UPDATE Where Current of Cursor; the transaction object was specified in the statement that declared the cursor.
Examples
This statement updates the row in the Employee table in which the cursor called Emp_curs is positioned:
UPDATE Employee SET salary = 17800 WHERE CURRENT of Emp_curs ;