Part I

Language fundamentals

Unify VISION: 4GL Reference

1
Writing scripts
This chapter describes the fundamentals of writing VISION 4GL scripts:
the elements of a script
script conventions
a suggested script organization
Also included is DBMS-specific information about these topics:
references to database objects
SYBASE SQL Server temporary tables
SYBASE SQL Server and the browse feature

Creating scripts
All VISION 4GL and C function definitions reside in a script file. Each
class is associated with its own script. You access a script through
VISION Script Editor only.

VISION Script Editor

In VISION Script Editor you add templates for allowable methods and
then supply VISION 4GL statements and functions to complete the
method.
For example, the following illustration shows a sample script for a form
class. The method list contains the names of all sections and methods that
can be inserted in the script for a form class:

Method list

Script text

Related information

For more information about how to use VISION Script Editor, see Using
VISION Script Editor in Unify VISION: Developing an Application.

Script components
When the user performs an action on a form, VISION Runtime Manager
executes statements in the method associated with that action. The
following tables list examples of user actions and the methods that are
executed.
4

Unify VISION: 4GL Reference

Examples of user actions

When the user
performs this action:

VISION Runtime Manager executes the

Clicks on a button
associated with a
developer-defined
command

COMMAND

Double clicks on a
field

ON DOUBLE CLICK

Exits the application

ON EXIT

Finds a record

ON FIND

statements in the following methods

Changes data in a field WHEN FIELD CHANGES

Clicks in a field

ON FIELD

Clicks in another field AFTER FIELD

Closes the form

ON DISMISS FORM

Clears the form to add ON CLEAR TO ADD

a record
Clears the form to find ON CLEAR TO FIND
a record
Displays the next
record

ON NEXT RECORD

Displays the previous

record

ON PREVIOUS
RECORD

Zooms to another form ON ZOOM

Form commands

ON CHOOSE NEXT FORM

ON NEXT FORM
ON PREVIOUS FORM

Record commands

ON NEXT RECORD
ON PREVIOUS RECORD

Returns a value from a ON RETURN VALUES

form

Chapter 1: Writing scripts

The following table provides a list of the most frequently used tasks and
the corresponding script statements or system functions.
VISION 4GL language components

Task

Script statement or system function

Display a message

DISPLAY NOTICE
DISPLAY

yesno$( )
Assign a value to a
variable

SET

Display a form

CREATE FORM

Declare a local
variable

PRIVATE
PUBLIC

Close a form

DISMISS FORM
CANCEL FORM

Return values to a
form

VALUES TO RETURN ARE

Execute a conditional
statement

FOR
REPEAT
WHILE
IF

Exit the application

EXIT

Print a form

PRINT FORM

Handle runtime errors DBMS_ERROR HANDLER

INSTALL

Send information from

a Unify VISION
application to another
program

DDE_EVENT HANDLER
INSTALL
CREATE PIPELINE
WRITE PIPELINE

Request a lock on a
record

SLOCK
XLOCK

Debug a form

Use VISION Debugger

BREAK
BREAKPOINT

Use the preprocessor

(continued on next page)
6

Unify VISION: 4GL Reference

VISION 4GL language components (continued)

Related information

Task

Script statement or system function

Send a message from

one form to another

MESSAGE_HANDLER
SEND MESSAGE

Execute database
statements

ALTER SCHEMA
ALTER TABLE
CREATE SCHEMA
CREATE TABLE
CREATE VIEW
DELETE
DELETE SELECTED
ROW
DROP SCHEMA
DROP TABLE
DROP VIEW

GRANT
INSERT INTO
REVOKE
SELECT
SLOCK
UNLOCK
UPDATE
UPDATE SELECTED
ROW
XLOCK

For a complete descriptions of foundation classes and runtime operations,

see Unify VISION: Class Reference.

Script conventions
The VISION 4GL syntax descriptions assume the following general
conventions about scripts:
Methods
Methods are optional. If you do not include a method, the default action
is performed according to the specifications you gave for the form or
field in VISION Designer.
Because script methods are event driven, you can arrange them in any
order you prefer. For instance, statements in a BEFORE FIND method are
always executed before an interactive database search regardless of
where you have placed this method in your script.
Methods are optional in a script, unless otherwise noted in the
description.
The BEGIN and END keywords are not required in a method.
Chapter 1: Writing scripts

Comments
Comments cannot span methods. A comment that starts in one method
must terminate in that same method. A comment that starts outside a
method must end before the next method.
Statements
Each method contains one or more statements. A method can include as
many statements as needed. Statement order within a method determines
execution order.
Statements must be placed within a method, unless otherwise noted
in the description.

You can use either a single statement or a statement block

anywhere that statement appears in the syntax listings unless
otherwise noted in the description.
A statement_list is made up of one or more VISION 4GL
statements. A statement_block is also made up of one or more
statements. However, if the statement_block has more than one
statement, it must be introduced with the keyword BEGIN and
concluded with the keyword END.
A semicolon (;) is required to terminate an SQL statement.
Semicolons are optional for terminating VISION 4GL statements.
System functions
All system functions have a dollar sign ($) as the last character.
You must include the $ character when you use a system function.
All system functions must include parentheses in the function call,
regardless of whether the function has parameters.
When a system function returns a value, you can choose whether
to use this value in the script.
System functions must be placed within methods.
Spaces between the system function parameters shown in the
Syntax subsection are optional. Commas between parameters are
required.
An entire array variable cannot be passed to Unify VISION system
functions or to 3GL functions directly. However, the values of
individual elements of an array can be passed to a function.
8

Unify VISION: 4GL Reference

Optional script elements

Optional elements in a script are:
a file header
preprocessor declarations
external file and function declarations
Related information

For information about preprocessor declarations and external files, see

Using the preprocessor starting on page 107.
The order of script elements
Certain elements of your script, if used, must be arranged in a specific
order:
External function declarations must be placed before the script
header.
Methods must be placed after the header.
FIELD subsections must be grouped together under the related
FIELD method.

Using Help with VISION Script Editor

Online help is provided for VISION 4GL statements, methods, predefined
functions, and system functions. You can access the help while writing
scripts in VISION Script Editor and copy the statement or method text to
the VISION Script Editor window.
There is no help for the toolbar or status line in VISION Script Editor.
To access the help, choose Help ! Indexed Help from any window in
VISION Development Environment, then choose VISION Script Editor

and then the category of help that you want.

To copy and paste the text into a script, follow these steps for either
Windows or UNIX:
Windows

Chapter 1: Writing scripts

Select the text to be copied and issue the Copy command

from the Help windows Edit menu. In VISION Script
Editor use the Paste command from the Edit menu to
paste into your script.
9

UNIX

10

You cannot select text in the help window. Instead, Issue

the Copy command from the Help windows Edit menu.
This brings up a window with the selectable text. Select
the text to be copied and press the OK button. In VISION
Script Editor use the Paste command from the Edit menu
to paste into your script.

Unify VISION: 4GL Reference

Connecting to a database

VISION 4GL includes statements and system functions for connecting to a

database or for changing the database connection.

Database connection statements

When you write scripts, you can specify database connections in the
following statements and clauses:
CHOOSE FORM USING
CREATE FORM
ENABLE ZOOM TO
ON CHOOSE NEXT FORM
USING CONNECTION clause

The USING CONNECTION clause is used with DBMS SQL statements,

such as SELECT, INSERT, DELETE, or CREATE. The clause can also be
used with transaction statements, such as BEGIN WORK, COMMIT
WORK, and ROLLBACK WORK or with locking statements, such as
SLOCK, XLOCK, or UNLOCK.
g Tip

To monitor your database connections from scripts, query the following

read-only attributes: FORM_CONNECTION_NAME and
FORM_CONNECTION_SOURCE.

Database-dependent system functions

Several system functions also depend on a database connection. For the
following system functions, the connection that is used is the connection
for the form that is associated with the script that called the function:
check_dirty$( )
db_type$( )
get_password$( )
l_allow_interrupt$( )
Chapter 1: Writing scripts

l_wait_time$( )
show_dirty$( )
sql_clear$( )

11

For the following system functions, the database connection that was
used for the most recently executed DBMS SQL statement is used,
regardless of the associated forms database connection.
dbms_status$( )
sql_code$( )
sql_errmsg$( )

sql_state$( )
status$( )

The connection that was used for the most recently executed stored
procedure is used for the following system functions, regardless of the
associated forms database connection.
sp_compute$( )
sp_return$( )
sp_select$( )
If the tx_mode$( ) system function is supported for the DBMS, the
function affects all transactions in the application.

DBMS-specific statements and clauses

Some VISION 4GL statements or clauses are used only with a specific
DBMS, and others have DBMS-specific usage. See the Support section
in statement and clause descriptions for DBMS-specific usage.
Portability guideline

ANSI standard SQL statements

To ensure application portability, use only ANSI standard SQL statements
and VISION 4GL statements that work the same on every DBMS. If you
want to take advantage of DBMS-specific VISION 4GL usage, execute the
statements conditionally, based on the database value that is returned by
the db_type$( ) system function.
DBMS-specific SQL extensions
Similarly, if you want to use DBMS-specific SQL extensions, make sure
that all SQL statements are in BEGIN_SQL . . . END_SQL statement
blocks that are executed conditionally, based on the database value that is
returned by the db_type$( ) system function.

The SQL statements that appear in the statement block between

BEGIN_SQL and END_SQL can be any SQL statements that are
recognized by the DBMS, including DBMS-specific SQL extensions.
Returning primary key values
Because not every DBMS supports primary keys, use the VALUES TO
RETURN statement to return values from a zoom form; do not use the
Return Key option on the Zoom Properties panel for the form object.
12

Unify VISION: 4GL Reference

g Tip

On almost every DBMS, DML and DDL statements cannot be mixed in

the same transaction. Perform a COMMIT or ROLLBACK WORK before
executing a dynamic SQL statement if the statement contains DDL. You
may also find it advantageous to call sql_clear$( ) after executing
dynamic DDL.

ODBC interface
For an application that is used with a database that is accessed through
ODBC, scripts and function scripts can contain SQL conformance level
Core SQL Grammar statements. The statements must be enclosed in a
BEGIN_SQL . . . END_SQL statement block.

ORACLE

If you are using ORACLE version 7, you can use both ORACLE SQL and
PL/SQL statements in scripts and function scripts if the statements are
enclosed in a BEGIN_SQL . . . END_SQL statement block.
Unify VISION supports the ORACLE Version 7 deferred binding and
deferred parsing for variables.

Chapter 1: Writing scripts

13

Referring to database objects

You can refer to database objects in VISION 4GL scripts. The information
in this section describes these types of database object references:
qualified table or column names
case sensitivity (and case conversions) in database object names
table name synonyms

Qualifying table or column names

In Unify VISION, you can qualify a table or column name with the name
of the database object that owns, or contains, the table or column. The
owning database object that is specified depends on the DBMS.
For INFORMIX, you can often qualify a table name by the owner
name and qualify a column name by the table name.
For INGRES, you can qualify a table name by the owner name and
qualify a column name by the table name.
For ODBC, if supported by the underlying DBMS, you can qualify
a table name by the owner name and qualify a column name by the
table name.
For ORACLE, you can specify the name of the user that owns the
table or column.
For SYBASE SQL Server, you can specify the name of the
database that contains the table or column. You can also specify
the owner of the table or column.
For Unify DataServer, you can specify the name of the schema that
contains the table or column.
In addition to the optional qualification, when you specify a database
object name, the DBMS may require you to specify the name in uppercase
or lowercase or enclosed in quotation marks (name).
An alternative that is also allowed if supported by the DBMS is to refer to
a table by a synonym.
14

Unify VISION: 4GL Reference

g Tip

If you do not know the names of your database tables, look in your
DBMS manuals to find out how to get a list of table names. Usually you
can use the DBMS version of SQL and some set of commands to display
data dictionary information. For example, if you are using Unify
DataServer, you can run Interactive SQL/A and use the TABLES
command to display a list of table names.

INFORMIX

Depending on the version and mode of INFORMIX, you use one of the
following formats to refer to tables.
If you are using INFORMIX OnLine, to refer to tables, use this
format:
[owner_name.]table_name
To refer to columns, use this format:
[[owner_name.]table_name.]column_name
If you are using MODE ANSI, you must qualify the table name by
the owner name. If you do not qualify the table name, you will
receive a compile error for the script. If the table is not a MODE
ANSI table, the owner name portion is ignored.
If you are using INFORMIX SE, you cannot qualify the table name
or column name by the owner name.
The owner-table name combination must be unique in the application.
The owner name is the login name of the owner of the database object
and may contain uppercase letters.

INGRES

(If you are using INGRES on Windows through ODBC, also see your
INGRES ODBC driver documentation.) To refer to INGRES tables, use this
format:
[owner_name.]table_name
To refer to columns, use this format:
[table_name.]column_name
Chapter 1: Writing scripts

15

You cannot specify the owner name as well as the table name when you
specify a column name.
When you specify column names, you can use correlation names for
tables that are referenced in the select, delete, update, create integrity,
and create rule statements. Use this format:
[correlation_name.]column_name
Correlation names are typically shortened versions of the table name. For
example, s is the correlation for a table named salesreps, shown in the
following example:
select s.lastname from salesrep s
where s.district = 'central' ;

ODBC interface
For ODBC, if the underlying DBMS supports database object names
qualified by the owner name and table name, you can use the following
database object name formats.
To refer to tables, use this format:
[owner_name.]table_name
To refer to columns, use this format:
[[owner_name.]table_name.]column_identifier

ORACLE

To refer to ORACLE database tables, use this format:

[user_name.]table_name
To refer to columns, use this format:
[[user_name.]table_name.]column_name
If a Unify VISION object has the same name as a database column, use
quotation marks () to distinguish the object name from the database
column name. For example, if you have a database column called
ADDRESS1 and also have an object address1, the object name must be
enclosed by quotation marks address1.
16

Unify VISION: 4GL Reference

SYBASE SQL Server

To refer to SYBASE SQL Server database tables, use this format:
[[database_name.][owner_name].]table_name
Use this format to refer to columns:
[[database_name.][owner_name].]table_name.column_name
To qualify the table or column name by the database name and omit the
owner name, include the dot as placeholder, as shown here:
database_name..table_name[.column_name]
Placeholder for owner name

If you do not include the SYBASE SQL Server database name, Unify
VISION uses the database that is specified by the DBNAME external
preference. If you do not specify the owner name, Unify VISION obtains
the owner name for that table from the SYBASE SQL Server system
views.
Unify DataServer
To refer to Unify DataServer database tables, use this format:
[schema_name.]table_name
To refer to columns, use this format:
[[schema_name.]table_name.]column_name

Database object name case sensitivity

VISION Designer stores database object names in the same case as they

are entered. Any target table column names that are not used on the form
are stored in the form file in the same case as they appear in the database
data dictionary. To evaluate database object names, Unify VISION uses
the same name matching algorithms as the current DBMS, as described in
the following subsections.
INFORMIX

On INFORMIX, database object names are always converted to

lowercase. For example, the table names company, Company, and
COMPANY, are all evaluated as company.
Chapter 1: Writing scripts

17

When you use MODE ANSI, user names are by default converted to
uppercase unless the name is enclosed in quotation marks
(user_name). For example, the user names smith and Smith are both
evaluated as SMITH, while the name smith is evaluated as smith.
INGRES

To evaluate database object names and user names for INGRES, Unify
VISION converts all database object names and all user names to
lowercase. For example, if an INGRES developer types EMP as the target
table name when defining a form with VISION Designer, Unify VISION
matches the name with a database table named emp.
ODBC interface
On a database that is accessed through the ODBC interface, database
object name case sensitivity depends on the DBMS and is determined at
runtime. See your ODBC online documentation and DBMS manuals for
information about case sensitivity.
ORACLE

To enable Unify VISION to find the correct database objects, when you
name ORACLE database objects, follow these rules:
If you use SQL*Plus to create the database object and do not
enclose the object name in double quotation marks (name), the
name is converted to uppercase (NAME) when it is stored in the
data dictionary.
When you ask Unify VISION to find the database object, you must
enter the name in all-uppercase letters. That is, if the database
object name was created without quotation marks as Company,
COMPANY, or company, it must be specified as COMPANY.
If you create the database object and enclose the object name in
double quotation marks (Name), the name is stored exactly as
entered (Name).
When you ask Unify VISION to find the database object, you must
type the name exactly as it was created and use the quotation
marks. That is, if the database object name was created with
quotation marks as Company, COMPANY, or company,
you must specify the name exactly as it was created (Company,
COMPANY, or company).
18

Unify VISION: 4GL Reference

Example

The following examples illustrate the use of quotation marks to specify

ORACLE database object names. In the first and third examples, because
the objects are named without quotation marks, you must specify the
names in all-uppercase letters (EMPLOYEE and SALARY). In the second
example, because the objects are named with double quotation marks,
you must specify the names exactly as they appear between the quotation
marks (Employee and Salary).
ORACLE database object name case conversions

If this SQL*Plus statement is used to create the The object name is

database object:
stored as:
CREATE TABLE EMPLOYEE (SALARY NUMBER)

EMPLOYEE
SALARY

CREATE TABLE Employee (Salary Number)

Employee
Salary

CREATE TABLE employee (salary number)

EMPLOYEE
SALARY

The ORACLE rules for referring to database object names also apply to
user names and passwords, as shown in the following table.
ORACLE user name and password case conversions

If this SQL*Plus statement is used to grant the user The user name is
access to the database:
stored as:
GRANT CONNECT TO James IDENTIFIED BY jjj ;

JAMES
JJJ

GRANT CONNECT TO James IDENTIFIED BY jjj ;

James
jjj

g Tip

Chapter 1: Writing scripts

Unify VISION also supports use of the ORACLE 7 authentication of the

user name by the operating system. The operating system login user
name is then used to log in to the database. To specify this option, specify
a user name of / and no password; for example, set the DBUSER
external preference to the value /. See your ORACLE 7 Server
Administrators Guide for information about authenticating users.
19

SYBASE SQL Server

On SYBASE SQL Server, all database object names and user names are
case sensitive. You must enter database object names and user names
exactly as they are defined.

Unify DataServer
On Unify DataServer, all database object names and user names are case
sensitive. You must enter database object names and user names exactly
as they are defined.

Using table name synonyms

You can also specify a table by its synonym, if one has been defined. In
VISION Designer, when you design a form that has a target table, you
select the target table name from the Data Source list box on the Database
Attributes panel. Table name synonyms are displayed as well as other
table names.

20

Unify VISION: 4GL Reference

Creating SYBASE SQL Server temporary tables from

scripts
The information in this section applies to only the SYBASE SQL Server
DBMS.
SYBASE SQL Server temporary tables are visible to only the application

that created them. They are not visible to other applications and can be
accessed only through the connection under which they were created.
SYBASE SQL Server does not allow DDL (data definition language)
statements in a transaction. Therefore, on detecting a DDL statement,
VISION Runtime Manager opens a secondary connection to SYBASE SQL
Server to execute the statement.

However, because the application is using the primary connection, the

application cannot access any temporary table that was created under the
secondary connection. To make sure that the application can use the
temporary table, you must create it under the primary connection.
From a script, to create the temporary table in the primary connection,
end the current transaction and perform DDL statements in a BEGIN_SQL
. . . END_SQL statement block, as shown in this example:
tx_mode$(FALSE); /* Turn off automatic transaction handling
*/
COMMIT WORK;
/* End current transaction
*/
BEGIN_SQL
/* Start the SQL command block
*/
create table #tmp_table_name ( . . . );
/* Create the table: SYBASE SQL statements
*/
END_SQL
/* End the SQL command block
*/
SET $return_value_var TO status$(
);
/* Save the status return value
*/
tx_mode$(TRUE)
/* Turn automatic transaction handling back on */
COMMIT WORK;
/* Restart the deferred transaction
*/

Because SYBASE SQL Server will automatically drop the temporary table
when the application terminates, you do not need to drop the table from
the VISION 4GL script. However, if the application needs to drop the
table, do it within the BEGIN_SQL . . . END_SQL statement block, using
the create table example as a guide.
The SYBASE SQL Server SELECT INTO #temporary_table_name
statement may also create a temporary table. If you use this statement,
Chapter 1: Writing scripts

21

make sure that you enclose it in the BEGIN_SQL . . . END_SQL

statement block, as shown in the previous example.
These guidelines apply only to temporary tables. If you create normal
tables, they can be accessed through all connections to the server,
regardless of the connection under which they were created.

22

Unify VISION: 4GL Reference

Processing queries and using the browse feature with

SYBASE SQL Server

The information in this section applies to only the SYBASE SQL Server
DBMS.
Processing queries and using the browse feature with SYBASE SQL
Server has a few functional differences because Unify VISION uses
SYBASE SQL Server DB-Library functions to connect to the SYBASE
server. Unify VISION must maintain a current transaction for each server
connection. Each database request, such as creating a selected set or
updating rows, must be completed or canceled before starting a new
request in the same transaction.

Writing database queries for SYBASE SQL Server

Therefore, when you write database queries, especially when you use the
browse feature with Unify VISION with SYBASE SQL Server, follow
these guidelines:
Qualify queries so that the number of rows that satisfy the query is
limited to only the rows that the application needs. For example,
do not set up zoom forms that can return an excessive number of
rows that are never accessed by the user. (See Using the browse
feature with SYBASE SQL Server, on page 24.)
Do not use the browse feature on a form in record consistency.
After the selected set is built, Unify VISION must reread the first
record to make it current. Therefore, the first select request, which
created the set in browse mode, must be completed. Unfortunately,
this defeats the purpose of browsing on a very large set of records.
Instead, open the form in set consistency or in no consistency. In
either case, the first row is not reread, the first subset of records
appears quickly, and browse mode is retained.
Do not execute an interactive command or VISION 4GL statement
that initiates another SQL statement. Executing such a statement
causes the browse set to be completed before the requested action
takes place, which causes browse functionality to be again lost.
Chapter 1: Writing scripts

23

These are some of the actions that initiate another SQL statement:
executing a DBMS SQL SELECT, UPDATE, or DELETE statement
executing an interactive add, update or delete operation
executing a find for sets of records on either a Next form or a
zoomed-to form
executing a stored procedure

Using the browse feature with SYBASE SQL Server

When you use the browse feature and the selected set is cleared or the
browse mode form is exited to go to the previous form, the select request
that created the set is canceled. In this case, Unify VISION informs
SYBASE SQL Server to cancel execution of the current request and flush
any pending results.
When SYBASE SQL Server cancels the current select request, each
remaining record must still be processed. Therefore, the end user may see
some delay when clearing a selected set or exiting a form in browse
mode, especially if the entire requested set is fairly large.

24

Unify VISION: 4GL Reference

Embedded SQL statements

Unify VISION allows you to use SQL statements in your script to perform
non-interactive database operations. The flexibility of SQL allows your
script to include the following features:
access to multiple tables and views
joining of tables
portability with other databases
inclusion of database-specific extensions to SQL
optimal database access methods
other statements and features provided by the DBMS, such as
triggers and stored procedures
Unify VISION automatically recognizes some keywords as SQL
statements:
DML statements

DDL statements

COMMIT WORK
DELETE
INSERT
ROLLBACK WORK
SELECT
UPDATE

ALTER SCHEMA
ALTER TABLE
CREATE SCHEMA
CREATE TABLE
CREATE VIEW
DROP SCHEMA
DROP TABLE
DROP VIEW
GRANT
REVOKE

These are standard database statements as specified by the international

standards for SQL. However, in addition to these statements, you can
include other database statements by enclosing them within an SQL
statement block. An SQL statement block can include any statements that
are provided by your database other than statements requiring user
interaction. An SQL statement block is delimited by the VISION 4GL
BEGIN_SQL and END_SQL statements.
Chapter 1: Writing scripts

25

When VISION Runtime Manager encounters an SQL statement, it

automatically prepares the statement for processing by the database. The
database determines the optimal access method to be used and then
executes the statement.
If not contained in a statement block or EXECUTING clause, SQL
statements must be terminated by a semicolon (;).
Related information

For complete information about SQL statement blocks and how you can
use DBMS features with Unify VISION, see the syntax descriptions for
BEGIN_SQL and END_SQL.

Including variables
When you use SQL statements in a script, you can include Unify VISION
variables as parameters within the statements.
If a form name is not specified, a Unify VISION variable must be prefixed
by a dollar sign ($), for example:
$emp_number
A dollar sign prefix is not required if the form name is specified, for
example:
emp_form:emp_number

You can use functions and other elements in a similar manner, for
example:
SELECT emp_name, emp_number
FROM employee
WHERE emp_sdate > $date_function($in_str);

Database interface
When your script is compiled, Unify VISION elements are automatically
prepared in a manner recognized by the database. If errors occur during
compilation of the script that are due to SQL statements, you receive a
warning message, but the script is successfully compiled.
26

Unify VISION: 4GL Reference

At runtime, VISION Runtime Manager substitutes the appropriate value

in place of the variable or other element.
Restrictions and conditions
Unify VISION provides the values of database parameters to the database
at runtime. However, the database cannot alter the values of variables in
your script. Therefore, you cannot change the value of a script element,
such as a counter or index, in an SQL statement. Perform operations to
script elements in VISION 4GL statements only; such statements have no
effect in an SQL statement.
Portability guideline

To ensure portability, observe the following restrictions when Unify

VISION variables are used as dynamic arguments to SQL statements:

A Unify VISION object cannot be used as the argument of an

aggregate (set) function. You must specify a literal column name.
In the BETWEEN predicate of a WHERE clause, at least one
element must be a literal column name.
At least one element of an IN predicate must be a literal column
name.
At runtime, all Unify VISION variables used as dynamic
parameters in SQL statements must have been previously defined.
NULL is an acceptable value; however, UNDEFINED is not a
permitted value.

The EXECUTING clause

An SQL SELECT statement can contain a Unify VISION EXECUTING
clause. To set the value of a scalar variable, the EXECUTING clause is
required for Unify VISION to select all rows that match the WHERE
clause. If the EXECUTING clause is omitted, only the first matching row
is selected. The EXECUTING clause is not required to set the values of
an array.
Related information

For information about the EXECUTING clause, see the syntax

description given on page 259.

The locking clauses

An SQL SELECT statement can contain one of the Unify VISION locking
clauses: SLOCK or XLOCK.
Chapter 1: Writing scripts

27

To ensure optimal performance, security, and portability of your

application, use the Unify VISION locking statements rather than the
locking mechanisms provided by your database.
Related information

For information about the locking clauses, see the syntax descriptions for
SLOCK and XLOCK in this manual.

Example
The following example shows a SELECT statement that includes an
EXECUTING clause.
SET i TO 0
SET name[i], number TO
SELECT AND SLOCK emp_name, emp_number
FROM employee
WHERE emp_sdate > str_to_date $($in_str)
AND emp_number > $in_number
EXECUTING
BEGIN
IF name[i] = mname THEN
BEGIN
DELETE SELECTED ROW;
SET i to i + 1
END
END

28

Unify VISION: 4GL Reference

Dynamic SQL

Dynamic SQL enables you to compose and execute an SQL statement at

runtime. In static SQL, you must type in the SQL statement, including
tables, columns and rows, into your script. With dynamic SQL, the names
of columns, rows, and tables are variables. The variables can be typed in
by the user or they can be defined in the script. When the application is
running, the SQL statements are constructed in memory as your
application is executed.
In another example, the form may ask the user to enter any SQL
statement in a field. In this case, the entire statement is unknown. In both
of these cases, you need to set up a script that is prepared to receive
variables from the user.

Passing parameters to SQL statements

In dynamic SQL, an unknown variable or statement is passed from the
application to the script, the statement is prepared, and then executed.
After the statement is executed, the statement can be executed at a later
time, or the memory used by the statement can be released.
Unknown variables are called parameters. Dynamic SQL has two types of
parameters: input and output. Input parameters are the values that the
user types at runtime or are variables in a script. Output parameters are
the values the database returns to the application. The following
illustration shows the relationship between your form and your script
when the user types in input parameters:

Form
Input parameters

Form script

Prepared
statement
DBMS

Output
parameters

Chapter 1: Writing scripts

executes
statement

29

Writing a dynamic SQL section in a script

In dynamic SQL, you can execute a statement immediately or you can
prepare the statement and execute it later in the script or pass it to a
function to be executed. Whether you decide to execute it immediately or
later depends on how often you will execute the SQL statement.
The advantage of preparing a statement is that you can store the prepared
statement in an SQL handle and reuse the SQL handle in the future. An
SQL handle is used to refer to statements that have been prepared.
Throughout this guide, examples of SQL handles always have the _hndl
suffix to clearly show that the object is a handle, for example,
update_hndl. After you have prepared a handle, you can reuse the same
handle any number of times.
For a statement that is executed a single time only, for fastest execution
use the EXECUTE_SQL statement only. You do not need to prepare or
free this statement. The PREPARE_SQL and EXECUTE_SQL statement
combination is required only for multiple executions.
Examples of executing a statement immediately and preparing the
statement are described in the following paragraphs.
Example

For example, the following dynamic SQL statement immediately updates

the prices column to 5 dollars in all rows in the order table:
EXECUTE_SQL 'UPDATE order_tbl SET prices = 5';

In the next example, the price is updated to the value entered by the user:
FIELD text1
ON FIELD
INPUT
EXECUTE_SQL 'UPDATE order_tbl SET prices = ?' using $text1;

Example

In this example, the UPDATE statement is prepared by using the

PREPARE_SQL statement and the UPDATE statement is stored in an SQL
handle called update_hndl. Later in the script, the EXECUTE_SQL
statement executes the statement contained in update_hndl.
ON CREATE
PREPARE_SQL 'UPDATE order_tbl SET prices = ?' into
$update_hndl;
. . .
ON NOT CURRENT
EXECUTE_SQL $update_hndl USING $text1;

30

Unify VISION: 4GL Reference

To execute the contents of the update_hndl statement again, the same

EXECUTE_SQL statement is repeated:
EXECUTE_SQL $update_hndl USING $text1;

Example

After you have finished using the SQL handle, you use the FREE_SQL
statement to release memory resources. The following example frees the
resources held by the update_hndl SQL handle:
FREE_SQL $update_hndl;

Describing the SQL statement

After preparing a statement, you can get information about both sets of
parameters. Getting information about parameters is called describing the
parameters. A description is not required to execute a statement specified
by the user. However, your script may need parameter information at a
later time.
Unify VISION provides attributes to describe the input and output
parameters. In some products, the language provides a statement called
DESCRIBE to allow you to view the values of the input parameters. In
Unify VISION, the parameters are already described and you can access
the description by using SQL handle attributes. To get information about
input parameters on some DBMSs, you use these attributes:
INPUT_ACCELL_TYPE[ ]
INPUT_COUNT
INPUT_DB_COLUMN_TYPE[ ]
INPUT_DB_COLUMN_TYPE_CODE[ ]
INPUT_PRECISION[ ]
INPUT_SCALE[ ]

Similarly, after the DBMS receives the dynamic SQL statement, it returns
results. These results are called output parameters. Unify VISION
provides these attributes to display the value of the output parameters:
OUTPUT_ACCELL_TYPE[ ]
OUTPUT_COUNT
OUTPUT_DB_COLUMN_TYPE[ ]
OUTPUT_DB_COLUMN_TYPE_CODE[ ]
OUTPUT_NAME[ ]
OUTPUT_PRECISION[ ]
OUTPUT_SCALE[ ]

On SYBASE SQL Server, the values of these attributes are valid after the
statement is executed.
Chapter 1: Writing scripts

31

Each attribute is prefixed with an OUTPUT or INPUT term to reflect the

parameter type.
The following paragraphs describe the dynamic SQL attributes:
ACCELL type

Describes the data type of the input or output parameter.

Input data types are a Unify VISION data type, for
example, STRING or NUMERIC.

Database column type

Describes the DBMS column type. By default, the value
of this attribute is the same as the value of the
ACCELL_TYPE attribute except when the value is
DATE_TIME.
Database column type code
Describes the DBMS column type by displaying a
database code. The DBMS codes are database dependent.
One usage of database column type codes is to
distinguish between an AMOUNT or FLOAT data type.
Another example is to determine if the database column
is the DATE_TIME data type. With the database column
code, you can set the OUTPUT_ACCELL_TYPE to
either DATE or TIME.
Precision

Specifies the number of significant digits in a AMOUNT

or NUMERIC database column. In a STRING field,
precision specifies the number of characters in the
database column. In a FLOAT field, precision specifies
the number of bits.

Scale

Specifies the number of digits to the right of the decimal

point in an exact NUMERIC field.

Using an SQL handle

An SQL handle references an SQL statement. Similarly to all other
objects in Unify VISION, you declare the object the first time you use it.
An SQL handle is an object that must be UNDEFINED before you use it.
An SQL handle has three states: invalid, inactive, and active. If you
prepare a statement by storing the statement in an SQL handle and then
32

Unify VISION: 4GL Reference

execute the handle, the SQL handle will execute successfully because the
handle was active. The state changes to invalid if the SQL handle is
freed. Database operations can change the handle to inactive. If you
execute the handle at a later time, the SQL handle may have changed state
to inactive. Only valid SQL handles execute a statement correctly.

Events
The following events change the state of an SQL handle:
The SQL handle no longer contains a statement because you
released the contents by using the FREE_SQL statement.
On some databases, the database committed or rolled back the
transaction associated with an SQL handle.
The current schema has changed.
Invalid
PREPARE_SQL string_expression
INTO handle

PREPARE_SQL
(SYBASE SQL Server only)
Free SQL handle

Free SQL handle

EXECUTE_SQL SQL_handle_name
or PREPARE_SQL
Inactive

Active

Database operations, such as a

commit or rollback

For SYBASE SQL Server, the SQL handle attributes have invalid values
until after the EXECUTE_SQL statement.
An SQL handle has three states that are stored in two attributes:
IS_VALID and IS_PREPARED.

Chapter 1: Writing scripts

33

Attributes that describe state of SQL handle

IS_VALID

IS_PREPARED

State of SQL handle class

FALSE

NULL

Invalid. The SQL handle is not

currently associated with a
particular statement. Attributes
contain default values and should
not be referenced.

TRUE

TRUE

Active. Statement is prepared and

ready for execution. Attributes
accurately contain values based on
the prepared statements.

TRUE

FALSE

Inactive. The SQL handle is

associated with a statement but the
statement is not prepared. The
EXECUTE_SQL statement
automatically prepares the statement
again if you do not use the
PREPARE_SQL statement first.
STATEMENT_TEXT and
CONNECTION_NAME attributes
contain the last prepared statement.
All other attributes are set to default
values and should not be referenced.

Permitted operations
With an SQL handle, you can perform the following tasks:
Reference attributes, for example:
SET temp TO titles_hndl:OUTPUT_ACCELL_TYPE

Pass SQL handles as reference parameters to a function, for

example:
calculate_pay(titles_hndl)

34

Unify VISION: 4GL Reference

Execute VISION 4GL statements PREPARE_SQL,

EXECUTE_SQL, and FREE_SQL, for example:
ON CREATE
PREPARE_SQL 'UPDATE order_tbl SET prices = ?' into
$update_hndl;
. . .
EXECUTE_SQL $update_hndl USING $text1;
FREE_SQL $update_hndl;

Creating a handle
You can create an SQL handle by using it in a PREPARE_SQL statement.
If an undefined general variable is passed to a function as a reference
parameter and the function prepares an SQL statement into that variable,
then the variable becomes an SQL handle. The variable is an SQL handle
in the function and the calling script.

Example
The following example uses many of the dynamic SQL statements and
attributes. The script assumes that the user will enter an SQL SELECT
statement into the text1 field. After the user clicks on a button with the
developer-defined command execute_dsql, the script executes the
following steps:
Declares an array called answer that stores the rows returned from
a SELECT statement.
Prepares the SQL statement entered in the text1 field into an SQL
handle called user_hndl.
Verifies that text1 has a valid SQL statement. If errors were found
during preparation of text1, the user is asked to reenter or modify
the SQL statement.
Verifies that the user wants to execute that SQL statement.
If a column is of DATE_TIME data type, the user is asked to
choose the appropriate data type to be stored in the database.
Executes the user_hndl and stores the result of the SELECT
statement into the answer general array variable.
Chapter 1: Writing scripts

35

#include "sscodes.h"
FORM CLASS form0
PUBLIC MATRIX answer[1 to UNKNOWN ESTIMATING 10, 1 TO UNKNOWN ESTIMATING 10]
COMMAND execute_dsql
BEGIN
PREPARE_SQL $text1 INTO $user_hndl;
IF (status$() != SS_NORM) THEN
DISPLAY 'Wrong syntax. Modify your statement again.' FOR
FYI_MESSAGE WAIT;
ELSE
BEGIN
DISPLAY NOTICE 'Execute ' + $user_hndl:STATEMENT_TEXT + '
for the ' + $user_hndl:CONNECTION_NAME + ' database?'
LABELS 'YES' DEFAULT, 'NO' RESULT INTO user_answer
IF user_answer = 0 THEN
BEGIN
FOR (SET $j to 1; $j <= $user_hndl:COLUMN_INDEX;
SET $j to $j + 1)
BEGIN
IF $user_hndl:OUTPUT_DB_COLUMN_TYPE[j] = 'DATE_TIME'
THEN
BEGIN
DISPLAY NOTICE 'Would you like the output of ' +
$user_handl:OUTPUT_NAME[j] +
' in DATE or TIME data type?'
LABELS 'Date format'
DEFAULT, 'Time format' RESULT INTO format_answer
IF $format_answer = 0 THEN
SET $user_hndl[j]:OUTPUT_ACCELL_TYPE
TO 'DATE'
ELSE
SET $user_hndl[j]:OUTPUT_ACCELL_TYPE TO
'TIME'
END
END
END
SET $answer TO EXECUTE_SQL $user_hndl;
DISPLAY NOTICE 'Number of rows is ' +
$answer:ROW_UPPER_BOUNDS + ' Number of columns is ' +
$answer:COLUMN_UPPER_BOUNDS for fyi_message WAIT
END
END

Related information

For syntax information about the EXECUTE_SQL, FREE_SQL, LOCAL,

PREPARE_SQL, and SET statements, see Script statements in this
manual.

36

Unify VISION: 4GL Reference

For syntax information about the following attributes, seeAttributes

syntax descriptions in Unify VISION: Class Reference:
INPUT_ACCELL_TYPE[ ]
INPUT_COUNT
INPUT_DB_COLUMN_TYPE[ ]
INPUT_DB_COLUMN_TYPE_CODE[ ]
INPUT_PRECISION[ ]
INPUT_SCALE[ ]
OUTPUT_ACCELL_TYPE[ ]
OUTPUT_COUNT
OUTPUT_DB_COLUMN_TYPE[ ]
OUTPUT_DB_COLUMN_TYPE_CODE[ ]
OUTPUT_NAME[ ]
OUTPUT_PRECISION[ ]
OUTPUT_SCALE[ ]
STATEMENT_TEXT

Chapter 1: Writing scripts

37

Calling stored procedures from form scripts

If the DBMS supports stored procedures (also called database procedures

or remote stored procedures), you can call them from VISION 4GL
scripts, as described in this section. Stored procedures are supported by
these Unify VISION DBMS interfaces:
INFORMIX
INGRES (UNIX only)
ORACLE version 7
SYBASE SQL Server

Unify DataServer

Calling INFORMIX stored procedures

VISION 4GL scripts can include calls to INFORMIX stored procedures.
Stored procedures are pre-compiled sets of SQL statements that are
executed when called by other programs, such as a Unify VISION
application.

Declaring INFORMIX stored procedures

Before being used, an INFORMIX stored procedure must be declared as a
function in the EXTERN statement. When you declare the stored
procedure, you must specify its type, name, and parameters. An
INFORMIX stored procedure must be declared as ROW_VALUED.
Related information

For the syntax and usage description for the EXTERN statement, see page
263.
Using INFORMIX stored procedures
An INFORMIX stored procedure returns whatever is specified by the
RETURN statement. An INFORMIX stored procedure can be used by
itself or in place of a SET . . . SELECT statement.

38

Unify VISION: 4GL Reference

If the INFORMIX stored procedure is not declared as ROW_VALUED,

nothing will be returned. Furthermore, you must use the SET statement
when you call the INFORMIX stored procedure. If you call the
ROW_VALUED stored procedure without a SET statement, the resulting
rows are discarded.
In the following example, an INFORMIX stored procedure named
sp_items( ) is used in place of a SET . . . SELECT statement. The
sp_items( ) stored procedure selects data from a table named items,
where each selected row has an item cost greater than the argument
passed to sp_items( ).
The stored procedure definition contains these SQL statements:
CREATE PROCEDURE sp_items (cost MONEY)
RETURNING (INT, MONEY)
DEFINE K
INT;
DEFINE C MONEY;
SELECT item_key, item_cost INTO K, C FROM items
WHERE item_cost > cost
RETURN K, C;

The sp_items( ) stored procedure is declared in the following VISION

4GL EXTERN statement:
EXTERN STORED ROW_VALUED
FUNCTION sp_items(ge_value) ;

After being declared, sp_items( ) is called in the VISION 4GL script by

using the following statements:
SET $cnt TO 0 ;
SET $key, $item_cost TO sp_items(100.00)
EXECUTING
BEGIN
. . .
SET $cnt TO $cnt + 1 ;
END

Related information

Chapter 1: Writing scripts

For the syntax and usage description of the sp_return$( ) system

function, see page 538.

39

Calling INGRES database procedures

VISION 4GL scripts can include calls to INGRES database procedure.
Database procedures are pre-compiled sets of SQL statements that are
executed when called by other programs, such as a Unify VISION
application.

Declaring INGRES database procedures

Before being used, an INGRES database procedure must be declared as a
function in the VISION 4GL EXTERN statement. When you declare the
database procedure, you must specify its type, name, and parameters.
An INGRES database procedure must be declared as a STORED function,
with type NUMERIC. (For INGRES, the only type allowed for a STORED
function is NUMERIC; ROW_VALUED is not allowed.)
Related information

For the syntax and usage description for the EXTERN statement, see page
263.
Using INGRES NUMERIC database procedures
All INGRES NUMERIC database procedures return the numeric argument
of the RETURN statement that was executed to terminate the procedure.
The VISION 4GL sp_return$( ) system function can also be used to
return the numeric return value, of the last call to a database procedure.
INGRES NUMERIC database procedures can be used only within these

boundaries:
All parameters must be passed by value.
All select statements in a database procedure must assign their
results to local variables.
A select statement in a database procedure can return only a single
row of data; additional rows are ignored.
If a database procedure is called by a rule, the RETURN statement
cannot be used to return a value to the application.
If the database procedure is executed by firing a rule, instead of by
using the execute procedure statement, actions specified by the
whenever sqlmessage clause are ignored.
40

Unify VISION: 4GL Reference

You can use a NUMERIC database procedure wherever a function can be

used.
Example

In the following example, an INGRES NUMERIC database procedure

named dbp_limit( ) returns 1 when a customers charge is greater than
the account limit and returns 0 when the charge is less than the limit.
The database procedure definition contains these SQL statements:
create procedure dbp_limit
(custid char(30), charges money) as
begin
if (select cust_id, chrg_lim from customers
where cust_id = :custid and chrg_lim > :charges)
return 1;
else
return 0;
endif;
end;

Note that colons are used to indicate the procedures parameters.

The database procedure is declared in a VISION 4GL EXTERN statement:
EXTERN STORED NUMERIC
FUNCTION dbp_limit(custid, charges) ;

After being declared, dbp_limit( ) can be called in the 4GL script by

script by using either of the following statement groups:
SET $acct_stat TO dbp_limit($custid,$charges) ;

OR
dbp_limit($custid,$charges) ;
SET $acct_stat TO sp_return$() ;

The sp_return$( ) system function shown in the example obtains the

return value of the last call to a stored procedure.
Related information

For the syntax and usage description of the sp_return$( ) system

function, see page 538.
Using INGRES database procedures as statements
A call to an INGRES database procedure can also be used alone as a
statement, independent of a SET statement. In this case, any NUMERIC
return is discarded because the statement has no variables to assign
values to. You can obtain the return value by using the sp_return$( )
system function.

Chapter 1: Writing scripts

41

Related information

For the syntax and usage description for the EXTERN statement, see page
263.

Calling ORACLE stored procedures

The information in this section applies to only the ORACLE DBMS,
version 7.
You can call ORACLE version 7 stored procedures from VISION 4GL
scripts. To use an ORACLE version 7 stored procedure with a Unify
VISION application, simply follow the guidelines outlined in this section
for creating, declaring, and calling the stored procedure.

Creating a stored procedure for use with a Unify VISION

application
When you define an ORACLE version 7 stored procedure that will be
used with a Unify VISION application, follow these guidelines:
Write the stored procedure in ORACLE PL/SQL.
In the stored procedure definition, declare parameters in the
PL/SQL stored procedure definition as IN, IN/OUT, or OUT. Note
that only scalar data types are supported by VISION 4GL and that
boolean types cannot be passed to and from PL/SQL. See your
PL/SQL Version 2.0 manual for information about allowed data
type conversions.
You must define all the parameters for a remote stored procedure
before you call it. If all parameters are not defined, a status$( )
value of SS_UNDACL is returned.
For local stored procedures, ORACLE OUT parameters can be
UNDEFINED. If the type of the result parameter is undefined, the
type is derived from the type defined in the stored procedure. If
any IN or IN/OUT parameter is UNDEFINED in Unify VISION, a
status$( ) value of SS_UNDACL is returned.
All parameters are defined from the types defined for them in
Unify VISION. Parameter values are passed to and from the
ORACLE version 7 stored procedure using the Unify VISION type.
If the actual stored procedure expects a different type, then the
ORACLE PL/SQL processor tries to convert the type. If the PL/SQL
42

Unify VISION: 4GL Reference

processor cannot convert the type, a runtime error is generated, and

a status$( ) value of SS_DBINT is returned.
Boolean values and variables cannot be used as parameters to
stored procedures, because ORACLE version 7 does not support the
passing of boolean parameters to and from PL/SQL.
If you try to pass a boolean value from Unify VISION, a runtime
error is generated with a status$( ) return value of SS_UNSPTP. If
you try to call a stored procedure that expects a boolean value, a
runtime error is generated with status$( ) return value of
SS_UNDBTP.
(You can use the to_num$( ) system function to convert a boolean
value to integer so that it can be passed to a PL/SQL stored
procedure. After the integer value is returned from the stored
procedure, you can use the to_bool$( ) system function to convert
the value to boolean.)
The maximum length supported for LONG, VARCHAR2, and
CHAR is the same as supported in PL/SQL.
If the number of parameters that are specified in a stored procedure
declaration does not match the number in the stored procedure
definition, a runtime error is generated with a status$( ) return
value of SS_PARNTMCH when the stored procedure is called.
If the parameter mode as specified in the stored procedure
declaration is not compatible with the mode of the stored
procedure as defined, runtime errors are generated when the stored
procedure is called. For example, if the stored procedure is
declared as RESULT but is defined as ORACLE IN, or is declared
as VALUE but is defined as ORACLE OUT or IN/OUT, a status$( )
value of SS_MDNTMCH is returned.
All other stored procedure errors return the status$( ) value
SS_DBINT. The description of such errors can be found by calling
database error functions.

Declaring ORACLE stored procedures

To declare the ORACLE version 7 stored procedure, follow these steps:
1. In the EXTERN statement of a VISION 4GL script, declare the
stored procedure as a function of type STORED.
Chapter 1: Writing scripts

43

2. Specify the function return type as VOID or as a Unify VISION

data type, such as NUMERIC. ROW_VALUED stored procedures
are not supported by ORACLE (calling a ROW_VALUED stored
procedure generates a runtime error with a status$( ) return value
of SS_INVLSPTYP.)
3. The stored procedure name can be specified in the declaration with
the ORACLE notation:
schema_name.package_name.procedure_name@db_link
4. Declare the stored procedure function parameters as scalar, not list
or matrix variables. If parameters are IN parameters in the stored
procedure, declare them as value parameters in EXTERN. If
parameters are OUT or IN/OUT parameters in the stored
procedure, declare them as RESULT parameters in EXTERN.
The EXTERN declaration is used to determine whether an ORACLE
version 7 stored procedure is declared as a procedure (VOID) or as a
function that returns a value with the specified Unify VISION data type.
The VISION compiler will compile the VISION 4GL script whether or not
the stored procedure is available at compile time.
Calling ORACLE stored procedures
After you declare an ORACLE version 7 stored procedure, you can use
the stored procedure like any other function, but the stored procedure
must be used exactly as it is declared.
For example, if the stored procedure is a function but is declared as a
procedure (VOID), or the stored procedure is a procedure but declared as
some other function type, such as STRING or NUMERIC for example, a
runtime error is generated. The error that is generated depends on
whether the stored procedure is in the current database or in a database
that is accessed through a database link:
If the stored procedure is in the local database, the status$( ) return
value is SS_INVLSP.
If the stored procedure is in a database that is accessed through a
database link, the status$( ) return value is SS_DBINT. To obtain
the specific database error that occurred, call an error message
routine.
When you call the stored procedure, if the stored procedure name is not
qualified by the database connection name, the stored procedure is run
under the current forms database connection.
44

Unify VISION: 4GL Reference

Warning

Do not try to use overloaded functions with Unify VISION

applications. If you have a stored procedure that you customarily
overload (see your ORACLE PL/SQL Users Guide and Reference), you
can declare and call only one of its variations per VISION 4GL script.
However, you can declare and call one of the other variations of the
stored procedure from another script.
Use the OSPCACHESZ external preference to control the caching of
ORACLE stored procedures.
If the use of a stored procedure does not match the actual stored
procedure in the database, one or more errors will occur.

Calling SYBASE SQL Server stored procedures

The information in this section applies to only SYBASE SQL Server
databases.
VISION 4GL scripts can include calls to SYBASE SQL Server stored
procedures. SYBASE SQL Server stored procedures are pre-compiled sets
of Transact-SQL statements that are executed when called by other
programs, such as a Unify VISION application.

To use stored procedures with Unify VISION application, simply follow

the guidelines in this section for declaring and using stored procedures.
Other topics include these:
using SELECT statements in stored procedures
matching parameter data types for stored procedures
using system functions to monitor stored procedures
system function scope in nested SELECTs in stored procedures
returning RESULT parameters
using stored procedures as statements
defining macros as stored procedures
When you call the stored procedure, if the stored procedure name is not
qualified by the database connection name, the stored procedure is run
under the current forms database connection.
Chapter 1: Writing scripts

45

Declaring SYBASE SQL Server stored procedures

Before being called from a VISION 4GL script, a stored procedure must
be declared as a function in the EXTERN statement. When you declare
the stored procedure, you must specify its type, name, and parameters. A
SYBASE SQL Server stored procedure type can be either ROW_VALUED
or NUMERIC.
Related information

For the syntax and usage description for the EXTERN statement, see page
263.

Using ROW_VALUED stored procedures

A ROW_VALUED stored procedure returns rows from one or more
SELECT statements that are executed from the stored procedure. The
stored procedure can be used by itself or in place of a SET . . . SELECT
statement.
For SYBASE SQL Server, a ROW_VALUED stored procedure can be used
wherever a function can be used. Used as a function, a ROW_VALUED
stored procedure yields a numeric return status.
You can also use the VISION 4GL sp_return$( ) system function to obtain
a numeric return status for a ROW_VALUED stored procedure or use a
Transact-SQL OUTPUT parameter to return a RESULT parameter.
Note that the results of a ROW_VALUED stored procedure cannot be
stored to an array variable.
Example

In the following example, a ROW_VALUED stored procedure named

sp_items( ) is used in place of a SET . . . SELECT statement. The
sp_items( ) stored procedure selects data from a table named items,
where each selected row has an item cost greater than the argument
passed to sp_items( ).
For SYBASE SQL Server, the stored procedure definition contains these
Transact-SQL statements:
CREATE PROC sp_items @cost money
AS
SELECT item_key, item_cost
FROM items
WHERE item_cost > @cost

46

Unify VISION: 4GL Reference

The sp_items( ) stored procedure is declared in the following VISION

4GL EXTERN statement:
EXTERN STORED ROW_VALUED
FUNCTION sp_items(cost) ;

After being declared, sp_items( ) is called in the VISION 4GL script by

using the following statements:
SET $cnt TO 0 ;
SET $key, $item_cost TO sp_items(100.00)
EXECUTING
BEGIN
. . .
SET $cnt TO $cnt + 1 ;
END

Note that the same parameter name (cost) must be used to declare the
stored procedure in the EXTERN statement as was used to create the
stored procedure.
Related information

For the syntax and usage description of the SET statement, see page 359.
For the syntax and usage description of the sp_return$( ) system
function, see page 538.
Using NUMERIC SYBASE SQL Server stored procedures
You can use a NUMERIC type stored procedure wherever a function can
be used. For a NUMERIC stored procedure, use the VISION 4GL
sp_return$( ) system function to obtain a numeric return status for a
NUMERIC stored procedure or use a Transact-SQL OUTPUT parameter
to return a RESULT parameter.
If a NUMERIC stored procedure includes a SELECT statement for
choosing database rows, the row values are discarded.

Example

In the following example, a NUMERIC stored procedure named

sp_limit( ) returns 1 when a customers charge is greater than the account
limit and returns 0 when the charge is less than the limit. The stored
procedure definition contains these Transact-SQL statements:
CREATE PROC sp_limit @cust_ID char(30), @charges money
IF (SELECT cust_ID, chrg_lim FROM customers
WHERE cust_ID = @cust_ID AND chrg_lim > @charges)
RETURN 1
ELSE
RETURN 0

Chapter 1: Writing scripts

47

The stored procedure is declared in a VISION 4GL EXTERN statement:

EXTERN STORED NUMERIC
FUNCTION sp_limit(cust_ID, charges) ;

After being declared, sp_limit( ) can be called in the VISION 4GL script
by using either of the following statement groups:
SET $acct_stat TO sp_limit($cust_ID,$charges) ;

OR
sp_limit($cust_ID,$charges) ;
SET $acct_stat TO sp_return$() ;

The sp_return$( ) system function shown in the example obtains the

return status of the last call to a stored procedure.
Related information

For the syntax and usage description of the sp_return$( ) system

function, see page 538.
Returning RESULT parameters
NUMERIC and ROW_VALUED stored procedures can return RESULT
parameters. For SYBASE SQL Server, RESULT parameters are equivalent
to Transact-SQL OUTPUT parameters.

A RESULT parameter cannot be UNDEFINED.

Status and RESULT parameter values can be obtained only after the
stored procedure has finished executing. Selected row values are obtained
as each row is processed.
Using SELECT statements in stored procedures
A ROW_VALUED stored procedure can contain one or more SELECT
statements. SELECT statements are useful only in ROW_VALUED stored
procedures. If a NUMERIC stored procedure contains SELECT
statements, the selected rows are cancelled and ignored.
To execute multiple SELECT statements in a ROW_VALUED stored
procedure, you need only one VISION 4GL SET statement that includes
the call to the stored procedure. The SET statement must have an
EXECUTING block when the stored procedure returns values from more
than one selected row. Leaving the EXECUTING block ends execution of
the stored procedure.
48

Unify VISION: 4GL Reference

If each SELECT statement returns a different number of column values,

the SET statement must accommodate the largest number of column
values returned. For example, if the first SELECT returns one column
value, the second SELECT returns three column values, and the third
SELECT returns five column values, the SET statement must contain five
variables.
For SYBASE SQL Server, a SELECT statement in a stored procedure can
also contain a COMPUTE clause. When multiple values are returned by
multiple SELECT statements or COMPUTE clauses, the variable_list in
the SET statement must contain as many variables as the largest number
of returned values.
Example

The following example stored procedure contains three SELECT

statements that return one, three, and five columns. Therefore, the SET
statement assigns values to five variables.
Stored procedure

First SELECT
Second SELECT

Third SELECT

. . .
SELECT col1
FROM table1
. . .
SELECT col1, col2, col3
FROM table2
ORDER BY col1
. . .
SELECT col1, col2, col3, col4, col5
FROM table3
. . .

Needs 1 variable
Needs 3 variables

Needs 5 variables

Required number of variables = 5

SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()
EXECUTING
. . .

Unify VISION SET statement

Matching data types in stored procedures

If the variables in the VISION 4GL SET statement are field variables,
target variables, or target field variables, their data types must match the
data types of the results returned by the SELECT statements in the stored
procedure.
Chapter 1: Writing scripts

49

If the variables in the SET statement are general variables, the data types
need not match. The data type of a general variable changes
automatically with each executing loop of the SET statement, depending
on the data type of the value assigned to the variable.
Before each executing loop of the SET statement, Unify VISION resets all
variables to UNDEFINED, as shown in the following example:

Reset variables
to UNDEFINED

SET $var1, $var2, $var3, $var4, $var5

TO stored_proc()
EXECUTING
. . .

Using system functions to monitor stored procedures

To determine the action to take on the values returned from a stored
procedure, you can use one or more of the following system functions:
sp_compute$( ) Returns TRUE if the last row returned by the stored
procedure is the result of a SYBASE SQL Server
Transact-SQL COMPUTE statement.
sp_return$( )

Returns the return status of the last call to a stored

procedure. If the stored procedure does not have a
RETURN statement, sp_return$( ) returns 0.

sp_select$( )

Returns the index of the current SELECT in the stored

procedure. The first SELECT returns 1; the second
SELECT returns 2, and so on.

You can use the sp_compute$( ), sp_return$( ), and sp_select$( ) system

functions to monitor stored procedures. You can use sp_compute$( ) and
sp_select$( ) at any time; use sp_return$( ) only after the stored
procedure has completed execution.
Example

50

In the following example, the SET statement assigns values returned

from multiple SELECT statements performed by the stored_proc stored

Unify VISION: 4GL Reference

procedure. The EXECUTING block of the SET statement uses

sp_select$( ) and sp_compute$( ) to determine which actions to take.

EXECUTING
block

Related information

Chapter 1: Writing scripts

SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()

EXECUTING
SWITCH sp_select$()
BEGIN
CASE 1:
/* $var1 contains value returned by SELECT #1
. . .
CASE 2:
IF (sp_compute$()) THEN
/* $var1 and $var2 contain values
returned by COMPUTE clause */
. . .
ELSE
/* $var1, $var2, and $var3 contain values
/* returned by SELECT #2
. . .
CASE 3:
/* $var1, $var2, $var3, $var4, and $var5
/* contain values returned by SELECT #3
. . .
END

*/

*/
*/

*/
*/

For the syntax and usage of the SET statement with stored procedures,
see page 359.

51

System function scope in nested stored procedure calls

When several stored procedure calls are nested in one EXECUTING
block, each stored procedure call can have an EXECUTING block, which
in turn can contain one or more calls to a system function. The scope of
each system function depends on the functions context, as shown in the
following example.
sp_call1 results:
sp_select$( ) &
sp_compute$( )

SET $p1, $p2 TO sp_call1()

EXECUTING
BEGIN
. . .
SET $p1, $p2 TO sp_call2()
EXECUTING
BEGIN
. . .
END
. . .

sp_call2 result:
sp_return$( )

SET $p1, $p2 TO sp_call3()

EXECUTING
BEGIN
. . .
END
. . .

END

Related information

sp_call2 results:
sp_select$( ) &
sp_compute$( )

sp_call3 results:
sp_select$( ) &
sp_compute$( )

sp_call3 result:
sp_return$( )

sp_call1 result:
sp_return$( )

For the syntax and usage for the following statement and system
functions, see the indicated pages:
SET statement (page 359)
sp_compute$( ) system function (page 536)
sp_return$( ) system function (page 538)
sp_select$( ) system function (page 541)

Using stored procedures as statements

A call to a stored procedure can also be used alone as a statement,
independent of a SET statement. In this case, any return, whether
52

Unify VISION: 4GL Reference

NUMERIC or ROW_VALUED, is discarded because the statement has no

variables to assign values to. However, RESULT parameters can be

returned. You can also obtain the return status by using the sp_return$( )
system function.

Defining macros as stored procedures

SELECT statements and ROW_VALUED stored procedure calls can be

used similarly. In a header file, you can define a macro that uses either a
stored procedure or a SELECT expression.
In this example, a header file contains two definitions for a macro named
ITEMSEL. The first definition uses the sp_items( ) stored procedure to
define ITEMSEL, and the second definition uses a SELECT expression.
The definition that is used depends on whether SPS_AVAIL is defined.
#ifdef SPS_AVAIL
#define ITEMSEL(amt) sp_items(amt)
#else
#define ITEMSEL(amt) SELECT item_key, item_cost \
FROM items WHERE item_cost > amt
#endif

The VISION 4GL script that uses the ITEMSEL macro would contain the
following statements:
SET $cnt TO 0 ;
SET $key, $item_cost TO ITEMSEL(100.00)
EXECUTING
BEGIN
SET $cnt TO $cnt + 1 ;
END

Chapter 1: Writing scripts

53

Using Unify DataServer stored procedures

To use a Unify DataServer stored procedure, you must first use the
SQL/A CREATE PROCEDURE statement to create the stored procedure.
After creating the stored procedure, you can call it from a Unify VISION
application.
SQL statements within a stored procedure must conform to the syntax
requirements of Unify DataServer. You cannot embed VISION 4GL

statements or clauses within the stored procedure.

Related information

For complete information about how to create stored procedures, see

your Unify DataServer manuals.
Declaring the Unify DataServer stored procedure
To declare a stored procedure, follow these guidelines:
1. Before calling the stored procedure, use EXTERN statement to
declare the stored procedure as a function of type STORED.
2. Specify the function return type as VOID or as a data type that is
compatible with the Unify DataServer DBMS data type, such as
NUMERIC.
3. Declare the stored procedure function parameters as scalar, not list
or matrix variables.
4. Make sure that the number of parameters that are specified in the
stored procedure declaration is the same as the number in the
stored procedure definition (CREATE PROCEDURE statement).
The EXTERN declaration is needed to determine whether the stored
procedure is declared as a procedure (VOID) or as a function that returns
a value with the specified data type.
If a stored procedure contains a call to another stored procedure, the
compiler will compile the calling stored procedure regardless of whether
the called stored procedure is available at compile time.
Calling stored procedures
You can call a stored procedure like any other function. For example, you
can use the SET statement to assign the value returned by a stored
procedure to a variable.

54

Unify VISION: 4GL Reference

When you call the stored procedure, the stored procedure is run under the
current database connection.

Nested stored procedure calls

Stored procedures and triggers can be nested. When several stored
procedure calls are nested in one EXECUTING block, each stored
procedure call can have an EXECUTING block, which in turn can contain
one or more calls to a system function.

Chapter 1: Writing scripts

55

56

Unify VISION: 4GL Reference

2
Script functions
This chapter describes the fundamentals of writing Unify VISION script
functions:
types of functions
defining a function
using a function
executing functions with timers
error-handler functions
building links for data transfer (Windows)

57

Types of functions

A function is a set of statements that perform a task in your application.

Functions are used to divide large tasks into modular units or to group a
set of procedures that are used repeatedly throughout a form or
application.
Functions can accept arguments, process or convert data, and return a
value.
Unify VISION provides predefined system functions that perform
common information processing tasks. If needed, you can also create
your own functions.
You can create two types of functions:
global functions
local functions
Although the types of functions are similar, each has a different purpose
and scope. The following table summarizes the types of functions you
can use and how they are created.
Summary of Unify VISION function features
Features

Global function

Statement types VISION 4GL

Local function
VISION 4GL

Definition

Each function is contained The function is defined

in its own script.
like a method within the
script where it is used.

Declaration

Declared in the form

header of every script
where it is used.

No declaration is required

(continued on next page)

58

Unify VISION: 4GL Reference

Summary of Unify VISION function features (continued)

Features
Advantages

Global function
Recursive

Local function
Fast execution

Can contain local

functions

Easily accesses local

variables of the form

Can be called from any

script

Within any single script, you can include up to 1,000 local

developer-defined functions.

Global functions
A global function can be called from any script within an application.
Use these functions to perform tasks that are required throughout your
application.
A global function contains these elements:
a function header
local variable definitions (optional)
local function definitions (optional)
function body
formal parameter definitions
A global function has the following advantages:
A global function can be called from any script in your
application.
A global function can define its own local functions.
A global function can be recursive; that is, it can call itself.
You must define each global function in its own script.
Global functions scope variables the same way as scripts do; a global
function can access the variables in all of its ancestor forms.
Chapter 2: Script functions

59

To call a global function from any script, you must declare the function in
the script where it is called.
Within a global function, you can define local functions. These local
functions can be called within the global function body.
Related information

For instructions for creating a global function, see Defining a class in

VISION Class Browser in Unify VISION: Developing an Application.

Scope of global functions

The scope of a global function includes any script that uses the EXTERN
statement to declare the global function.

Scope of global function variables

A global function can access the following values:
arguments passed to the function
local variables defined within the global function
local functions defined within the global function
global functions declared within the global function script
variables on previously active forms
The parameters and local variables of a global function can be accessed
within the global function and within any of the local functions that are
defined within it. Parameters of a global function are added to the list of
local variables.
When resolving variable references within a global function, VISION
compiler follows the normal Unify VISION variable scoping rules.
VISION compiler first checks for a form prefix. If no form prefix exists,
VISION compiler checks the function definition for a variable declaration
in the PRIVATE clause or one of its parameters. If the variable is not
declared locally, VISION Runtime Manager checks the current, calling
form and, if the variable is not referenced on this current form, VISION
Runtime Manager then checks the previously active forms for the
variable definition.
60

Unify VISION: 4GL Reference

Example

The following script statements show an example of a global function

definition. The highlighted area shows a local function definition within
the global function.

AMOUNT FUNCTION calculate_pay(gross_salary,

days_in_period, RESULT taxes)
PRIVATE net_salary, net_pay
LOCAL AMOUNT FUNCTION get_netpay(gross_salary,
RESULT taxes)
PRIVATE the_taxrate, net_pay
BEGIN
SET the_taxrate TO
SELECT tax_rate FROM rates
WHERE lower_sal <= $gross_salary
AND upper_sal >= $gross_salary;
SET taxes TO (gross_salary * the_taxrate)
SET net_salary TO $gross_salary - taxes
RETURN (net_salary)
END
BEGIN
SET taxes TO 00.00
SET net_salary TO get_netpay(gross_salary, taxes)
SET net_pay TO (net_salary / days_in_period )
RETURN (net_pay)
END

Variables defined in a script are available only if the form is active. When
you reference variables on other active forms within a global function,
you must make sure that the form you specify is active whenever the
global function is called. If the form is not active, the reference fails.
g Tip

To improve performance, when referencing variables on previously

active forms, include the form name prefix (form:) in all references.

Local functions
A local function can be called only from within the script where it is
defined. Use a local script function to perform a task that must be
repeated several times in a single form or function, to increase
readability, or for modularity.
Chapter 2: Script functions

61

A local function has the following advantages:

A local function can usually be executed more quickly than a
global function.
A local function can conveniently access local variables of the
calling form or global function.
A local function can be defined in these objects:
a global function
a script for a form class
A local function contains these elements:
formal parameter definitions (optional)
a function header including these formal parameters
local variable definitions (optional)
function body
Because the use of a local function is restricted to the form where it is
defined, you do not need declare a local function.
Defining a local function is equivalent to defining a new method. The
function body is equivalent to the statements of a script method. At
runtime, the local function is part of the current form.
When the local function is defined within a script, you can refer to local
variables on the calling form simply by name. You do not need the form
prefix (form:) with form variables.
Local functions cannot define other local functions.
Scope of local functions
The scope of a local function is all methods of the script that contains the
function definition. If the script includes several local function
definitions, a local function can also be called by any succeeding local
function definitions.
A local function can be called from any place where a local variable can
be accessed within the script. You can call a local function in any of the
form methods.
62

Unify VISION: 4GL Reference

VISION compiler handles a function name in a manner similar to a

variable name; there must be a definition of the function name to access,

or call, the function. The script file that contains the call to the function
must contain a function definition.

Scope of local function variables

A local function can access the following values:
local variables defined within the local function
variables defined within the script or function
variables on previously activated forms
The parameters and local variables of a local function can be accessed
only within the local function body. VISION compiler generates unique
names for each of these variables. Therefore, references to parameters
and local variables in a local function do not refer to any other variable
definitions, even variables of the same name defined elsewhere within
the script.
When resolving variable references within a local function, VISION
compiler follows the normal Unify VISION variable scoping rules. It first
checks for a form prefix. If no form prefix exists, it checks the function
definition or parameter for a variable declaration in the PRIVATE clause.
If the variable is not declared locally, VISION Runtime Manager checks
the current, calling form or function, and if the variable is not referenced
there, VISION Runtime Manager then checks the previously active forms
for a variable definition.
If a local function is defined within a global function, the local function
can refer to variables defined within the global function. To improve
performance, when referencing variables on other active forms, include
the form name prefix (form:) in all references.
When you reference variables on other active forms from within a local
function, you must make sure that the form you specify is active when
the calling form or function is active. If the form or function is not active,
the reference fails.
In a global function, local functions must be defined after the global
function header and before the global function body. The local function
definitions follow any local variable definitions.
Chapter 2: Script functions

63

In a script, all local functions must be defined after the form definition
statement (FORM) and before the form methods. The local function
definitions follow any local variable definitions.
Example

The following script statements show an example of a local function

definition. The highlighted area is the local function definition for
calculate_benefit( ) within the script benefits.
FORM benefits
PRIVATE net_salary, net_pay
LOCAL VOID FUNCTION calculate_benefit
(RESULT cum_benefit, benefit_rate,
days_in_period)
PRIVATE benefit
BEGIN
SET benefit TO benefit_rate * days_in_period
SET cum_benefit TO cum_benefit + benefit
RETURN
END

...
FIELD pay_period
METHOD ON FIELD
INPUT
SET days_in_period TO
SELECT num_days FROM pay
WHERE period_num = $pay_period;
METHOD AFTER FIELD
SET years_in_company TO
current_date$() - starting_date
SET v_rate, p_rate TO
SELECT vaca_rate, pers_rate FROM leave
WHERE years = $years_in_company;
calculate_benefit(vacation, v_rate, days_in_period)
calculate_benefit(personal, v_rate, days_in_period )
DISPLAY vacation FOR cum_vacation
DISPLAY personal FOR cum_personal

64

Unify VISION: 4GL Reference

Defining a function

A script function is created in the script associated with a form class. The
script function consists of two elements:
the FUNCTION header statement
the function body

The function header

The function header is the first line of the function definition. This
statement defines the function by providing the following information:
the type of function: global or local
the data type of the value returned by the function
the function name
the function parameters
The keyword FUNCTION identifies the statement as a function header.
Related information

For a complete description of the FUNCTION statement, see page 271.

Defining a global or local function

The first item in the function header is the function type. The function
type is indicated by the inclusion or absence of the keyword LOCAL. The
function type specifies whether the function is a local or global function.

Defining return values

If the function returns a value, the function header contains the data type
of the value to be returned. If no value is returned, the header contains
the keyword VOID.
Chapter 2: Script functions

65

The RETURN statement provides a convenient way to leave a function.

This statement can also include the value to be returned. This return
value can be a variable or an expression. You can include the RETURN
statement anywhere in the function body.

Defining function names

Function names follow the same naming conventions as other Unify
VISION variables. Global and local function names cannot exceed 44
characters.
Do not include a $ character as the last character of your function name.
All Unify VISION system functions have the $ character as the last
character of the function name. This character tells VISION compiler to
look in system archives for the function definition.
For a global function name, you must make sure that the function name is
unique within all scripts that call the global function. Any script that calls
the global function must not have any local functions with the same name
as the global function.
For a local function, the function name must be unique within the script
in which the local function is defined. The script that defines and calls the
local function must not have any local variables or other local functions
with the same name.

Defining function parameters

You can pass arguments to Unify VISION functions by using function
parameters. These optional parameters are local variables for the
function.
To do so, you must define a parameter list in the function header. The
parameter names cannot be duplicated in the functions local variable list.
Three types of parameters can be used in a Unify VISION function:
value parameters
result parameters
reference parameters
66

Unify VISION: 4GL Reference

Example

In the following example, the function parameter list has two parameter
definitions:
LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)

The first parameter, gross_salary, is a value parameter. The second

parameter, taxes, is a result parameter.

Value parameters
At the time of the function call, a value parameter receives the actual
value of the corresponding argument. A value parameter is treated as a
local variable and is initialized with the argument value when the
function is called.
Each time a function is called, VISION Runtime Manager initializes the
value parameters with the value and data type of the corresponding
function argument in the function call.
When you change the value of a value parameter within a function, you
are changing only the value of a variable local to the function. When
execution returns to the calling program, the argument value is
unchanged.

Result parameters
A result parameter is also a local variable. It too is initialized with the
argument value when the function is called.
However, if you change the value of a result parameter within a function,
you also change the value of the argument variable. As the function exits,
the value of the result parameter is copied back into the argument
variable after the function returns. When execution returns to the calling
program, the argument variables value is changed. The argument
variable now contains a new value: the value of the result parameter.
Because the result parameter value is copied back into the argument
variable, you can use result parameters to return values to the calling
function. You can then use the value of this result parameter value in the
calling function.
Chapter 2: Script functions

67

Reference parameters
When a function calls a parameter by reference, the value of the
parameter is not copied to the function. Instead, only the location of the
array or variable is used to provide access to the value.
The type of reference parameter is identified by a keyword:
LIST

For a one-dimensional array.

MATRIX

For a two-dimensional array.

REF[ERENCE] For a simple (scalar) variable.

Writing the function body

The body of the function contains Unify VISION statements for executing
functions. The function body is specified by a statement block consisting
of Unify VISION statements surrounded by the keywords BEGIN and
END.
Statements within the function body can access local variables defined by
the function, unqualified variables (variables that are not preceded by a
form name), and variables on other active forms (when they are preceded
by the form name).
Certain Unify VISION statements have special conditions or restrictions
on their use in a function.
Related information

68

For a list of statements that are valid in a function body, see the
description of the FUNCTION statement beginning on page 271.

Unify VISION: 4GL Reference

Using a function

To use a Unify VISION function within a script, follow these steps:

1. Include a function call in the script.
2. Declare the function within the script.
Each of these steps is described in the sections that follow.

Calling the function

You call both local and global functions with the same calling syntax that
you use to call external functions or Unify VISION system functions.
The following restrictions and conditions apply to making function calls:
A global function name must be the same as the function itself. For
example, if you create a global function called func2 in VISION
Development Environment, and execute the Edit Script command,
VISION Development Environment automatically enters
NUMERIC FUNCTION func0( ) in your script. If you rename your
global function, you must also rename it in the script.
A global function can recursively call itself. It can also call other
global functions if these functions are declared with the EXTERN
statement within the global function script file.
A local function can call a global function only if the global
function is declared with the EXTERN statement within the script.
When you define a local function within a global function script,
the local function can call any global functions declared within the
global function.
A global function can call any local functions that are defined in
the global function.
A local function may not be recursive; it can call only other local
functions that are defined within the same script file. If a file
contains several local function definitions, a local function can call
any other local functions that precede it in the file. A local function
cannot call a local function that is defined later in the file.
Chapter 2: Script functions

69

Both local and global functions can call any Unify VISION system
functions. They can also call external C language functions as long
as these external functions are declared in the same file with the
EXTERN statement.
Because a global function is executed as a separate form, some Unify
VISION system functions are reset when execution of the function is

begun. Restarted functions include these system functions:

aud_mode$( )
check_dirty$( )
current_record_count$( )
current_record_num$( )
is_current_record_stored$( )
last_command$( )
status$( )
record_is_current$( )
When VISION Runtime Manager encounters a call to a global function, it
searches the class libraries in the class library list for the function. The
class libraries are searched in the order that they are specified in the class
library list. When the function is located, it is executed and no other class
libraries in the list are searched. If the function is not found in any of the
class libraries, VISION Runtime Manager then looks in the current class
library. If the function is still not found, an error occurs.
g Tip

Related information

When using one of these restarted functions, save the value of the
function in a variable or pass in the value as an argument to the global
function. Then use the variable or argument within the global function to
access the value for the calling form.
For information about the class library list, see the Class Libraries panel
description in the Partition profile and partition group profile editors
chapter of Unify VISION: Developing an Application.
Syntax for calling a function
To call a function from within a script, you use this function call syntax:
function_name ( arguments )

70

Unify VISION: 4GL Reference

The function name must be listed exactly as it is defined in the

FUNCTION statement. Like Unify VISION variable names, Unify VISION
function names are case sensitive.
For example, if the function name is defined as get_netpay, you cannot
call the function with the name GET_NETPAY or Get_NetPay.
Regardless of whether your function has parameters, you must include a
pair of parentheses in the function call. For example, if the function
display_empid( ) has no parameters, the following statement shows a
sample function call for the display_empid( ) function:
SET exit_stat TO display_empid()

Returning a value
If a function returns a value, you must include some way for using the
function return value when you call this function: Either:
Save the return value to use elsewhere in the calling function.
or
Use the return value once.
If you want to use this return value several times in the calling function,
you can use the SET statement to assign the return value to a variable, for
example:
SET net_pay TO get_netpay( emp_gross, emp_taxes )

The data type of the variable in the calling function must match the data
type of the return value as it is defined in the function header.
Mismatched data types return unexpected data.
If you need a value only once, you can use the value directly in the
calling function. For example, the following IF statement calls
get_netpay( ) and uses the return value:
IF ( get_netpay( emp_gross, emp_taxes ) < 10,000.00 ) THEN

If you attempt to use the return value of a function that has been defined
as VOID, you will receive an UNDEFINED value.
Chapter 2: Script functions

71

Declaring the function

When you call a function within a script, VISION compiler must
determine whether the function name variable refers to a function rather
than to an Unify VISION variable. If the script file does not contain the
function definition, you must include a function declaration within the
script file.
A function declaration is different from a function definition:
function
definition

The function header, variables and statements that

describe what the function does.

function
declaration

Tells VISION compiler that the function name variable

refers to a function defined in another script.

To declare a global function within a script, use the EXTERN statement.

The EXTERN statement declares external functions within a script. This
statement is the function declaration for a function with a definition that
is not included in the same file as the function call.
Example

The following example shows a call to a global function.

EXTERN SCRIPT NUMERIC FUNCTION calculate_pay
(gross_salary, days_in_period, RESULT taxes)
#include sscodes.h"
FORM payperiod
FIELD emp_lname
METHOD ON FIELD
INPUT
SET emp_number, emp_gross TO
SELECT emp_id, gross_sal FROM employee
WHERE emp_lname = $emp_lname;
IF (status$() = SS_NORM) THEN
BEGIN
SET emp_id:CLEAR_FIND_EXP TO emp_number
NEXT ACTION IS FIND
END
ELSE
BEGIN
DISPLAY 'Invalid Employee Name'
FOR FYI_MESSAGE WAIT

72

Unify VISION: 4GL Reference

END

RESTART ON FIELD

FIELD pay_period
METHOD ON FIELD
INPUT
SET days_in_period TO
SELECT num_days FROM periods
WHERE period_id = $pay_number;
METHOD AFTER FIELD
SET emp_taxes TO $00.00
SET emp_net TO
calculate_pay(emp_gross, days_in_period, emp_taxes)

Chapter 2: Script functions

73

Using ORACLE system functions in scripts

The information in this section applies only to the ORACLE DBMS.

If you are using Unify VISION with the ORACLE DBMS, you can use
ORACLE system functions in VISION 4GL scripts. To use an ORACLE
system function, use the ORACLE DUAL table. This table is
automatically created when a user is created.
Use ORACLE system functions only in SQL DML statements, such as
SELECT or INSERT. In other VISION 4GL statements, use VISION 4GL
system functions.
Example

The following example shows how to access the TRUNC( ) system

function through VISION 4GL and the DUAL table.
SET $dvar TO SELECT TRUNC($a/$b, 2) FROM DUAL;

Related information

For more information about ORACLE system functions, see your

ORACLE DBMS manuals.

74

Unify VISION: 4GL Reference

Executing functions with timers

A timer is an application event that is executed after a specified time
period. When the timer event is activated, a specified global function is
executed. This section describes the following tasks:
example of a timer
declaring a timer event
creating a timer event
deleting a timer event

Timer event example

For example, to display up-to-the-minute stock market quotations, you
could install a timer at regular intervals. Each time the timer event
occurs, its global function is executed to read an external file and update
the stock market information on the screen.
Related information

For complete descriptions of the timer statements described in this

section, see Script statements in this manual.

Declaring a timer event handler function

You must declare a timer event handler function before it can be
referenced in a CREATE TIMER EVENT statement. The timer event
handler function must be global and declared in an EXTERN VISION
TIMER FUNCTION statement.

Creating a timer event

You must create the timer event by using the CREATE TIMER EVENT
statement.
The CREATE TIMER EVENT statement installs a request for a timer
event. When the timer expires, the specified function is executed. The
specified function must have been previously declared and defined as a
TIMER FUNCTION.
Timer events can occur only once per installation. To execute a timer
event function again, the timer event request must be reinstalled.
Chapter 2: Script functions

75

Deleting a timer event

For a variety of reasons, you may want to delete a timer event before its
time limit has elapsed. For example, if you have requested a find
operation to be performed in 10 seconds, you may want to remove that
request after user input.
To remove a specific timer event, use the DELETE TIMER EVENT
statement. To delete all timer events, use the DELETE ALL TIMER
EVENTS statement.
The DELETE TIMER statements remove the timer event request from
various internal queues, thus preventing the timer event from being
executed.

76

Unify VISION: 4GL Reference

Error-handler functions

In a script you can define and install functions for handling runtime
errors. This section describes these tasks:
elements of a script used by error-handler functions
defining an error function
declaring the error-handler function
installing an error-handler function
By default, runtime errors are displayed to the user in a popup window.
Errors can result from interactive actions by the user or from script
conditions. You can use an error-handler function to suppress display of
an error message, depending upon the condition. Suppressed error
messages are instead written to the file specified by the AMGR_ERFL
external preference.
To suppress display of an error message, use a RETURN (TRUE)
statement in the function body. If the function body includes no RETURN
clause or specifies RETURN (FALSE), the standard error message
window appears.
When you use VISION Debugger to debug an application or form, all
error messages are displayed, regardless of error-handler specifications.
Example

In this example, the default error message window is allowed to appear

when a specific user error occurs:
IF (error_info[ERRNUM] = 8835) THEN
RETURN (FALSE);

Elements used by an error-handler function

Error-handler functions use the following Unify VISION features:
DEINSTALL, EXTERN, FUNCTION, and INSTALL statements

status$( ) system function

dbmserrs.h, sscodes.h, and scrpterr.h header files
Chapter 2: Script functions

77

To use an error-handler function, follow these steps:

1. First create it as a global function.
2. Declare and install the function in the script where it is called.
You can also deinstall an error-handler function in places where it is no
longer required.

Defining an error handler

You define the error-handler function in a separate script. The file can
include the dbmserrs.h, sscodes.h, and scrpterr.h header files. These
files are located in the $VISION_HOME/include directory. The
dbmserrs.h file defines values passed to the error-handler function. The
sscodes.h file defines the values returned by the status$( ) system
function. The scrpterr.h file defines the values passed to a
SCRIPT_ERROR function.
Example

The following example shows a file that defines an error handler named
deadlock_handler:
#include <sscodes.h>
#include <dbmserrs.h>
DBMS_ERROR FUNCTION deadlock_handler (LIST error_info)
BEGIN
IF (error_info[INTR_FLAG] = TRUE) THEN
DISPLAY NOTICE 'Warning! Deadlock!';
ROLLBACK WORK;
END;

Example

The following example shows a file that defines a script error handler
named script_err_handler:
#include <scrpterr.h>
SCRIPT_ERROR FUNCTION script_err_handler (LIST error_info)
BEGIN
IF (error_info[FATAL] = TRUE) THEN
DISPLAY NOTICE WITH TEXT 'User warning! Exiting the
application!'
WAIT;
RETURN (TRUE);
END;

78

Unify VISION: 4GL Reference

Declaring a DBMS error handler

In the script, you must declare a DBMS error-handler function as a global
FUNCTION, using the following syntax:
EXTERN SCRIPT DBMS_ERROR FUNCTION function_name
(LIST error_info)

The error handler function returns its status in a reference parameter

(LIST error_info); this parameter is a one-dimensional array consisting of
the following six elements, as defined in the dbmserrs.h file:
0

ACC_STATUS (NUMERIC) Provides the status return value. Values are

the same as those returned by the status$( ) system

function.
1

DBMS_ERR

DBMS_OPRN (NUMERIC) Provides the value defined in the

(NUMERIC) Provides the error code returned by the

DBMS. Values are the same as those returned by the
dbms_status$( ) system function.
dbmserrs.h file for the database operation type.

INTR_FLAG

(BOOL) Indicates whether the operation was interactive

(TRUE) or noninteractive (FALSE).

For an interactive operation:

4

INTR_OPRN

(NUMERIC) Specifies the operation (add, commit, delete,

find, or update) that caused the error.

For a noninteractive operation:

4

CODE_SECTION

Specifies the method as defined in the dbmserrs.h file.

5

FUNC_NAME (STRING) If the error is caused by a noninteractive

operation within a function, provides the function name.

Declaring a script error handler

In the script, you must declare a script error-handler function as a global
FUNCTION, using the following syntax:
EXTERN SCRIPT SCRIPT_ERROR FUNCTION function_name

(LIST error_info)
Chapter 2: Script functions

79

The script error handler function returns its status in a reference

parameter (LIST error_info); this parameter is a one-dimensional array
consisting of the following six elements, as defined in the scrpterr.h file:
0

FATAL

(BOOL) Indicates whether the operation was fatal

(TRUE) or recoverable (FALSE).

ERRNUM

(NUMERIC) The error number returned by VISION

Runtime Manager.

ERRTEXT

(STRING) The text of the error message returned by

VISION Runtime Manager.

OBJREF

(OBJECT_REF) The OBJECT_REF of the object that

caused the error.

For an interactive operation:

4

ISFORM

(BOOL) Indicates whether the error was caused by a

form (TRUE) or a global function (FALSE).

For a global function script error:

5

FUNCNAME

(STRING) Specifies the name of the global function that

caused the error.

For a script error:

5

CODESEC

(STRING) Specifies the name of the method that caused

the error.

CODELINE

(NUMERIC) Specifies the line number in the script where

the error occurred.

Installing an error handler

You must use the INSTALL statement to activate the error handler as
needed. The INSTALL statement enables you to specify specific errors
and to identify each installation of a particular error handler.
You can de-install an error handler when it is not needed by using the
DEINSTALL statement.
80

Unify VISION: 4GL Reference

Example

The following example shows portions of a script that installs and

deinstalls an error handler named deadlock_handler, which is assigned
an identifier named $deadlockid. This error handler is called only for the
SS_DEADLOCK status return error.
#include <sscodes.h>
EXTERN SCRIPT DBMS_ERROR FUNCTION deadlock_handler(LIST error_info)
ON CREATE
INSTALL DBMS_ERROR HANDLER deadlock_handler
FOR EVENTS SS_DEADLOCK
IDENTIFIED BY $deadlockid
...
ON DESTROY
DEINSTALL $deadlockid

Chapter 2: Script functions

81

Returning information about ORACLE version 7 or SYBASE

SQL error messages

The information in this section applies to only the ORACLE DBMS,

version 7and SYBASE SQL.
ORACLE Version 7 and SYBASE SQL can return multiple error messages

for a single executable statement. The error messages are returned as one
long string that contains embedded error numbers.
In a VISION 4GL script, to obtain information about the messages that
were returned for a statement, use these system functions:
sql_errmsg_count$( )
sql_errmsg_i$( )
dbms_status_i$( )
If you have existing scripts that obtain error message information through
the dbms_status$( ) system function and the sql_errmsg$( ) system
function, you can expect the following results:
dbms_status$( ) returns the first error code found in the string of
multiple messages.
sql_errmsg$( ) returns the entire string of multiple messages.
Note that the sql_state$( ) system function is not supported for ORACLE
or SYBASE SQL databases.

82

Unify VISION: 4GL Reference

Handling SYBASE SQL Server errors

The information in this section applies to only SYBASE SQL Server.
Special handling may be required for two types of SYBASE SQL Server
errors:
transaction abort errors
trigger errors

Handling SYBASE SQL Server transaction abort errors

Transaction abort errors are errors that cause SYBASE SQL Server to
abort the transaction. Although SYBASE SQL Server can generate
multiple errors for a single statement, Unify VISION gives you
information about only the most recent error, unless it is a transaction
abort error.
For transaction abort errors, you need to know not only that the
transaction has been aborted, but also what error caused the transaction to
be aborted. For example, if you try to insert the value 99999 into a
tinyint column, SYBASE SQL Server generates an overflow error and a
Transaction has been aborted error.
How transaction abort errors are handled in Unify VISION applications
depends on whether you perform interactive operations or perform
noninteractive operations through VISION 4GL.
Obtaining error messages for interactive operations
When you use Unify VISION interactively and the server aborts the
transaction, two error message boxes are displayed, one after the other.
The first message indicates the cause of the error. The second message is
a message that the server has aborted your transaction.
For example, if you use a trigger to insert a record, but the insert fails
because of a duplicate key value, the first message reads Attempt to
store a duplicate key, and the second message reads Transaction has
been aborted.
Chapter 2: Script functions

83

Obtaining error messages for noninteractive operations

through VISION 4GL
When you use VISION 4GL, if you want to display both error messages,
you must use these system functions:
1. Use the status$( ) system function to obtain the status code for the
error. For example, status$( ) returns -4 (SS_DUPK) when an
attempt is made to store a duplicate key.
2. Use the dbms_status$( ) system function to determine whether the
last statement that caused an error aborted the transaction. For
example, if the transaction was aborted, dbms_status$( ) returns
the SYBASE SQL Server error code 3618.
3. Use the sql_errmsg$( ) system function to retrieve the
corresponding SYBASE SQL Server message text. For example, for
error code 3618, sql_errmsg$( ) returns Transaction has been
aborted.

Handling SYBASE SQL Server trigger errors

Each SYBASE SQL Server table can have triggers defined for insert,
update, and delete operations. These triggers are activated (fired) after an
insert, update, or delete operation is performed on the table and can
execute any valid SYBASE SQL Server command.
If the work performed by the insert, update, or delete operation that fired
the trigger needs to be undone, a ROLLBACK statement must be
executed. The rollback aborts the entire current transaction, aborting the
current Unify VISION transaction as well.
To handle trigger errors, you need to be able to generate information
about trigger results, transaction rollback operation status, and error
severity, as described in the following subsections.

Generating information about trigger results

Because SYBASE SQL Server triggers cannot return a status through the
operation that fired the trigger, you must use the raiserror and print
statements to generate information about the triggers results. Both
statements call the SYBASE SQL Server error handler.
84

Unify VISION: 4GL Reference

The error number that is given to the error handler is different from the
normal SYBASE SQL Server error numbers. The following table shows
the ranges of error numbers that can be passed:
Statement

Error number range

print

none (SYBASE SQL Server errors)

1 through 20000

raiserror

20001 or above

Either print or raiserror can send a string to be used for an error

message to the error handling routine. The raiserror statement can also
send an error number in the range of 20001 or higher.
Unify VISION accepts the error numbers sent by print or raiserror and
saves the strings so that the appropriate message can be displayed. To
control how Unify VISION handles the SYBASE SQL Server errors, you
can use the SYBASE_MSGS and SYBASE_RB_ERRNUMS external
preferences.
To indicate which messages should be sent to Unify VISION, use the
SYBASE_MSGS external preference, which contains a list of strings
separated by commas:
Value

Result

none

Send SYBASE SQL Server error messages only

Errors

Send raiserror messages

Messages

Send print messages

Errors,Messages

Send raiserror and print messages

Messages,Errors

Send raiserror and print messages

These string values can be specified in uppercase or lowercase. The

default value is Errors.
If multiple errors are sent per database operation by using multiple calls
to either print or raiserror, only the last status and message is sent to
Unify VISION depending on the message severity (see Determining
Error Severity on page 86).
Chapter 2: Script functions

85

To be able to indicate whether a rollback was performed, use the

SYBASE_RB_ERRNUMS external preference, which contains a comma
separated list of error numbers in the raiserror range of greater than
20000.
Single numbers can appear in the comma separated list. A dash () in the
first or last character indicates that the range is open-ended. For example:
20001
2000121000
22000,2300023010,30000
27500
The default value is 20001, which assumes that every raiserror causes
a rollback.
When raiserror gets an error number that is in any of the listed ranges,
an error status informs Unify VISION that a rollback has occurred, thus
preventing an internal system error. The effect is similar to executing a
ROLLBACK WORK statement.
If the error given to raiserror indicates that a rollback has occurred, the
SYBASE_MSGS external preference is ignored, and the Unify error is
returned to VISION Runtime Manager.

Rollback guarantee
To ensure that the transaction is rolled back when the raiserror error
number indicates that a transaction was aborted, Unify VISION executes
an implicit rollback transaction operation. This ensures that an aborted
transaction is always rolled back, regardless of whether you have
explicitly issued a ROLLBACK WORK statement.
Determining error severity
Because multiple print and raiserror calls are possible, Unify VISION
must determine which one is the most important. The following list
indicates the types of errors in order of priority:
1. raiserror that indicates that a rollback occurred
2. SYBASE SQL Server errors (1 through 20000)
3. raiserror that indicates no rollback occurred
4. print (0)
86

Unify VISION: 4GL Reference

For example, if raiserror sends an error that indicates that a rollback (1)
was performed, and print is performed (4) at the same time, the rollback
raiserror is given priority. If two errors of the same priority are received,
the most recent error (the second) is given higher priority and sent to
Unify VISION.

Unify VISION errors

A Unify VISION error number is displayed on the screen with the
message given in the statement. Three error messages (numbers 11228,
11229, and 11230) can be sent to Unify VISION for an error that resulted
from an interactive operation. Each error message represents one of the
developer-defined errors that result from a call to print or raiserror.
Related information

For the syntax and usage of the ROLLBACK WORK statement, see page
348.
For the descriptions of the SYBASE_MSGS external preference and the
SYBASE_RB_ERRNUMS external preference, see External preferences
syntax descriptions chapter in Unify VISION: Application Reference.

Chapter 2: Script functions

87

Building links for data transfer

In Windows, data is transferred between applications through dynamic

data exchange (DDE). DDE enables two applications that are on a single
machine to send messages to each other and transfer data between them.
One application acts as the client, which requests and receives data from
another application. The application that sends data to the client
application acts as the server. The application can act as a client to one
application and as a server to another application.
Windows DDE protocol enables three types of links:
cold

A link in which the client requests the data each time that
the data is needed. The server sends the data only when it
is requested by the client.

hot

A link in which the client requests the data only once.

The server sends the data to the client whenever the data
changes.

warm

A link in which the server notifies the client that the data
has changed. The server does not send the data until the
client requests it.

You can build both hot and cold DDE links between the application and
other Windows applications. You cannot use warm links with a Unify
VISION application.

Building a link
When you build a link, you use the VISION 4GL INSTALL statement to
install a global function that acts as a DDE event handler. To deinstall the
DDE event handler function, you use the VISION 4GL DEINSTALL
statement.
The event handler function is used by Unify VISION to capture DDE
messages and pass them to the application through VISION 4GL. The
action taken depends on the message received.
88

Unify VISION: 4GL Reference

Handling DDE messages that are received

The INSTALL statement lets you install a global event handler function
for each DDE message that a server can receive from a client or that a
client can receive from a server. A client can trigger these events in a
DDE server:
EXECUTE_COMMAND
INITIATE_HOT_LINK
INITIATE_LINK
RECEIVE_DATA

REQUEST_DATA
TERMINATE_HOT LINK
TERMINATE_LINK

A server can trigger these events in a DDE client:

RECEIVE_DATA
TERMINATE_HOT_LINK
TERMINATE_LINK

You can use the DEINSTALL statement to deinstall one or all of the
global functions that are handling DDE events.
Sending DDE messages
In addition to using the INSTALL and DEINSTALL statements to install
DDE event handler functions, you can use several system functions to
send DDE messages from one application to another.
dde_get_data$( )
dde_get_hot_links$( )
dde_get_links$( )
dde_get_response$( )
dde_initiate_hot_link$( )
dde_initiate_link$( )

dde_request_data$( )
dde_send_command$( )
dde_send_data$( )
dde_terminate_hot_link$( )
dde_terminate_link$( )

All of these system functions return a numeric status code. For example,
a status of DDE_SUCCESS indicates that the function was successfully
completed. All other status values indicate that the function failed for a
specific reason. The status codes that can be returned by the DDE system
functions are defined in the ddecodes.h header file in the release include
directory.
Related information

For a complete description of the DEINSTALL statement, see page 213.

For a complete description of the INSTALL statement, see page 285.
For information about DDE-related system functions, see System
functions in this manual.

Chapter 2: Script functions

89

Building a cold link

A cold link consists of the sequence of events summarized in the
following diagram.
Cold link events

Client

Server
Initiate link for application, topic

Acknowledge application and topic availability

Request data item
Send data item
Terminate link
Terminate link

The method used for each event depends on whether the application is
acting as a server or as a client.
1. The client application initiates a link for a specific application and
topic. For example, the client application initiates a link for the
vision application and the CUSTOMER topic.
If the application is acting as a server, use the INSTALL
statement to install a global function to handle an initiate link
message sent by the client.
If the application is acting as a client, use the
dde_initiate_link$( ) system function to broadcast an initiate
link message to all applications that support DDE.
2. The server application acknowledges whether the application and
topic are available.
If the application is acting as a server, return the relevant status
in the initiate link event handler function.
If the application is acting as a client, the return status for the
dde_initiate_link$( ) function indicates the success or failure
of the link.
90

Unify VISION: 4GL Reference

3. If the requested application and topic are available, the client

requests a data item. For example, the client application requests
the ADDRESS data for the CUSTOMER topic that is associated
with the vision application.
If the application is acting as a server, use the INSTALL
statement to install a global function to handle a request data
message sent by the client.
If the application is acting as a client, use the
dde_request_data$( ) system function to send a request data
message.
4. The server either sends the data item or sends a message that the
data item is not available.
If the application is acting as a server, the request data event
handler function returns either the value of the data item or an
undefined value if the data item is not available.
If the application is acting as a client and the data item is
available, its value is stored in the result data variable that was
specified as an argument for the dde_get_data$( ) function.
Client event 3 (the client request for data) and server event 4 must
be repeated each time the data item is needed.

5. Either the server or the client can send the first message to
terminate the link. The server sends the message if the data is no
longer available; the client sends the message if the data is no
longer needed.
If the application is acting as a server, use the
dde_terminate_link$( ) system function to send a terminate
link message to the client. Use the INSTALL statement to install
a global function to handle a terminate link message sent by the
client.
If the application is acting as a client, use the
dde_terminate_link$( ) system function to send a terminate
link message to the server. Use the INSTALL statement to
install a global function to handle a terminate link message sent
by the server.
Chapter 2: Script functions

91

Building a hot link

A hot link consists of the sequence of events summarized in the
following diagram.
Hot link events

Client

Server

Initiate a link (conversation) for an application, topic

Acknowledge application and topic availability
Initiate a hot link for a data item
Acknowledge data item availability

Send data item when it is updated

Terminate the hot link for the data item
Terminate the hot link for the data item
Terminate link (conversation) for the application and topic
Terminate link (conversation) for the application and topic

The method used for each event depends on whether the application is
acting as a server or as a client.
1. The client application initiates the link for a specific application
and topic. For example, the client application initiates a link for the
vision application and the CUSTOMER topic.
If the application is acting as a server, use the INSTALL
statement to install a global function to handle an initiate link
message sent by the client.
If the application is acting as a client, use the
dde_initiate_link$( ) system function to broadcast an initiate
link message to all applications that support DDE. If
acknowledged positively, a conversation is initiated between
the client and server.
92

Unify VISION: 4GL Reference

2. The server application acknowledges whether the application and

topic are available.
If the application is acting as a server, return the relevant status
in the initiate link event handler function.
If the application is acting as a client, the return status for the
dde_initiate_link$( ) function indicates whether a server is
available to service the request.
If the application and topic are available and a link is initiated, a
conversation is opened between the client and server.
3. If the requested application and topic are available, the client
initiates a hot link for a specific data item that is needed. For
example, the client application indicates that it needs the
ADDRESS data for the CUSTOMER topic that is associated with
the vision application.
If the application is acting as a server, use the INSTALL
statement to install a global function to handle an initiate hot
link message sent by the client.
If the application is acting as a client, use the
dde_initiate_hot_link$( ) system function to indicate that a
data item is needed by the client.
4. The server acknowledges whether the data item is available.
If the application is acting as a server, return the relevant status
in the initiate hot link event handler function.
If the application is acting as a client, the return status for the
dde_get_response$( ) function indicates the success or failure
of the link.
After a conversation is opened between the client and server, the
client can initiate hot links for any of the data items that are
associated with the topic. Thus, for each conversation opened by
dde_initiate_link$( ), the client can initiate a number of hot links
(dde_initiate_hot_link$( )).
5. The server sends the data item each time the data is updated.
If the application is acting as a server, use the
dde_send_data$( ) system function to send the data item value
to the client application.
If the application is acting as a client, use the INSTALL
statement to install a global function to handle a receive data
message sent by the server.
Chapter 2: Script functions

93

6. Either the server or the client can send the message to terminate
the hot link for the data item. The server can send the message if
the data item is no longer available. The client can notify the
server when the data item is no longer needed.
If the application is acting as a server, use the
dde_terminate_hot_link$( ) system function to send a
terminate hot link message to the client. Use the INSTALL
statement to install a global function to handle a terminate hot
link message sent by the client.
If the application is acting as a client, use the
dde_terminate_hot_link$( ) system function to send a
terminate hot link message to the server. Use the INSTALL
statement to install a global function to handle a terminate hot
link message sent by the server.
7. The server acknowledges that the client no longer needs the data
item (terminates the hot link for the data item).
If the application is acting as a server, and the terminate hot
link message is received, the hot link is terminated, regardless
of whether the INSTALL statement was used to install a global
function to handle terminate hot link events.
If the application is acting as a client, the return status for the
dde_terminate_hot_link$( ) function indicates the success or
failure of the terminate hot link message.
8. Either the server or the client can send the message to terminate
the link for the application and topic (closes the conversation
between the client and server).
If the application is acting as a server, use the
dde_terminate_link$( ) system function to send a terminate
link message to the client. Use the INSTALL statement to install
a global function to handle a terminate link message sent by the
client.
If the application is acting as a client, use the
dde_terminate_link$( ) system function to send a terminate
link message to the server. Use the INSTALL statement to
install a global function to handle a terminate link message sent
by the server.

Writing DDE event handler functions

When you write global DDE event handler functions, follow the
guidelines given in this section. The guidelines are presented in the form
94

Unify VISION: 4GL Reference

of tables that summarize the expected syntax and return values for each
function. You must provide the arguments and return values; Unify
VISION does not provide them.
Use the EXTERN statement to declare each global DDE event handler
function. Use the INSTALL statement to install the function, and use
DEINSTALL to deinstall the function. Make sure that the name of the
function that is declared in the EXTERN statement is the same as the
function name that is passed to the INSTALL statement.
The examples that start on page 101 illustrate how the global DDE event
handler functions are used with the DDE system functions to handle links
between Unify VISION clients and servers.

For execute command DDE events

Write a Boolean DDE event handler function to handle execute command
messages. If this function is installed, it will be called when a client asks
Unify VISION to execute a command. The execute command event
handler function is responsible for execution of the requested command.
Event: Execute command
Syntax:

BOOL FUNCTION exec_command_func(client_ID,

command_name)
where exec_command_func is the name of the function
to handle execute command events.
Arguments:

(NUMERIC) client_ID
The link ID of the client that asked for the
command to be executed. The link ID is passed
to the function by VISION Runtime Manager.
(STRING) command_name
The name of the command to be executed.

Return Values: TRUE

The command has been executed successfully.

FALSE The command could not be executed

successfully.

Chapter 2: Script functions

95

For initiate hot link DDE events

Write a Boolean DDE event handler function to handle initiate hot link
messages. If this function is installed, it will be called when a client sends
an initiate hot link message for a specific data item.
This function returns TRUE if the hot link will be established. After the
hot link is established, the server will use the dde_send_data$( ) function
to send the client a new copy of the data item each time that the data is
updated.
Event: Initiate hot link
Syntax:

BOOL FUNCTION init_hot_link_func(client_ID, item)

where init_hot_link_func is the name of the function to

handle initiate hot link events.
Arguments:

(NUMERIC) client_ID
The link ID of the client that is to send the
request for a hot link. The client link ID is
passed to the function by VISION Runtime
Manager.
(STRING) item
The name of the item for which data was
requested.

Return Values: TRUE

The hot link will be established.

FALSE The hot link will not be established.

96

Unify VISION: 4GL Reference

For initiate link DDE events

Write a Boolean DDE event handler function to handle initiate link
messages. If this function is installed, it will be called when a client sends
an initiate link message.
Event: Initiate link
Syntax:

BOOL FUNCTION init_link_func(client_ID,

application, topic)
where init_link_func is the name of the function to
handle initiate link events.
Arguments:

(NUMERIC) client_ID
The link ID of the client that requested the link.
The link ID is passed to the function by
VISION Runtime Manager.
(STRING) application
The application that was specified by the
client.
(STRING) topic
The topic that was specified by the client.

Return Values: TRUE

The DDE link will be established.

FALSE The DDE link will not be established.

Chapter 2: Script functions

97

For receive data DDE events

Write a Boolean DDE event handler function to handle receive data
messages. If this function is installed, it will be called when a client sends
data to a server or a server sends data to a client.
Event: Receive data
Syntax:

BOOL FUNCTION

receive_data_func(client_or_server_ID, item, data)

where receive_data_func is the name of the function to
handle receive data events.
Arguments:

(NUMERIC) client_or_server_ID
The link ID of the client or server that sent the
data. The ID is passed to the function by
VISION Runtime Manager.
(STRING) item
The name of the data item for which data was
sent.
(TEXT) data
The data value that was sent.

Return Values: TRUE

Informs the client or server that the data has

been accepted.

FALSE Informs the client or server that the data has

been rejected.

98

Unify VISION: 4GL Reference

For request data DDE events

Write a string DDE event handler function to handle request data
messages and support cold links. If this function is installed, it will be
called when a client sends a request data message.
Event: Request data
Syntax:

TEXT FUNCTION request_data_func(client_ID, item)

where request_data_func is the name of the function to

handle request data events.
Arguments:

(NUMERIC) client_ID
The link ID of the client that requested the
data. The ID is passed to the function by
VISION Runtime Manager.
(STRING) item
The name of the data item for which data is
requested.

Return Values: Defined_TEXT_value

The value of the requested data.
Undefined
The application cannot provide the requested
data.

Chapter 2: Script functions

99

For terminate hot link DDE events

Write a void DDE event handler function to handle terminate hot link
messages. This function will be called when a client sends a terminate
hot link message. The DDE hot link is terminated regardless of whether
the function is installed.
Event: Terminate hot link
Syntax:

VOID FUNCTION term_hot_link_func(link_ID, item)

where term_link_func is the name of the function to

handle terminate link events.
Arguments:

(NUMERIC) client_or_server_ID
The link ID of the client or server that asked to
terminate the hot link. The client or server ID
is passed to the function by VISION Runtime
Manager.
(STRING) item
The name of the data item that is being sent to
the client by the server.

Return Values: None

100

Unify VISION: 4GL Reference

For terminate link DDE events

Write a void DDE event handler function to handle terminate link
messages. This function will be called when a client sends a terminate
link message. The DDE link is terminated regardless of whether the
function is installed.
Event: Terminate link
Syntax:

VOID FUNCTION

term_link_func(client_or_server_ID)
where term_link_func is the name of the function to
handle terminate link events.
Arguments:

(NUMERIC) client_or_server_ID
The link ID of the client or server that asked to
terminate the link. The ID is passed to the
function by VISION Runtime Manager.

Return Values: None

Examples
The following examples show how to create cold and hot links between
Unify VISION and other Windows applications.

Cold link server example

In this example, Microsoft Excel is the DDE client and the Unify VISION
application is the DDE server.
Excel macro

The Microsoft Excel macro obtains a customer name from the Unify
VISION application and transfers the value to the calling cell.
WChan=INITIATE("SCRIPT", "CUSTOMER")
=REQUEST(WChan, "NAME")
=TERMINATE(WChan)
=RETURN()

Chapter 2: Script functions

101

The following VISION 4GL statements enable the Unify VISION

application to act as a DDE server for the Excel macro. Topic is defined
as a table name, and Item is defined as a column in that table, so that the
table and column names can be used in a SET statement.
BOOL FUNCTION DDEInitiateLink(Client, Application, Topic)
BEGIN
IF ($Application = "VISION") AND ($Topic = "CUSTOMER")
BEGIN
SET $custclient TO $Client
/* custclient is a global */
RETURN (TRUE) /* initiate link */
END
RETURN (FALSE) /* DO NOT initiate link */
END
TEXT FUNCTION DDERequestData(Client, Topic, Item)
PRIVATE tmp
BEGIN
IF ($custclient = $Client) /* custclient is a global */
SET $tmp TO SELECT $Item FROM $Topic
RETURN ($tmp)
END
RETURN (UNDEFINED)
END

Form script statements

The following statements are in a script:

EXTERN SCRIPT BOOL FUNCTION DDEInitiateLink(val, val, val)
EXTERN SCRIPT STRING FUNCTION DDERequestData(val, val)
INSTALL DDE_EVENT HANDLER DDEInitiateLink
FOR EVENTS INITIATE_LINK
IDENTIFIED BY $initid
INSTALL DDE_EVENT HANDLER DDERequestData
FOR EVENTS REQUEST_DATA
IDENTIFIED BY $reqid

Hot link server example

In this example, Microsoft Excel is the DDE client, and the Unify VISION
application is the DDE server.
Excel macro

A Microsoft Excel data cell contains this macro:

=vision|CUSTOMER!NAME

102

Unify VISION: 4GL Reference

Form script statements

The following VISION 4GL statements enable the Unify VISION

application to act as a DDE server for a hot link. These statements are in a
script.
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN

SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT

BOOL
TEXT
BOOL
BOOL
BOOL
BOOL
VOID
VOID

FUNCTION
FUNCTION
FUNCTION
FUNCTION
FUNCTION
FUNCTION
FUNCTION
FUNCTION

DDEInitiateLink(val, val, val)

DDERequestData(val, val)
DDEStartHotLink(val, val)
DDEStopHotLink(val, val)
DDEReceiveData(val, val, val)
DDEExecuteCmd(val, val)
DDEAcknowledge(val, val, val)
DDETerminate(val)

The following matrix array is used to keep track of the active hot links.
Unify VISION searches through the array in the WHEN FIELD
CHANGES methods to determine whether an active hot link exists for a
particular variable.
LOCAL MATRIX hotlinks[1 TO UNKNOWN, 1 to 4], numhotlinks
SET numhotlinks TO 0

The following INSTALL statements can be put in the BEFORE

APPLICATION section of the master application script. The DDE event
handler global functions are called when DDE events are received by
Unify VISION.
INSTALL DDE_EVENT HANDLER DDEInitiateLink
FOR EVENTS INITIATE_LINK
IDENTIFIED BY $initid
INSTALL DDE_EVENT HANDLER DDERequestData
FOR EVENTS REQUEST_DATA
IDENTIFIED BY $reqid
INSTALL DDE_EVENT HANDLER DDEStartHotLink
FOR EVENTS INITIATE_HOT_LINK
IDENTIFIED BY $reqid
INSTALL DDE_EVENT HANDLER DDEStopHotLink
FOR EVENTS TERMINATE_HOT_LINK
IDENTIFIED BY $reqid
INSTALL DDE_EVENT HANDLER DDEReceiveData
FOR EVENTS RECEIVE_DATA
IDENTIFIED BY $reqid
INSTALL DDE_EVENT HANDLER DDEExecuteCmd
FOR EVENTS EXECUTE_COMMAND
IDENTIFIED BY $reqid

Chapter 2: Script functions

103

Global function scripts

The following global functions are placed in their own script files.
BOOL FUNCTION DDEInitiateLink(Client, Application, Topic
BEGIN
IF ($Application = "VISION")
BEGIN
IF ($Topic = "CUSTOMER")
SET $custclient TO $Client
/* custclient is a global */
RETURN(TRUE) /* initiate link */
END
RETURN (FALSE) /* DO NOT initiate link */
END

This function adds active hot links to the hotlinks array.

BOOL FUNCTION DDEStartHotLink(linkid, item)
BEGIN
SET numhotlinks TO dde_get_hot_links$(hotlinks)
RETURN (TRUE)
END

This global function removes a hot link from the hotlinks array when the
hot link is terminated by the client.
BOOL FUNCTION DDEStopHotLink(linkid, item)
BEGIN
SET numhotlinks TO dde_get_hot_links$(hotlinks)
RETURN (TRUE)
END

104

Unify VISION: 4GL Reference

Cold link client example

In this example, Microsoft Excel is the DDE server and the Unify VISION
application is the DDE client.
Form script statements

The following VISION 4GL statements enable the Unify VISION

application to act as a DDE client for Microsoft Excel.
SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id)
IF ($stat = DDE_SUCCESS) THEN
BEGIN
SET $stat TO
dde_request_data$($server_id, 'CELL1', $data, 10000)
/* time out after 10 seconds */
IF ($stat = DDE_SUCCESS) THEN
BEGIN
/* $data contains the value of CELL1 in the Excel */
/*
spread sheet Sheet1
*/
END
END

Hot link client example

In this example, Microsoft Excel is the DDE server, and the Unify
VISION application is the DDE client.
The following VISION 4GL statements enable the Unify VISION
application to act as a DDE client for Microsoft Excel.
BOOL FUNCTION DDEReceiveData(Link_id, Item, Data)
BEGIN
SET $screen_field TO $Data
RETURN TRUE
END
EXTERN SCRIPT BOOL FUNCTION DDEReceiveData(val, val, val)
INSTALL DDE_EVENT HANDLER DDEReceiveData
FOR EVENTS RECEIVE_DATA
IDENTIFIED BY $reqid
SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id)
IF ($stat = DDE_SUCCESS) THEN
BEGIN
SET $stat TO
dde_initiate_hot_link$($server_id, 'CELL1', 10000)
/* time out after 10 seconds */
IF ($stat = DDE_SUCCESS) THEN
BEGIN
/* Excel should now send CELL1 to VISION whenever */
/* the value changes. VISION receives the data
*/
/* through the ReceiveData event handler global
/* function.
END
END

Chapter 2: Script functions

*/
*/

105

Time-out handling example

In this example, the Unify VISION application is the DDE client.
BOOL FUNCTION DDEReceiveData(Link_id, Item, Data)
BEGIN
SET $screen_field TO $Data
RETURN TRUE
END
EXTERN SCRIPT BOOL FUNCTION DDEReceiveData(val, val, val)
INSTALL DDE_EVENT HANDLER DDEReceiveData
FOR EVENTS RECEIVE_DATA
IDENTIFIED BY $reqid
SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id)
IF ($stat = DDE_SUCCESS) THEN
BEGIN
SET $stat TO
dde_request_data$($server_id, 'CELL1', $data, 10000)
/* time out after 10 seconds */
WHILE ($stat = DDE_TIMEOUT)
BEGIN
SET $stat TO DDE_DENYREQ
IF (yesno$('Do you want to continue waiting for a DDE
response?', 0) ) THEN
BEGIN
SET $stat TO
dde_request_data$($server_id, 'CELL1', $data, 10000)
END
END
END

106

Unify VISION: 4GL Reference

3
Using the preprocessor
This chapter describes how to use a C preprocessor with Unify VISION:
defining preprocessor variables
defining variable values
including external files in a script

107

Using a preprocessor

Within a script, you can use standard preprocessor statements. These

preprocessor statements allow you to define special preprocessor
variables to perform conditional code compilation. These variables can
also be used to define macros. In addition, the preprocessor allows you to
include external operating system files in your VISION 4GL scripts.
When a script is compiled it is first processed by a preprocessor. The
preprocessor checks the script file for special preprocessor statements and
performs the indicated modifications on the script.
A preprocessor statement begins with a pound sign (#) in column 1. The
# character is followed by a preprocessor keyword that describes the
compiler directive.
By using preprocessor statements in your script, you can:
conditionally compile code
define preprocessor variables
define preprocessor macros
include external files into the script

108

Unify VISION: 4GL Reference

Defining preprocessor variables

You can use the preprocessor statement #define to define variables that
the preprocessor recognizes. The two forms of this statement are:
#define variable
#define variable value
The first form defines a preprocessor variable. The second form both
defines a preprocessor variable and assigns it a value. By convention,
preprocessor variable names are in UPPERCASE letters.
Within the script, you can use the following preprocessor statements to
test whether this variable is defined:
#ifdef variable
#ifdef variable
...
#endif
#else
...
#endif
Between the #ifdef and the #endif statements you can include either
VISION 4GL statements or other preprocessor statements. If you use the
#else statement, include one set of statements (executed if the #ifdef
variable is defined) between the #ifdef and the #else statements and the
second set (executed if the #ifdef variable is not defined) between the
#else and the #endif statements.

Using the #define statement

A common use of the #define statement is to define a debugging
preprocessor variable and then to surround debugging statements in your
script with the #ifdef and #endif statements based on whether this debug
variable is defined.
Chapter 3: Using the preprocessor

109

In the following example, a SET/SELECT statement verifies that the

customer table has a row with the key value entered in
customer_number. If the SET/SELECT encounters an error and the
preprocessor variable DEBUG is defined, the DISPLAY statement
displays the status$( ) error value in a notice box.
#define DEBUG
#include sscodes.h
FORM customer_entry
PUBLIC status_error
FIELD customer_number
METHOD ON FIELD
INPUT
SET customer_entry:cust_id TO
SELECT cust_id FROM customer
WHERE cust_id = customer_entry:customer_number;
IF ( ( SET status_error TO status$() ) = SS_NORM ) THEN
BEGIN
DISPLAY
Customer ID already defined. Please try again
FOR FYI_MESSAGE
RESTART ON FIELD
END
ELSE
IF ( status_error <> SS_NOREC ) THEN
BEGIN
DISPLAY Database Error FOR
FYI_MESSAGE
#ifdef DEBUG
DISPLAY status= + error FOR
FYI_MESSAGE
#endif
END

To undefine the DEBUG variable, you can either surround the #define
DEBUG statement with comment symbols or you can use the
preprocessor statement #undef DEBUG.

Using the #define variable statement

To define a preprocessor variable and assign a value to this variable, you
use the second form of the #define statement:
#define variable value
If the preprocessor variable is already defined, this form of the #define
statement assigns a value to the variable.
110

Unify VISION: 4GL Reference

The preprocessor variable can be redefined by another #define statement

and you can use previously defined variables within a variable definition.
Do not use aVISION 4GL keyword or variable as the name of a
preprocessor variable.
You can use this form of the #define statement to:
create a macro
create mnemonic names for program constants

Creating preprocessor macros

To create a macro, you assign a string of VISION 4GL statements to a
preprocessor variable. Within the VISION 4GL statements, you can use
the preprocessor variable name anywhere you want to use the associated
string of statements.
When your script is processed by the preprocessor, occurrences of the
macro name are expanded: the preprocessor variable is replaced with the
VISION 4GL statements.
You can use a macro only after it has been defined. You can include
macro definitions within a file with the #include statement.
For example, the following preprocessor statement tests whether the
return code of the status$( ) system function is successful:
#define

OK_STATUS

status$() =

SS_NORM

You can then use the preprocessor variable OK_STATUS anywhere you
need to test the success of an operation, for example:
IF ( OK_STATUS ) THEN
DISPLAY 'Operation Successful'
FOR FYI_MESSAGE WAIT

The macro definition can extend over multiple lines if you place the
backslash character (\) at the end of each line of the definition.
You can also define parameters for a preprocessor macro. Parameters are
useful for inserting VISION 4GL variables into the macro definition when
the macro is expanded.
Chapter 3: Using the preprocessor

111

Using parameters in a macro definition

#define LOCKCHECK(error)
\
SWITCH error
\
BEGIN
\
CASE SS_LMOUT:
\
DISPLAY 'Locking Error Encountered' \
FOR FYI_MESSAGE WAIT \
CASE SS_NORM:
\
DISPLAY 'Selected Row(s) Available' \
FOR FYI_MESSAGE WAIT \
DEFAULT:
\
DISPLAY 'Database Error: ' +
\
to_string$(error) \
FOR FYI_MESSAGE WAIT \
END

The following lines are expanded when the LOCKCHECK macro is

processed:
SET db_stat TO status$()
LOCKCHECK(db_stat)

The following lines are generated after expansion of the macro:

SET db_stat TO status$()
SWITCH db_stat
BEGIN
CASE SS_LMOUT:
DISPLAY 'Locking Error Encountered'
FOR FYI_MESSAGE WAIT
CASE SS_NORM:
DISPLAY 'Selected Row(s) Available'
FOR FYI_MESSAGE WAIT
DEFAULT:
DISPLAY 'Database Error: ' + to_string$(db_stat)
FOR FYI_MESSAGE WAIT
END

Defining program constants

The #define statement is also useful for creating names for program
constants. For example, you can use #define to define names for the
constant values in a SWITCH statement. The SWITCH statement must
have constant values in the CASE clauses.
112

Unify VISION: 4GL Reference

The statements shown in the following example define four shipping

codes as preprocessor variables. It then uses the preprocessor variable
names within the SWITCH statement instead of the integer shipping code
values. These mnemonic preprocessor variables make the code easier to
read.
#define
#define
#define
#define

UNKNOWN 0
RECEIVED 1
WAITING 2
SHIPPED 3
...
SWITCH ship_code
BEGIN
CASE RECEIVED:
DISPLAY 'Received' FOR ship_status
CASE WAITING:
DISPLAY 'Waiting' FOR ship_status
CASE SHIPPED:
DISPLAY 'Shipped' FOR ship_status
CASE UNKNOWN:
DISPLAY 'Unknown' FOR ship_status
END

Chapter 3: Using the preprocessor

113

Including external files

You can use the preprocessor statement #include to include operating
system files in your script. This statement has the form:
#include file_name
where file_name is the name of the include file. This file name can be
either an absolute file path name or a relative path name. If the path name
is relative, it is relative to the directory where you are compiling the
script. It is a C language and fourth generation language convention to
name all include files by appending a .h suffix.
When the script is processed by the preprocessor, the #include statement
is expanded: the include file name is replaced by the contents of the
include file. These include files can contain either VISION 4GL
statements or other preprocessor statements.
Example

The following statements use the #include statement to include two

external files in the script. The first #include includes the preproc.h file
that contains other preprocessor statements that can be used in the script.
The second #include includes the externs.h file that contains external
function declarations that can be used in the script.
#include <preproc.h>
#include <externs.h>
FORM example
METHOD ON CREATE
#ifdef DEBUG
DISPLAY 'Entering ON CREATE section'
FOR FYI_MESSAGE WAIT
#endif
IF NOT ( open_message_file$(MESFILE) ) THEN
BEGIN
DISPLAY OPENERR FOR FYI_MESSAGE WAIT
write_errlog (OPENERR, 'serious')
END

The preproc.h file contains:

#define DEBUG
#define MESFILE '/usr/application/messages'
#define OPENERR 'There was an error opening the error file'

114

Unify VISION: 4GL Reference

And the externs.h file contains:

EXTERN SCRIPT BOOL FUNCTION is_variable(variable_name)
EXTERN SCRIPT NUMERIC FUNCTION get_unique (table_name)
EXTERN C NUMERIC FUNCTION write_errlog(msg, status)
EXTERN MESSAGE_HANDLER corporate_logo RETURNING STRING
EXTERN MESSAGE_HANDLER profit USING (this_year, last_year)
RETURNING INTEGER

Related information

Chapter 3: Using the preprocessor

Some Unify VISION system functions require #include statements. For

complete information about how to use system functions, see System
functions beginning on page 403.

115

116

Unify VISION: 4GL Reference

4
Tokens and operators
This chapter describes the operators and expressions you can use in
VISION 4GL statements:
tokens and symbols
object operators
assignment operators
arithmetic operators
relational operators
logical operators
bitwise operators
null values
undefined values

117

Operators

An operator indicates the action to be performed upon an operand. Most

operators are special characters, such as the equal sign (=). Other
operators are VISION 4GL keywords, such as SET.
The following table shows the types of operators you can use in a VISION
4GL script. Each type of operator is described in this manual.
Types of operators used in scripts
Category

Operator

Description

Object

Member

>

Dereference

SET

(Binary)Variable and attribute

assignment

=>

(Binary/Unary) Clear-to-find
expression assignment

(Binary/Unary) Binary addition and

concatenation; unary plus

(Binary/Unary) Binary subtraction;

unary minus

(Binary) Multiplication

(Binary) Division

(Binary) Modulus

Assignment
operators

Arithmetic
operators

(continued on next page)

118

Unify VISION: 4GL Reference

Types of operators used in scripts (continued)

Category

Operator

Description

Relational
operators

<

(Binary) Less than

>

(Binary) Greater than

<=

(Binary) Less than or equal to

>=

(Binary) Greater than or equal to

(Binary) Equality

<>

(Binary) Inequality

LIKE

String pattern-matching or
pattern-exclusion operator (_ and %
metacharacters)

SHLIKE

String pattern-matching or
pattern-exclusion operator (? and *
metacharacters)

AND

(Binary) Logical AND

OR

(Binary) Logical OR

NOT

(Unary) Logical negation

&

(Binary) Bitwise AND

(Binary) Bitwise inclusive OR

(Binary) Bitwise exclusive OR

(Unary) Bitwise negation (ones

complement)

Null value
operators

IS NULL

(Unary) Null value equality

IS NOT NULL

(Unary) Null value inequality

Undefined
value
operators

IS UNDEFINED (Unary) Undefined value equality

Logical
operators

Bitwise
operators

Chapter 4: Tokens and operators

IS NOT UNDEFINED

(Unary) Undefined value inequality

119

Operands
An operand is an expression. Depending upon the associated operator, an
operand may have restrictions on its data type. Operands must be defined
and the operand data types must be compatible. Unify VISION performs
some automatic type conversion as needed before performing the
operations. The resulting type is determined by the data types of the
operands and the operation.
Most operators are binary and require two operand values:
operand1 operator operand2
In SQL statements only one operand of a binary operation can be a Unify
VISION variable.
A few Unify VISION operators are unary operators. A unary operator
requires only a single operand:
operator operand1
operand1 operator
In SQL statements a Unify VISION variable cannot be used as the operand
of a unary operation.

Precedence of operators
When several operators appear in a single expression, Unify VISION
must determine an order for evaluating them. To determine operator
evaluation order, Unify VISION uses precedence and associativity rules.
Precedence is the order or priority in which operators are applied to
operands. Unify VISION applies operators of higher precedence before
those of lower precedence. Associativity is the direction in which Unify
VISION evaluates operators at the same precedence level. Associativity is
either right to left or left to right.
Many operators are at the same level of precedence. To determine when
to evaluate operators at the same level of precedence, Unify VISION uses
associativity rules.
The following chart shows the precedence and associativity rules for all
Unify VISION operators. The operators are listed in order of decreasing
precedence.
120

Unify VISION: 4GL Reference

Precedence and associativity rules for Unify VISION operators

Precedence*

Operator
:
>
()
NOT

~
+ (unary)
(unary)
*
/
%
+ (binary)
(binary)
<
>
<=
>=
=
<>

Associativity
left to right
left to right
right to left

left to right

left to right
left to right

IS NULL
IS NOT NULL
IS UNDEFINED
IS NOT UNDEFINED
LIKE
SHLIKE

&
|
^

left to right

AND
OR
SET

left to right
left to right
left to right
Not applicable

=>

* Operands grouped between parallel lines have the same precedence.

Chapter 4: Tokens and operators

121

Expressions

An expression can be made up of several elements:

operators
developer-defined Unify VISION variables
system variables
function return values
constants
object attributes
Expressions can appear in a variety of VISION 4GL statements:
logical expressions in conditional statements and clauses
arguments of functions
operands of operators
database values
The following list shows examples of Unify VISION expression syntax:
( expr )
expr1 = expr2
expr1 <> expr2
expr1 + expr2
expr1 expr2
expr1 * expr2
expr1 / expr2
expr1 % expr2
expr1 & expr2
expr1 | expr2
expr1 ^ expr2
+ expr
expr
expr1 < expr2
expr1 > expr2
expr1 >= expr2
122

Unify VISION: 4GL Reference

expr1 <= expr2

expr1 AND expr2
expr1 OR expr2
NOT expr
expr =>
=> expr
expr1 >= expr2
expr1 > expr2
SET variable TO expr
SET variable TO SELECT column FROM table
attribute
form:attribute
[form:][$]variable:attribute
field_array[ ]
field_array[subscript]
field_array[subscript]:attribute
field_array[row, column]
field_array[row, column]:attribute
variable:attribute
form:variable:attribute
variable [NOT] LIKE mask ESCAPE escape_character
variable [NOT] SHLIKE mask

Chapter 4: Tokens and operators

123

Tokens and symbols

This section describes symbols, delimiters, and metacharacters that can
be used in application development.

Form script tokens

Special symbols and delimiters are used in statements and expressions to
separate or identify the elements of a script:
()

A pair of parentheses enclose function arguments or

delimit expressions.

In SQL statements a dollar sign ($) must precede all

Unify VISION variable names; it is optional in other
statements.
All Unify VISION system function names are suffixed by
a dollar sign ($). The dollar sign distinguishes a Unify
VISION system function from developer-defined
functions and database column names. Do not use a
dollar sign when you define or call your own functions.
If a dollar sign is required in the syntax of a database
SQL statement, it must be prefixed by a backslash (\$).

&

The & token can be used as a prefix to field names in a

field validation rule to specify the value of a field.
Preceding this token you can use one of three operators:
<

Less than

>

Greater than

Not equal to

Example

Meaning

<&total

Less than the value of the total field.

!&teller_name
Not equal to the value of the
teller_name field.
124

Unify VISION: 4GL Reference

The semicolon terminates a statement. A semicolon is

optional for most script statements; it is required after
SQL statements that are not contained within an SQL
block.

string

A pair of apostrophes enclose a literal string quotation. If

the string contains an apostrophe, precede the apostrophe
by a backslash (\) escape character.

The comma separates the elements of a statement.

variable

The name of a developer-defined variable can be

enclosed by a pair of quotation marks.
Variable names and other object names are case
sensitive: uppercase and lowercase letters are not
equivalent. For example, company_address and
Company_Address are two different variables.

Related information

See Attributes syntax descriptions chapter in Unify VISION: Class

Reference for information about the following attribute:
FIELD_VALIDATION_RULE

Metacharacters
The user can enter search criteria that include DBMS metacharacters.
However, if the DBMS does not provide a particular metacharacter, it is
interpreted as a literal character instead. To search for a character that is
reserved as a DBMS metacharacter, the user must enclose the character
within brackets ([ ]).
By default, the search range metacharacter is a hyphen (). However, the
search range metacharacter can be changed to any ASCII character by
setting the RNGMETACH preference.
Related information

See External preferences syntax descriptions chapter in Unify VISION:

Application Reference for information about the following external
preference:
RNGMETACH

Chapter 4: Tokens and operators

125

Member operator

The colon (:) is the member operator. You can reference the value of an
attribute by using any of these formats:
[$][form_name:]object_name:attribute
[form_name:][$]object_name:attribute
[$][form_name:]form_attribute
object_name:object_attribute
array_name[ ]:field_attribute
array_name[subscripts]:field_attribute
If a form name is not specified, the attribute applies to the current form.

126

Unify VISION: 4GL Reference

Dereference operator (>)

obj_ref_exp > identifier [ ( [parm[, parm . . . ] ] ) ]

obj_ref_exp

An expression that evaluates to an OBJECT_REF data

type that identifies the object to be operated on.

identifier

Specifies an attribute, variable, or method defined for the

class of object identified by obj_ref_exp.

parm

If identifier refers to a method defined for the class,

specifies the name of a parameter to be passed for the
method invocation.

In a script, you can use a dereference operator (>) to reference objects

identified by the OBJECT_REF data type. The dereference operator
permits the referencing of objects at runtime, whereas the colon operator
(:) references objects only at compile time.
The dereference operator can be used to reference attributes, variables,
and methods of an object.
Typical uses for the dereference operator include:
to reference an object ID passed into an ON DRAG DROP method.
to reference the parent form
to reference the parent object
to reference variables between subforms
to send synchronous messages to Form and Service objects rather
than using the SEND MESSAGE statement
You can reference the parent of a child by using the PARENT_ID
attribute. For objects on a form, the PARENT_ID is the parent form. For a
form, the parent is the previous form. The PARENT_ID of the first form
in an application is always NULL.
The dereference operator can be used to send a synchronous message to a
Service or Form object. obj_ref_exp identifies the object to which the
Chapter 4: Tokens and operators

127

message is directed. identifier specifies the method to be invoked on the

destination object. The return value of the method is returned as the result
of the dereference operator.
The dereference operator cannot be used in the following cases:
RETURN VALUES INTO clause

accessing individual array elements

RESULT parameters

g Tip

Example

To reference variables between two subforms within the same form, store
the subform object IDs in global variables.

In the following example, the dereference operator references the value

of the text1 field, and the value is stored in the current_value variable.
SET text1_id TO text1:OBJECT_ID
SET current_value TO text1_id->VALUE

In the next example, the dereference operator references attributes of the

created form.
COMMAND display_sample
BEGIN
CREATE FORM 'sample' OF CLASS runtime1
OBJECT_REF INTO $form_id
SET $form_id->TX_MODE_FORM_CREATION TO 'COMMIT'
SET $form_id->VISIBLE TO TRUE
END

In the next example, the to_string$( ) system function is used to test the
current transaction mode by displaying the contents of a dereferenced
object:
DISPLAY 'The transaction mode is ' +
to_string$(form_id->TX_MODE_FORM_CREATION) FOR FYI_MESSAGE WAIT

This example invokes the m1 method on the object identified by objid,

where m1 is a synchronous message.
set $rtnvalue TO objid->m1(p1,p2,p3)

128

Unify VISION: 4GL Reference

Related information

See the following related script statement and system functions:

SEND MESSAGE (page 354)

acquire_global_uvns$( ) (page 405)

acquire_local_uvns$( ) (page 406)
dap_4gl_errcode$( ) (page 433)
dap_td_count$( ) (page 434)
dap_td_errcode_i$( ) (page 435)
dap_ti_errcode$( ) (page 438)
status$( ) (page 551)
See Unify VISION: Class Reference for information about related classes:
UONameService class
UONameService::resolve( )
UONameService::bind( )
Service class
Form::OBJECT_ID
Service::OBJECT_ID

Chapter 4: Tokens and operators

129

Assignment operators
An assignment operator assigns a specific value to a variable or attribute.
VISION 4GL provides two types of assignment operations:
the SET statement
the clear-to-find expression

SET statement
The VISION 4GL assignment operator is the SET statement.
You can use the SET statement to change the values of variables and their
attributes:
general variables
field variables
target variables
target field variables
variable and form attributes
system variables
The SET statement automatically performs some type conversions if the
operands have different data types.
You can also use the SET statement to clear the value of a variable.
For a complete description and examples of the SET statement, see page
359.

Clear-to-find
The clear-to-find expression operator is a pair of characters: => (=
followed by > with no space between). You can use this operator to
change the value of clear-to-find expressions. Clear-to-find expressions
exist only for target field and target variables. They establish search
criteria to use during a database search.
130

Unify VISION: 4GL Reference

The clear-to-find expression operator specifies a less than, greater

than, or range of values as search criteria for a target field or target
variable. You can use this operator with target field and target variables
of any data type except BOOLEAN.
Use the SET statement to assign a clear-to-find expression to the field
target or target variables CLEAR_FIND_EXP target attribute.
The following table shows the different forms of the => operator.

Forms of the => operator

Clear-to-find expression

Search criteria

expr =>

Values greater than expr

=> expr

Values less than expr

expr1 => expr2

Values in the range from expr1 through

expr2. expr1 and expr2 must be the same
data types.

Variables containing null values can be used with the => operator.
However, if the clear-to-find expression evaluates to a null value, the
database search will not find any matching database rows.
Variables containing UNDEFINED values are illegal operands for the
clear-to-find expression operator. Invalid operands result in a runtime
error.
For examples of clear-to-find expressions, see the description for the SET
statement.

Chapter 4: Tokens and operators

131

Arithmetic operators
Arithmetic operators are not defined for BOOLEAN operands.

Addition
expr1 + expr2
The + operator is the addition operation for variables with the data types
NUMERIC, FLOAT, AMOUNT, DATE and TIME.
The following table shows the data types that are compatible with the +
operator. Operations on other combinations of data types are invalid.
Results of addition
First operand

Second operand

Result

AMOUNT

NUMERIC
FLOAT
AMOUNT

AMOUNT
AMOUNT
AMOUNT

DATE

NUMERIC

DATE

DATETIME

NUMERIC

DATETIME 1

FLOAT

NUMERIC
FLOAT
AMOUNT

FLOAT
FLOAT
AMOUNT

NUMERIC

NUMERIC
FLOAT
AMOUNT
DATE 2
DATETIME
TIME 2

NUMERIC
FLOAT
AMOUNT
DATE
DATETIME 1
TIME

TIME

NUMERIC

TIME

1 If a NUMERIC value is added to a datetime value, the NUMERIC value

is treated as the number of days to add to the date portion.
2 If a NUMERIC value is added to a TIME value, the NUMERIC value is
treated as number of minutes. If a NUMERIC value is added to a DATE
value, the NUMERIC value is treated as number of days.
132

Unify VISION: 4GL Reference

Concatenation
expr1 + expr2
The plus sign (+) is the concatenation operator for STRING, TEXT, and
BINARY values. When you concatenate two strings, you join them with
no spaces between them. Concatenation can be performed on STRING,
TEXT, and BINARY values only.
A concatenation with a null operand always results in a null value.
Concatenating an operand with a zero-length operand returns the original
value.

Results of concatenation
First operand

Second operand

Result

BINARY

BINARY

BINARY

STRING

STRING
TEXT

STRING
TEXT

TEXT

STRING
TEXT

TEXT
TEXT

Subtraction
expr1 expr2
The operator is the subtraction operation for variables with the data
types NUMERIC, FLOAT, AMOUNT, DATE and TIME. This operator is not
valid for variables of the STRING, TEXT, BINARY, or BOOLEAN data
types.
The following table shows the results of the subtraction operation
between data types. Operations on other combinations of data types are
invalid.
Chapter 4: Tokens and operators

133

Results of subtraction operation

First operand

Second operand

Result

AMOUNT

AMOUNT
FLOAT
NUMERIC

AMOUNT
AMOUNT
AMOUNT

DATE

DATE
NUMERIC

NUMERIC
DATE

DATETIME

DATETIME
NUMERIC
DATE

NUMERIC 1
DATETIME 2
NUMERIC 3

FLOAT

AMOUNT
FLOAT
NUMERIC

AMOUNT
FLOAT
FLOAT

NUMERIC

AMOUNT
FLOAT
NUMERIC

AMOUNT
FLOAT
NUMERIC

TIME

NUMERIC
TIME

TIME
NUMERIC

1 If a DATETIME value is subtracted from a DATETIME value, the

difference in number of days is the result.
2 If a NUMERIC value is subtracted from a datetime value, the
NUMERIC value is treated as number of days and subtracted from the
date portion of the DATETIME value.
3 If a DATE value is subtracted from a DATETIME value, the difference
in number of days is the result.

A NUMERIC result is produced by the subtraction of two NUMERIC

values. Any subtraction involving an AMOUNT value produces an
AMOUNT result. Subtraction involving a FLOAT value produces a FLOAT
result unless one of the operands is an AMOUNT value (result is then an
AMOUNT).
Subtraction performed on two DATE values produces a NUMERIC result.
This result is the number of days between the two dates. Similarly,
subtracting two TIME values produces a NUMERIC result that is the
number of minutes between the times.
134

Unify VISION: 4GL Reference

If a NUMERIC value is subtracted from a TIME value, the NUMERIC

value is treated as number of minutes and the result is a TIME value. If a
NUMERIC value is subtracted from a DATE value, the NUMERIC value is
treated as number of days and the result is DATE value.

Multiplication and division

expr1 * expr2
expr1 / expr2
The * operator is the multiplication operation for variables with the data
types NUMERIC, FLOAT, and AMOUNT. The / operator is the division
operation for variables with the data types NUMERIC, FLOAT, and
AMOUNT. Neither of these operators is defined for the BOOLEAN, DATE,
TIME, TEXT, BINARY, or STRING data types.
The following table shows data types that are compatible with the * and /
operators. Operations on other data types are incompatible.
Results of multiplication and division operations
First operand

Second operand

Result

AMOUNT

AMOUNT
FLOAT
NUMERIC

AMOUNT
AMOUNT
AMOUNT

FLOAT

AMOUNT
FLOAT
NUMERIC

AMOUNT
FLOAT
FLOAT

NUMERIC

AMOUNT
FLOAT
NUMERIC

AMOUNT
FLOAT
NUMERIC

A NUMERIC result is produced only by the multiplication of two

NUMERIC values. Any multiplication involving an AMOUNT value
produces an AMOUNT result. Multiplication involving a FLOAT value
produces a FLOAT result, unless one of the operands is an AMOUNT
value (result is then an AMOUNT).
Division by zero produces a runtime error. Make sure that the second
operand of the / operator never evaluates to zero.
Chapter 4: Tokens and operators

135

Modulus
expr1 % expr2
The % operator is the modulus operation for the NUMERIC data type.
This operator is not defined for any other data types.
The modulus operator performs remainder division as in the C
programming language. That is, the result of an expression with the
modulus operator is the remainder after dividing expr1 by expr2.
Division by zero produces a runtime error. Make sure that the second
operand of the % operator never evaluates to zero.
The following table shows the result of the % operator. Other data types
are incompatible with the modulus operation.
Result of the modulus operator
First operand

Second operand

Result

NUMERIC

NUMERIC

NUMERIC

Unary positive and negative

+ expr
expr
The unary + operator indicates a positive value for a NUMERIC, FLOAT,
or AMOUNT operand. The unary operator indicates a negative value for
a NUMERIC, FLOAT, or AMOUNT operand. All unsigned values are
assumed to be positive.
Neither of these operators is defined for any other data types.
The following table shows the data types that are compatible with the
unary + and operators. Unary operations on other data types are invalid.
Results of unary operations

136

Operand

Result

AMOUNT

AMOUNT

FLOAT

FLOAT

NUMERIC

NUMERIC
Unify VISION: 4GL Reference

Relational operators

VISION 4GL provides six binary relational operators:

equal

<>

not equal

>

greater than

>=

greater than or equal to

<

less than

<=

less than or equal to

VISION 4GL provides two operators for comparing operands with a string

mask:
LIKE

string pattern-matching or pattern-exclusion operator

SHLIKE

string pattern-matching or pattern-exclusion operator

Relational operators return values based on three-value logic. A relational

operation can yield three possible results:
TRUE
FALSE
NULL

When three-value logic (TRUE, FALSE, and NULL) is mapped to

two-value logic (TRUE and FALSE), a NULL value is mapped to FALSE.
If any of the relational operators operands contains a null value, the
result of the relational operation is NULL.
The following table summarizes how the NULL and UNDEFINED values
work with the relational operators.
Chapter 4: Tokens and operators

137

Results of relational operations

First operand

Second operand

Result

Non-null value

Non-null value
Null value
Undefined value

TRUE | FALSE
NULL

Non-null value
Null value
Undefined value

NULL
NULL

Non-null value
Null value
Undefined value

Invalid
Invalid
Invalid

Null value

Undefined value

Invalid

Invalid

If any operand is UNDEFINED, a runtime error occurs.

Using the NULL constant as an operand of a relational expression causes
a compilation error. Use the operators IS NULL and IS NOT NULL to test
for equality and inequality of null values.
g Tip

To convert a null value to a non-null value, use the system function

null_convert$( ).

Equality and inequality

expr1 = expr2
expr1 <> expr2
The = operator is the relational equality operation. The <> operator
(< followed by >, with no space between) is the inequality operation. The
character pair != is recognized as equivalent to <>.
For STRING and TEXT values, the equality and inequality operators
compare operands character by character in ASCII sequence. All
characters within the search string are treated as literal characters. To
compare complex patterns that include metacharacters, use the LIKE or
SHLIKE pattern-matching operators.
The following table shows the data types that are compatible with the =
and <> relational operators. Operations on other combinations of data
types are invalid.
138

Unify VISION: 4GL Reference

Compatible data types for = and <> operators

First operand

Second operand

Result

AMOUNT

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

BINARY

BINARY

BOOLEAN

BOOLEAN

BOOLEAN

BOOLEAN

DATE

DATE
DATETIME

BOOLEAN
BOOLEAN 1

DATETIME

DATE
DATETIME
TIME

BOOLEAN 1
BOOLEAN
BOOLEAN 2

FLOAT

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

NUMERIC

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

OBJECT_REF

OBJECT_REF

BOOLEAN

STRING

STRING
TEXT

BOOLEAN

TEXT

STRING
TEXT

BOOLEAN

TIME

DATETIME
TIME

BOOLEAN 2
BOOLEAN

1 An implicit to_datetime$( ) is done on the date yielding a datetime

with 00:00:00.000 for the time portion.
2 An implicit to_datetime$( ) is done on the time yielding a datetime
with an undefined date. If both expressions have undefined dates, then
the time portions are compared. If only one of the dates is undefined,
they are considered not equal.
g Tip

Chapter 4: Tokens and operators

To test whether a variable contains an UNDEFINED value, use the IS

UNDEFINED and IS NOT UNDEFINED operators.
139

Comparisons
expr1 > expr2
expr1 >= expr2
expr1 < expr2
expr1 <= expr2
The < operator is the relational less than operation. The > operator is
the relational greater than operation.
The >= operator is the relational greater than or equal to operator. The
<= operator is the relational less than or equal to operation. Both of
these operators are made up of two characters: either a greater than (>)
sign or a less than sign (<) followed by the equal sign (=). The two
characters must not be separated by spaces or tabs.
The following table shows the data types that are compatible with the
inequality relational operators. Operations on other combinations of data
types are invalid and cause runtime errors.

140

Unify VISION: 4GL Reference

Compatible data types for <, >, <= and >= operators
First operand

Second operand

Result

AMOUNT

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

BINARY

BINARY

BOOLEAN

DATE

DATE
DATETIME

BOOLEAN
BOOLEAN 1

DATETIME

DATE
DATETIME
TIME

BOOLEAN 1
BOOLEAN
BOOLEAN 2

FLOAT

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

NUMERIC

AMOUNT
FLOAT
NUMERIC

BOOLEAN
BOOLEAN
BOOLEAN

STRING

STRING
TEXT

BOOLEAN

TEXT

STRING
TEXT

BOOLEAN

TIME

DATETIME
TIME

BOOLEAN 2
BOOLEAN

1 An implicit to_datetime$( ) is done on the date yielding a datetime

with 00:00:00.000 for the time portion.
2 An implicit to_datetime$( ) is done on the time yielding a datetime
with an undefined date. If both expressions have undefined dates, then
the time portions are compared. If one and only one of the dates is
undefined, the use of <, <=, >, or >= results in a runtime error.

STRING and TEXT values are compared character by character until two
characters differ or until the end of one or both string or text variables is
reached.
Chapter 4: Tokens and operators

141

When two characters differ, the string or text containing the character
with the smaller ASCII code value is less than the other. Comparisons
use ASCII code values:
Letters have alphabetic ordering.
Uppercase letters (A, B, . . .) are less than" lowercase letters
(a, b, . . .).
Numeric characters (1, 2, . . .) are less than" all alphabetic
characters.
Symbol characters (#, $, . . .) have the ordering indicated by
their ASCII values.
If initial characters match, a string shorter than a second string is less
than the second string. Therefore, a string that is identical to only the
first part of a second string will also be less than the second string.
The same rules are true for TEXT values also.

Pattern matching
The pattern-matching operators use metacharacters to select portions of
data. VISION 4GL provides two pattern-matching operators:
LIKE
SHLIKE

The LIKE operator

The LIKE operator enables you to search for character string values by
using the following pattern-matching metacharacters:
_

(underline) Matches any single character.

For example, if you need to find the name Gray but
dont know whether it is spelled Grey or Gray, you
can use the specification Gr_y. However, the
specification cat_ _ matches catch but not cats or
catalog.
The number of characters must match exactly.

142

Matches any string of characters of any length, including

zero-length strings. Null strings are not matched.
Unify VISION: 4GL Reference

A LIKE expression has the following syntax:

variable [NOT] LIKE mask
variable

Is the name of the variable to be compared.

mask

Is the string that contains the pattern that must be

matched. The mask string is case sensitive.

You can exclude strings that match the mask by using the NOT keyword.
The LIKE operator can be used in all VISION 4GL expressions. In
addition, this operator can be used in SQL DML statements that conform
to the ANSI standard.
Related information

Example

For information about how to use the LIKE operator in SQL statements,
see the documentation for your DBMS.
These statements determine whether the data in the phone_number field
begins with the digits 415; if the condition is true, the string CA is
displayed in the state field.
IF phone_number LIKE '415%' THEN
SET state TO 'CA'

The SHLIKE operator

The SHLIKE operator enables you to search for character string values
by using the following pattern-matching metacharacters:
?

Matches any single character.

For example, if you need to find the name Gray but
dont know whether it is spelled Grey or Gray, you
can use the specification Gr?y.
The number of characters must match exactly.
For example, the specification cat?? matches strings of
exactly five characters beginning with cat, such as catch;
however, strings of less than or more than five
characters, such as cats or catalog, are not matched.

Chapter 4: Tokens and operators

143

Matches any string of characters of any length, including

zero-length strings. Null strings are not matched.

[az]

A character class, where a and z are any character. The

character class matches any single character that is a
member of the class. You can specify a range of
characters by separating two characters with a dash ().
For example, you can specify the range of all uppercase
letters by the class [AZ] or
[ABCDEFGHIJKLMNOPQRSTUVWXYZ]. You can
specify the range of all upper and lower case letters by
[azAZ]. You can construct other classes similarly.

A SHLIKE expression has the following syntax:

variable [NOT] SHLIKE mask
variable

Is the name of the variable to be compared.

mask

Is the string that contains the pattern that must be

matched. The mask string is case sensitive.

You can exclude strings that match the mask by using the NOT keyword.
The SHLIKE operator can be used only with VISION 4GL statements. It is
not a standard database operator for use in SQL statements.
By default, VISION Runtime Manager calls the operating system
regular-expression evaluation routines to evaluate the SHLIKE
expression. To use the Unify routines, set the UNIFY_REGCMP external
preference to TRUE.
The Unify regular-expression evaluation routines recognize backward
ranges, such as [ZA], while most operating system routines do not. For
the Unify routines, you must precede special characters by double
backslashes, for example, \\{ and \\}.
Example

These statements determine whether the data in the phone_number field

begins with the digits 415; if the condition is true, the string CA is
displayed in the state field.
IF phone_number SHLIKE '415*' THEN
SET state TO 'CA'

144

Unify VISION: 4GL Reference

Logical operators

VISION 4GL provides two binary logical operators:

AND

logical AND

OR

logical OR

In addition to the binary logical operators, VISION 4GL provides a unary

logical operator:
logical negation

NOT

The logical operators are defined for BOOLEAN or NUMERIC operands.

Non-zero NUMERIC operands are coerced to TRUE. A zero NUMERIC
operand is coerced to a FALSE BOOLEAN value.
Logical operators return values based on three-value logic. A logical
operation can yield three possible results:
TRUE
FALSE
NULL

When three-value logic (TRUE, FALSE, and NULL) is mapped to

two-value logic (TRUE and FALSE), a NULL value is mapped to FALSE.
Using the NULL constant as an operand of a logical operator causes a
compilation error. Use the operators IS NULL and IS NOT NULL to test
for equality and inequality of null values.
A non-BOOLEAN, non-NUMERIC operand causes a runtime error, as
does an UNDEFINED operand.

Chapter 4: Tokens and operators

145

Logical OR and logical AND

expr1 AND expr2
expr1 OR expr2
The AND operator is the logical AND operation. The OR operator is the
logical inclusive OR operation. Both operators are defined for BOOLEAN
operands only and yield a BOOLEAN result.
If either of the AND or OR operands contains a null value, the result is
NULL. If either of the AND or OR operands is UNDEFINED, a runtime
error occurs.
The following chart shows the truth table for the AND and OR logical
operators.
Truth table for logical AND and OR
Operand values

146

Result

A AND B

A OR B

TRUE

TRUE

TRUE

TRUE

TRUE

FALSE

FALSE

TRUE

TRUE

NULL

NULL

TRUE

TRUE

UNDEFINED

Invalid

TRUE

FALSE

TRUE

FALSE

TRUE

FALSE

FALSE

FALSE

FALSE

FALSE

NULL

FALSE

NULL

FALSE

UNDEFINED

FALSE

Invalid

NULL

TRUE

NULL

TRUE

NULL

FALSE

FALSE

NULL

NULL

NULL

NULL

NULL

NULL

UNDEFINED

Invalid

Invalid

UNDEFINED

TRUE

Invalid

Invalid

UNDEFINED

FALSE

Invalid

Invalid

UNDEFINED

NULL

Invalid

Invalid

UNDEFINED

UNDEFINED

Invalid

Invalid

Unify VISION: 4GL Reference

For the AND and OR operands, expressions are evaluated from left to
right until a result can be determined for the entire expression. For logical
operators, Unify VISION can sometimes determine the logical result
without completely evaluating both operand expressions.
If the first operand of the AND operator is FALSE, Unify VISION knows
that the entire expression will evaluate to FALSE. Similarly, if the first
operand of the OR operator is TRUE, Unify VISION knows that the entire
expression will evaluate to TRUE. Therefore, in both these cases, Unify
VISION does not evaluate the second operand.
Example

In the following example, if a is not 5, then the first operand evaluates to

FALSE and Unify VISION does not evaluate the second operand. The

function call to func and the assignment to b are not performed.

IF (a = 5) AND (SET b TO func(d,e,f)) THEN

In the next example, if TOTAL is undefined or is null, TOTAL is set to 0.

IF ($TOTAL is undefined) OR ($TOTAL is null) THEN
SET $TOTAL to 0

In the next example, the NUMERIC logical expression is coerced to a

BOOLEAN TRUE, which causes the statement_body to be executed:
IF (1234) THEN
statement_body

Logical NOT
NOT expr

The NOT operator is the logical negation operation. This operator is

defined for a BOOLEAN operand only and yields a BOOLEAN result.
The following chart shows the truth table for the NOT logical operator.
Truth table for logical NOT

Chapter 4: Tokens and operators

Operand value
A

Result
NOT A

TRUE

FALSE

FALSE

TRUE
147

NOT A

NULL

NULL

UNDEFINED

Invalid

If the NOT operand contains a null value, the result is NULL. If the NOT
operand is UNDEFINED, a runtime error occurs.

148

Unify VISION: 4GL Reference

Bitwise operators

VISION 4GL provides three binary bitwise operators:

&

bitwise AND

bitwise inclusive OR

bitwise exclusive OR

In addition to the binary bitwise operators, VISION 4GL has a unary

bitwise operator: bitwise negation ( ~ ).
Bitwise operators are defined for NUMERIC operands only and always
produce a NUMERIC result.
Bitwise operations are performed on a bit-by-bit basis. The first (far
right) bits of both operands are evaluated and then the second pair of bits
are evaluated and so on for successive pairs of bits.
The following chart summarizes how the null and UNDEFINED values
work with the bitwise operators.

Bitwise operators and null values

Chapter 4: Tokens and operators

First operand

Second operand

Result

Non-null value

Non-null value
Null value
Undefined value

Non-null value
Null value
Invalid

Null value

Non-null value
Null value
Undefined value

Null value
Null value
Invalid

Undefined value

Non-null value
Null value
Undefined value

Invalid
Invalid
Invalid
149

If a bitwise operator has any operands containing UNDEFINED, a

runtime error occurs.
Using the NULL constant as an operand of a bitwise operand causes a
compilation error. Use the null operators IS NULL and IS NOT NULL to
test for equality and inequality of null values.

Bitwise OR and bitwise AND

expr1 & expr2
expr1 | expr2
expr1 ^ expr2
The & operator is the bitwise AND operation. There are two bitwise OR
operators:
|

bitwise inclusive OR

bitwise exclusive OR

The bitwise AND and OR operators are defined for NUMERIC operands
only and yield a NUMERIC result.
The following chart shows the truth table for the bitwise AND and OR
operators (&, |, ^). The three rightmost columns show the effects of these
operators on a single bit in A and a single bit in B for all possible
combinations of bits.

Truth table for &, |, or ^

Value

Result

A&B

A|B

A^B

If any of the &, |, or ^ operands is UNDEFINED, a runtime error occurs.

150

Unify VISION: 4GL Reference

Bitwise negation
~ expr
The ~ operator is the unary bitwise negation or ones complement. This
operator is defined for NUMERIC operands only and yields a NUMERIC
result.
The following chart shows the truth table for the ~ operator. The second
column shows the effect of this operator on a single bit in A.

Truth table for ~

A

~A

If the ~ operand is UNDEFINED, a runtime error occurs.

Chapter 4: Tokens and operators

151

Null value operators

expr IS NULL
expr IS NOT NULL
The IS NULL and IS NOT NULL operators test whether a variable
contains a null value. A null value is a valid variable value indicating
empty or no value.
Both operators require only one operand. These operators yield a TRUE
or FALSE value depending upon whether the operand contains a null
value.

Truth table for IS NULL and IS NOT NULL

Operand

IS NULL

IS NOT NULL

Non-null value

FALSE

TRUE

Null value

TRUE

FALSE

Undefined

Invalid

Invalid

Undefined variables or values are illegal operands for null operators. A

null operand containing an UNDEFINED value causes a runtime error.
The null value operators are useful in conditional statements such as IF,
WHILE, and REPEAT and in the WHERE clause of DML statements.
You can use the null value operators in the logical expression of these
statements.

152

Unify VISION: 4GL Reference

Undefined value operators

expr IS UNDEFINED
expr IS NOT UNDEFINED
The IS UNDEFINED and IS NOT UNDEFINED operators test whether a
variable contains an UNDEFINED value. An undefined value indicates
that the variable is un-initialized: it has no valid value associated with it.
Both operators require only one operand. These operators yield a TRUE
or FALSE value depending upon whether the operand is an UNDEFINED
value. With the undefined value operators, the operand must precede the
IS UNDEFINED or IS NOT UNDEFINED operator.
The following table shows the results of the undefined operators IS
UNDEFINED and IS NOT UNDEFINED.

Truth table for IS UNDEFINED and IS NOT UNDEFINED

First operand

IS UNDEFINED

IS NOT UNDEFINED

Not undefined

FALSE

TRUE

Undefined

TRUE

FALSE

The undefined value operators are useful in conditional statements such

as IF and REPEAT. You can use the undefined value operators in the
logical expression of these statements.

Chapter 4: Tokens and operators

153

154

Unify VISION: 4GL Reference

Part II
VISION 4GL language

155

156

Unify VISION: 4GL Reference

5
Script statements
This chapter provides complete descriptions of all VISION 4GL script statements. The
descriptions appear in alphabetical order. Each description includes several parts:

Syntax

Presents the syntax for the statement. BOLDFACE words are

keywords. Shaded areas indicate features that are restricted to a
particular user interface or DBMS. Italicized words within the syntax
are described under Arguments.

Support

Describes DBMS or user interface restrictions or dependencies, if any.

Arguments

Describes the italicized arguments shown in the syntax.

Description

Describes usage, conditions, and notes.

Restrictions Lists restrictions on usage, if any.

Example

Gives a sample that shows how the statement might be used.

See also

Lists related statements described in this manual.

Related information
Lists chapters or topics in other manuals that are related to the
statement.

157

ALTER SCHEMA
SQL DDL statement

Syntax

Unify DataServer only

[ USING [ CONNECTION ] connection ]

ALTER SCHEMA alter_schema_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

The ALTER SCHEMA statement is not supported for INFORMIX.

ORACLE

The ALTER SCHEMA statement is not supported for ORACLE.

SYBASE SQL

The ALTER SCHEMA statement is not supported for

SYBASE SQL Server.

Server

Unify DataServer

Supported.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
alter_schema_clause
Any of the DDL keywords or statements allowed by the DBMS within
an ALTER SCHEMA command. If more than one statement is listed,
the statement list must be enclosed by a pair of parentheses.
158

Unify VISION: 4GL Reference

Description

When VISION Runtime Manager encounters an ALTER SCHEMA statement, it

prepares the statement for processing by the database. Because this statement is
executed by the DBMS, it must conform to the syntax requirements of the DBMS;
extensions provided by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

Related
For complete syntax information, see the documentation provided by the DBMS
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

159

ALTER TABLE
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

ALTER TABLE SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the arguments permitted by the DBMS in an ALTER TABLE

statement.

When VISION Runtime Manager encounters an ALTER TABLE statement, it prepares

the statement for processing by the database. Because this statement is executed by the
DBMS, it must conform to the syntax requirements of the DBMS; extensions provided
by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

160

Unify VISION: 4GL Reference

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions The ALTER TABLE statement can be used in all VISION 4GL methods.

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

161

BEGIN_SQL
Script statement: SQL statement block

Syntax

[ USING [ CONNECTION ] connection ]

BEGIN_SQL

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.

Description

The BEGIN_SQL statement marks the start of an SQL statement block. This statement
is required for executing nonstandard database statements, such as vendor-specific
extensions.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
This statement is not required for DML and DDL statements shown in this manual.
The SQL statement block must be terminated by the END_SQL statement.
The database statements listed between the begin and end delimiters are sent directly
to the database for processing. Unify VISION variables can be used within the
statement block, but the database cannot return values to the Unify VISION
application. The BEGIN_SQL and END_SQL statements themselves are not passed to
the database.

162

Unify VISION: 4GL Reference

INFORMIX
If you are using Unify VISION with INFORMIX in standard mode, use the tx_mode$( )
system function and the COMMIT WORK statement to terminate the current
transaction before execution of the SQL statement block. With MODE ANSI,
INFORMIX always automatically starts a transaction for the user; the tx_mode$( )
system function has no effect.

SYBASE SQL Server

Use the tx_mode$( ) system function and the COMMIT WORK statement to terminate
the current transaction before execution of the SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This example shows how the BEGIN_SQL and END_SQL statements are used to
enclose SYBASE SQL Server statements.
create table NEXTNUM
(
NXT_FIELD_NAME char(15),
NXT_NUMBER
int
);
COMMIT WORK
BEGIN_SQL
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (CO_KEY,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (ORD_NUMBER,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (EMP_KEY,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (CT_KEY,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (LD_KEY,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (ALT_KEY,$inival)
insert into NEXTNUM (NXT_FIELD_NAME,
VALUES (NV_NUMBER,$inival)
END_SQL

Chapter 5: Script statements

NXT_NUMBER)
NXT_NUMBER)
NXT_NUMBER)
NXT_NUMBER)
NXT_NUMBER)
NXT_NUMBER)
NXT_NUMBER)

163

In this example, the current transaction is terminated before execution of the SQL
statement block.
tx_mode$(FALSE)
COMMIT WORK
BEGIN_SQL
CREATE VIEW view1 AS
SELECT column1, column2 from table1
END_SQL
tx_mode$(TRUE)
BEGIN WORK

See also

Script language
END_SQL (page 250)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.

164

Unify VISION: 4GL Reference

BEGIN WORK
Script statement: transaction initiation

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

BEGIN WORK

Support

Support for this feature is DBMS dependent.

ODBC

The BEGIN WORK statement has no effect.

ORACLE

Supported.

SYBASE SQL

Supported as described under Description.

Server
Unify DataServer

Supported.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.

Description

The BEGIN WORK statement starts a transaction. If a transaction already exists or if

automatic transaction handling is enabled, this statement has no effect.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

165

INFORMIX
By default, the ACLTXMODE preference is set to TRUE and Unify VISION
automatically begins and commits transactions. However, if ACLTXMODE is set to
FALSE, automatic transaction handling is disabled.
When automatic transaction handling is disabled, the CHOOSE FORM USING, ON
CHOOSE NEXT FORM, and CREATE FORM transaction level specifications have no
effect. Therefore, you must explicitly begin and commit transactions by using the
BEGIN WORK and COMMIT WORK statements.
You can use the tx_mode$( ) system function to dynamically enable or disable
automatic transaction handling, regardless of the setting of ACLTXMODE.
SYBASE SQL Server
By default, the ACLTXMODE preference is set to TRUE and Unify VISION
automatically begins and commits transactions. However, if ACLTXMODE is set to
FALSE, automatic transaction handling is disabled.
When automatic transaction handling is disabled, the CHOOSE FORM USING, ON
CHOOSE NEXT FORM, and CREATE FORM transaction level specifications have no
effect. Therefore, you must explicitly begin and commit transactions by using the
BEGIN WORK and COMMIT WORK statements.
You can use the tx_mode$( ) system function to dynamically enable or disable
automatic transaction handling, regardless of the setting of ACLTXMODE.

Restrictions This statement can be used in all VISION 4GL methods.

Example

In this example, a new transaction is started and an update operation is processed. If

the update operation is successful, the transaction is committed; otherwise, if the
operation is not successful, the transaction is reversed.
BEGIN WORK
UPDATE emp SET salary = salary * 1.1;
IF (status$()=SS_NORM) THEN
COMMIT WORK
ELSE
ROLLBACK WORK

166

Unify VISION: 4GL Reference

See also

Script language
CHOOSE FORM USING (page 174)
COMMIT WORK (page 184)
CREATE FORM (page 191)
ROLLBACK WORK (page 348)

System functions
tx_mode$( ) (page 594)
Methods
ON CHOOSE NEXT FORM

For information about transaction control, see Managing transactions and locks in
Related
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.
For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
ACLTXMODE

Chapter 5: Script statements

167

BREAK
Script statement: control break

Syntax

BREAK

Description

The BREAK statement immediately terminates the execution of a loop or method.

This statement can be placed anywhere within a script.
When executed within a FOR, REPEAT, SET/SELECT EXECUTING, or WHILE
statement, the loop is immediately terminated and execution skips to the statement
following the loop. The BREAK statement terminates the current loop only.
When executed within other statement blocks, the BREAK statement terminates the
current method.
When executed within a function, but outside a loop, the BREAK statement causes
VISION Runtime Manager to evaluate all result parameters and exit from the function.
The return value of the function, if any, is UNDEFINED.
When executed within a SWITCH statement, the BREAK statement terminates the
current case clause.

Restrictions This statement can be used in all VISION 4GL methods.

Example

168

The following example accepts a customer name in a form field and retrieves a
corresponding account number. The customers variable is a MATRIX array with two
rows and one column for each customer. The first row contains customer names; the
second row contains the corresponding account numbers. The customer_count
variable initializes the array to the number of columns. When the WHEN FIELD
CHANGES method is executed, the resulting account number is assigned to
Unify VISION: 4GL Reference

customer_account. However, if the value of customer_account does not match any

customer name, a brief message is displayed.
FIELD customer_name
METHOD WHEN FIELD CHANGES
SET customer_account TO UNDEFINED
SET index TO 1
WHILE index <= customers:COLUMN_UPPER_BOUNDS
BEGIN
IF customer_name = customers[1,index]
THEN
BEGIN
SET customer_account TO accounts[2,index]
BREAK
END
SET index TO index + 1
END;
IF customer_account IS UNDEFINED
THEN DISPLAY Unknown customer FOR FYI_MESSAGE

See also

Script language
CONTINUE (page 187)
EXECUTING (page 259)
FOR (page 267)

Chapter 5: Script statements

REPEAT (page 337)

SET (page 359)
WHILE (page 393)

169

BREAKPOINT
Script statement: display debugger window

Syntax

BREAKPOINT

Description

When an application is running with VISION Debugger turned on, the Debugger
window is displayed when control reaches the BREAKPOINT statement.
The BREAKPOINT statement sets a permanent breakpoint in the application. Setting a
breakpoint can help you to debug the application while it is in the development stage.
The BREAKPOINT statement can be detected only by VISION Debugger. If the same
application is executed with the Debugger turned off, the statement has no effect on
application execution.

Restrictions The BREAKPOINT statement can be used in all VISION 4GL methods.

Example

In this example, when execution reaches the BREAKPOINT statement (when the user
tries to add a record), the debugger window is displayed automatically if the
application is executed in debug mode.
METHOD BEFORE ADD
SET fcompany:co_address_1:UPDATEABLE to FALSE
SET fcompany:co_key TO SELECT nxt_number FROM nextnum
WHERE nxt_field_name = co_key
UPDATE nextnum SET nxt_number TO fcompany:co_key + 1
WHERE nxt_field_name = co_key
BREAKPOINT
SET $fcompany:redo_contact TO TRUE

For information about how to use VISION Debugger, see Defining a class in VISION
Related
information Class Browser in Unify VISION: Developing an Application.

170

Unify VISION: 4GL Reference

CANCEL FORM
Script statement: cancel form operation

Syntax

CANCEL FORM object_ref

Arguments

object_ref

Description

The CANCEL FORM statement closes the form specified by object_ref.

An expression that specifies the object reference of the form to be

cancelled.

If the CANCEL FORM statement is executed on the current form, execution of the
current method is terminated. However, if object_ref is not the current form, execution
of the current method is continued.
The CANCEL FORM statement does not cause execution of the ON CANCEL FORM
method.

Restrictions The CANCEL FORM statement is invalid in the following methods:

FUNCTION
ON CLEAR TO ADD
ON CLEAR TO FIND
ON DRAG ENTER
ON DRAG LEAVE

See also

ON DRAG START
ON EXIT
ON FIND
WHEN FIELD CHANGES

Script language
NEXT ACTION IS CANCEL FORM (page 295)

Related
For information about the following predefined command, see Predefined
information commands in Unify VISION: Application Reference:
uv_cancel_form
Chapter 5: Script statements

171

See Unify VISION: Class Reference for information about related methods and
operations:
Methods
ON CANCEL FORM

Runtime operations
Cancel form

172

Unify VISION: 4GL Reference

CHANGE CURRENT RECORD TO

Script statement: change record display

Syntax

CHANGE CURRENT RECORD TO numeric_expression

Arguments

numeric_expression
A defined, non-null expression for the nth record in the selected set,
where the first record has a value of 1. If the number specified is
greater than the number of records in the selected set, an error occurs.

Description

The CHANGE CURRENT RECORD statement changes the current record to the
record in the selected set specified by the numeric expression. The ON PREVIOUS
RECORD, ON NEXT RECORD, and other methods are not executed.

Restrictions The CHANGE CURRENT RECORD statement is invalid in the following VISION 4GL
methods:
FUNCTION
ON FIND
WHEN FIELD CHANGES

Example

In this example, the records in the selected set are each sent to the pipeline identified
by $pipe_one.
CREATE PIPELINE $pipe_one RPT script ,lpr
FOR (SET $idx TO 1; $idx <= current_record_count$(); SET $idx TO $idx + 1)
BEGIN
CHANGE CURRENT RECORD TO $idx;
WRITE PIPELINE $pipe_one
$co_name, $co_key, $co_state, $co_city
END
CLOSE PIPELINE $pipe_one

See also

System functions
current_record_count$( ) (page 429)

Chapter 5: Script statements

173

CHOOSE FORM USING

Script statement: form sequence control

Syntax

CHOOSE FORM USING

{
[ NEW ] CHILD FORM [ form_name ]
OF CLASS class_name
[ USING [ CONNECTION ] connection ]
[ OCCURRENCES numeric ]
[ CONSISTENCY IS consistency ]
[ TRANSACTION IS transaction ]
[ POSITION x, y ]
[RETURN KEY
| RETURN VALUES [ INTO var1[, var2, . . . , varn ] ] ]

ACTIVE FORM object_ref } [ , . . . ]

[ WITH EXIT ]
[ OBJECT_REF INTO variable ]

Arguments

form_name

The instance name of the child form. This name can either be the
literal form name or a string expression. You can use the same name
as the class_name or a different name. Use a different name than the
class_name when you want to display the same form multiple times at
runtime.

class_name

The name of a form class as defined in VISION Development

Environment. This name can either be the literal form class name or a
string expression.

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

174

Unify VISION: 4GL Reference

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
numeric

A numeric expression that specifies the number of occurrences for

repeating fields on the form.

consistency

One of the following keywords:

transaction

Description

RECORD

Specifies record consistency for the form.

SET

Specifies set consistency for the form.

NONE

Specifies no consistency for the form.

One of the following keywords:

CONTINUE

Specifies that the current transaction is to be

continued.

COMMIT

Specifies that the current transaction is to be

committed and a new transaction is to be started.

Specifies the pixel value at which to position the form horizontally.

Specifies the pixel value at which to position the form vertically.

object_ref

An expression that specifies the object reference of the form to be

chosen.

var

The name of a form field where the value is to be inserted. References

to object attributes that do not yield a VALUE are prohibited.

variable

A variable that receives the value of the new object reference.

The CHOOSE FORM USING statement can be used to create or assign currency to one
or more child forms or to exit the application. Use this statement to display a form
after a certain event occurs in your script. If a new form is created by the choose form
operation, the RETURN clause specifies how data is to be returned from the new form
to its parent. If you specify more than one child form, a Next Form Chooser appears
with the names of the child forms.

Chapter 5: Script statements

175

When this statement is executed from a user-defined method, the form becomes
current on opening and the remaining statements in the method are not executed. If the
user-defined method that executed this statement was called by another method, the
calling methods execution is also ended, as is each method up the call chain.
The NEW keyword specifies that a new form instance is to be created.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Returning data to the form
Data is returned to the parent form when any of the following events occurs:
The user executes the uv_dismiss_form or uv_return_values commands.
The form is destroyed by the DELETE FORM statement.
The NEXT ACTION IS RETURN VALUES statement is executed.
If the user executes the uv_cancel_form command from the child form, no values are
returned.
The RETURN KEY/RETURN VALUES option returns primary key values from the
child form back to the parent form. If multiple values are returned, the parent form
must have a field for each of the values that are returned. If the RETURN option is
specified but there is no key value to return, input resumes on the parent forms
current field.
The INTO option returns values from the child form back to variables in the parent
form. The number of variables specified must match the number of fields specified in
the VALUES TO RETURN statement of the child form.
Field data types must match. The variables you are returning values from must have
the same data types as the corresponding variables into which you are assigning
values.
The POSITION clause
The POSITION clause specifies the position of the form relative to the bottom left
corner of the screen.
176

Unify VISION: 4GL Reference

The ACTIVE FORM clause

The ACTIVE FORM clause specifies that the value of the OBJECT_ID attribute of a
previous created form is to be used.
The WITH EXIT clause
The WITH EXIT clause specifies whether the Next Form Chooser dialog lists an entry
called Exit the application. At runtime, select the Exit the application entry to exit
the application.
The OBJECT_REF INTO clause
The OBJECT_REF INTO clause specifies that the object reference of the child form is
to be returned into variable.
INFORMIX

For INFORMIX SE, the SET and RECORD consistency values have no effect.

Restrictions The CHOOSE FORM USING statement is invalid in the following VISION 4GL
methods:
ON CURRENT
ON EXIT
WHEN FIELD CHANGES

Example

This example specifies that the parent forms displays a choice of two forms, along
with the exit option.
CHOOSE FORM USING
CHILD FORM inventory_form of CLASS inventory_form_class
RETURN VALUES INTO $a, $b, $c,
CHILD FORM acts_payable OF CLASS acts_payable_class
WITH EXIT
OBJECT_REF INTO $chosen_form_id

See also

Script language
CREATE FORM (page 191)
DELETE FORM (page 215)
VALUES TO RETURN ARE (page 389)

Related
For information about multiple database connections, see Getting started in Unify
information VISION: Developing an Application.
Chapter 5: Script statements

177

For information about related predefined commands, see Unify VISION: Application
Reference:
Predefined commands
uv_cancel_form
uv_dismiss_form
uv_return_values
See Unify VISION: Class Reference for information about related methods and
attributes:
Methods
ON CHOOSE NEXT FORM

Attributes
SCREEN_H
SCREEN_W
SCREEN_X
SCREEN_Y

178

Unify VISION: 4GL Reference

CLEAR COMMAND QUEUE

Script statement: remove command requests

Syntax

CLEAR COMMAND QUEUE

Description

The CLEAR COMMAND QUEUE statement causes all command requests on the
pending command queue to be removed so that they are not executed.

Restrictions This statement can be executed within any method, or from a local or global function.

See also

Script language
QUEUE COMMAND (page 323)

For related information about scripting, see COMMAND in Classes , in Unify

Related
information VISION: Class Reference.

Chapter 5: Script statements

179

CLEAR TO ADD
Script statement: clear-to-add operation

Syntax

CLEAR TO ADD

Description

The CLEAR TO ADD statement executes a clear-to-add operation; however, it does

not simulate the uv_clear_to_add command. Unlike the NEXT ACTION IS
CLEAR_TO_ADD statement, the CLEAR TO ADD statement does not stop execution
of the current method. After completing the clear-to-add operation, execution
continues in the current method. In addition, the CLEAR TO ADD statement does not
cause execution of the ON CLEAR TO ADD method.
You can use this statement to create a selected set based on data other than rows in a
target table. For example, you can use a loop, stored procedure, or 3GL function to
read data from a file to build a selected set.

Restrictions This statement is invalid in the following VISION 4GL methods:

FUNCTION
ON FIND
WHEN FIELD CHANGES

Example

In this example, a selected set is created from data provided by a stored procedure
named sp_companies( ). After all records have been added to the selected set, the
form displays the first record of the set.
CLEAR TO ADD
/* Clear the form to add a new record to the selected set */
SET $co_key, $co_name TO sp_companies()
EXECUTING
BEGIN
UPDATE CURRENT RECORD
/* Add this record to the selected set */
CLEAR TO ADD
/* Prepare to add another record to the set */
END
NEXT ACTION IS FIRST_RECORD

180

Unify VISION: 4GL Reference

See also

Script language
DELETE CURRENT RECORD (page 217)
UPDATE CURRENT RECORD (page 384)

See Unify VISION: Class Reference for information about related operations and
Related
information methods:
Runtime operations
Clear to add
Methods
AFTER ADD
AFTER UPDATE
BEFORE ADD
BEFORE UPDATE

Chapter 5: Script statements

181

CLOSE CONNECTION
Script statement: close database connection

Syntax

CLOSE CONNECTION connection_name

Arguments

connection_name
Specifies a string expression that contains the name of the database
connection instance to be closed.

Description

CLOSE CONNECTION allows a database connection instance to be dynamically

closed.
The connection instance to be closed is specified by connection_name.
Any active transaction associated with the connection instance will not be committed.
Whether any work performed on behalf of that transaction is rolled back is DBMS
dependent.

Restrictions The CLOSE CONNECTION statement can be used in all VISION 4GL methods.

See also

Script language
CREATE CONNECTION (page 189)
DEFINE CONNECTION (page 211)

182

DESTROY CONNECTION (page 224)

OPEN CONNECTION (page 298)

Unify VISION: 4GL Reference

CLOSE PIPELINE
Script statement: close specified pipeline

Syntax

CLOSE PIPELINE pipe_name

Arguments

pipe_name

Description

The CLOSE PIPELINE statement closes the pipeline identified by the pipe_name. The
Unify VISION pipeline feature enables you to pass data from your application to an
external data file or to another program.

The Unify VISION variable specified by the CREATE PIPELINE

statement.

The CLOSE PIPELINE statement flushes any remaining data from a WRITE
PIPELINE statement. To avoid loss of data, do not change the value of the pipeline
variable until after you have closed the pipeline with the CLOSE PIPELINE statement.
Pipelines must be closed before the application ends in order to avoid loss of data. The
pipeline must already exist before it can be closed. To create a pipeline, use the
CREATE PIPELINE statement.
The temporary output file is closed by the CLOSE PIPELINE statement and saved
under the file name specified when the pipeline was created.

Example

This statement closes the pipeline identified by $pipe1. Before closing the pipeline,
any remaining data is transmitted to the waiting file or UNIX process or processes.
CLOSE PIPELINE $pipe1

Restrictions This statement can be used in all VISION 4GL methods.

See also

Script language
CREATE PIPELINE (page 196)
WRITE PIPELINE (page 395)

Chapter 5: Script statements

183

COMMIT WORK
Script statement: commit database changes

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

COMMIT WORK [ RETAINING LOCKS ]

Support

Support for this feature is DBMS dependent.

INFORMIX

The RETAINING LOCKS clause has no effect for INFORMIX.

ODBC

If supported by the underlying DBMS, the COMMIT WORK

statement commits the transaction and releases locks.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

Supported.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.

Description

184

The COMMIT WORK statement terminates the current transaction and commits
database changes made by the current transaction.
Unify VISION: 4GL Reference

The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
SYBASE SQL Server
If automatic transaction handling is disabled, you must explicitly begin and end
transactions by using the BEGIN WORK and COMMIT WORK statements.

Restrictions The COMMIT WORK statement can be used in all VISION 4GL methods.

Example

In this example, automatic transaction handling is first disabled, and then the current
transaction, if any, is committed. A new transaction is then started to process and
commit an update operation.
tx_mode$(FALSE)
BEGIN WORK
UPDATE emp SET salary = salary * 1.1;
IF (status$()=SS_NORM) THEN
COMMIT WORK
ELSE
ROLLBACK WORK
/* There is no active transaction at this point. */

See also

Script language
BEGIN WORK (page 165)
ROLLBACK WORK (page 348)
SLOCK (page 369)
UNLOCK (page 378)
XLOCK (page 398)

System functions
tx_mode$( ) (page 594)

For information about transaction control, see Managing transactions and locks in
Related
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.
Chapter 5: Script statements

185

For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
ACLTXMODE

For information about related methods, see Unify VISION: Class Reference:
Methods
ON CHOOSE NEXT FORM

186

Unify VISION: 4GL Reference

CONTINUE
Script statement: begin loop iteration

Syntax

CONTINUE

Description

The CONTINUE statement immediately begins a new iteration of a loop when used
with the FOR, REPEAT, SET/SELECT EXECUTING, or WHILE statements.
When executed within a FOR, REPEAT, or WHILE loop, the control expression is
immediately evaluated or re-initialized. If the expression is true, the next iteration of
the loop is executed. If the control expression is false, the loop is terminated and
execution skips to the statement following the loop.
When executed within a SET/SELECT EXECUTING statement, the next record is
retrieved and the statement block is executed again. If there is no next record, the loop
is terminated.
The CONTINUE statement affects the current nested loop only. A CONTINUE
statement placed outside a FOR, REPEAT, SET/SELECT EXECUTING, or WHILE
statement results in an error.

Example

This example checks the hobbies table for the selected employee and determines
whether the employee plays chess. If the employees hobby is not chess, the
CONTINUE statement lets the report execution proceed.
SET $emp_id TO SELECT emp_id FROM employee
WHERE emp_name = $name
EXECUTING
BEGIN
SET hobby TO SELECT hobby FROM hobbies
WHERE emp_id = $emp_id AND hobby = chess
IF status$() <> 0 THEN
CONTINUE
WRITE PIPELINE $report $name
...
END

Chapter 5: Script statements

187

Restrictions This statement can be used in all VISION 4GL methods.

See also

188

Script language
BREAK (page 168)
EXECUTING (page 259)
FOR (page 267)
REPEAT (page 337)
SET (page 359)
WHILE (page 393)

Unify VISION: 4GL Reference

CREATE CONNECTION
Script statement: create a database connection

Syntax

CREATE CONNECTION connection_name

OF CLASS connection_class
[ { conn_attr IS conn_value [, conn_attr IS conn_value, . . . ] |
USING connection_values } ]

Arguments

connection_name
Specifies a string expression that contains the name of a new
connection instance.
connection_class
Specifies a string expression that contains the name of the class of the
new connection.
conn_attr

Specifies an identifier specifying a DCM class attribute, such as

DBTYPE, DBUSER, or DBSERVER.

conn_value

Specifies a string containing the value for the associated connection

class attribute.

connection_values
Specifies a string containing a comma-separated list of name/value
pairs in the format attr=value where attr can be any connection class
attribute, such as DBTYPE, DBSERVER, or DBUSER.

Description

The CREATE CONNECTION statement creates a new instance of database connection

class. The statement allows one or more of the connection class definition attributes to
be overridden for that particular instance.
The name of the new database connection instance is specified by connection_name.
The CREATE CONNECTION statement can optionally provide local definitions for
one or more of the database connection class attributes. This is useful for dynamically
specifying such attributes as user ID or password without having to define a complete
new connection class.

Chapter 5: Script statements

189

The name of the connection instance must not be identical to the name of a previously
existing connection name or connection class.
To open the database connection instance, use the OPEN CONNECTION statement.
Database connections can subsequently be closed with a CLOSE CONNECTION
statement. To destroy a database connection instance, use the DESTROY
CONNECTION statement.

Restrictions The CREATE CONNECTION statement is valid in all VISION 4GL methods.

Example

This example creates a new connection instance named s_connection. The USING
clause specifies connection attributes.
CREATE CONNECTION $s_connection OF CLASS salesconn
USING (DBUSER=+$uname + , + DBPASSWORD=+$passwd);

See also

Script language
DEFINE CONNECTION (page 211)
CLOSE CONNECTION (page 182)

DESTROY CONNECTION (page 224)

OPEN CONNECTION (page 298)

For information about .dcm file format, see Unify VISION: Application Reference.
Related
information

190

Unify VISION: 4GL Reference

CREATE FORM
Script statement: create a form instance

Syntax

CREATE FORM [ form_instance ]

OF CLASS form_class
[ USING [ CONNECTION ] connection ]
[ OCCURRENCES numeric ]
[ CONSISTENCY IS consistency ]
[ TRANSACTION IS transaction ]
[ RETURN KEY
| RETURN VALUES [ INTO var1[, var2, . . . , varn ] ] ]
[ POSITION x, y ]
[ OBJECT_REF INTO variable ]

Arguments

form_instance A string expression that specifies the instance name of the form to be
created. If not specified, a form instance name is assigned. An
unquoted identifier is interpreted as a literal string. To specify a
variable value, use the $ token, for example, $form_idx.
connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
form_class

The name of a form class as defined in VISION Development

Environment or VISION Designer. Specifying a form class that is not
included in the class library list for the application causes the
application to fail.

numeric

A numeric expression that specifies the number of occurrences for

repeating fields on the form.

Chapter 5: Script statements

191

consistency

transaction

Description

One of the following keywords:

RECORD

Specifies record consistency for the form.

SET

Specifies set consistency for the form.

NONE

Specifies no consistency for the form.

One of the following keywords:

CONTINUE

Specifies that the current transaction is to be

continued.

COMMIT

Specifies that the current transaction is to be

committed and a new transaction is to be started.

var

The name of a form field where the value is to be inserted. References

to object attributes that do not yield a VALUE are prohibited.

Specifies the pixel value at which to position the form horizontally.

Specifies the pixel value at which to position the form vertically.

variable

A variable that receives the value of the new object reference.

The CREATE FORM statement creates a new instance of a form class. The current
form becomes the parent form of the new form. Use the CREATE FORM statement to
display an instance of a form class with runtime values for attributes. For example, if
you designed a form with the BACKGROUND attribute set to the RGB value of blue
and the TX_MODE_ADD_RECORD attribute set to continue, you can change these
values at runtime by creating a new instance of the form class, setting those attributes
to red and commit, then making the form class current.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Returning data to the form
If a RETURN clause is specified, data is returned to the parent form when any of the
following events occurs:
The user executes the uv_dismiss_form or uv_return_values commands from
the child form.

192

Unify VISION: 4GL Reference

The child form is destroyed by the DISMISS FORM statement.

The NEXT ACTION IS DISMISS_FORM statement or NEXT ACTION IS
RETURN_VALUES statement is executed on the child form.
If the user executes uv_cancel_form from the child form, no key value is returned.
The RETURN option returns values from the child form back to the parent form. If
multiple values are returned, the parent form must have a field for each of the values
that are returned. If RETURN is specified but there is no key value to return, input
resumes on the parent forms current field.
The INTO option returns values from the child form back to variables in the parent
form. The number of variables specified must match the number of fields specified in
the VALUES TO RETURN ARE statement of the child form.
Field data types must match. The variables you are returning values from must have
the same data types as the corresponding variables into which you are assigning
values. If data types do not match, a runtime error occurs.
The POSITION clause
The POSITION clause specifies the position of the form relative to the bottom left
corner of the screen.
If the external preference CASCADE is FALSE, the SCREEN_X and SCREEN_Y
attribute settings are used to position the form when it is initially opened. The
POSITION clause can be used to override the SCREEN_X and SCREEN_Y attributes
as specified on the visual panel of VISION Designer.
The OBJECT_REF INTO clause
The OBJECT_REF INTO clause specifies that the object reference of the new child
form is to be returned into variable.
INFORMIX

For INFORMIX SE, the SET and RECORD consistency values have no effect.

Restrictions This statement is invalid in functions and in the following VISION 4GL methods:
ON CLEAR TO ADD
ON CLEAR TO FIND
ON CURRENT
ON DRAG ENTER
ON DRAG LEAVE

Chapter 5: Script statements

ON DRAG START
ON EXIT
ON FIND
WHEN FIELD CHANGES

193

Example

When the user clicks on a button on the form associated with the developer-defined
command display_fcompany, this example creates a new fc1 form, sets the values of
specific form attributes, and then makes the form visible and current.
COMMAND display_fcompany
BEGIN
CREATE FORM fc1 OF CLASS fcompany
OBJECT_REF INTO $form_id
SET $form_id:TX_MODE_FORM_CREATION TO COMMIT
SET $form_id:VISIBLE TO TRUE
MAKE $form_id CURRENT
END

In the following example, the position of the inventory form is specified by dividing
the width of the screen by 4.
SET tmpx TO SCREEN_W / 4
SET tmpy TO SCREEN_H / 4
CREATE FORM OF CLASS inventory POSITION tmpx, tmpy;

See also

Script language
VALUES TO RETURN ARE (page 389)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.
For information about related methods and attributes, see Unify VISION: Class
Reference:
Methods
ON CREATE
ON NEW CHILD

Attributes
OBJECT_NAME
SCREEN_H
SCREEN_W
SCREEN_X
SCREEN_Y
VISIBLE
194

Unify VISION: 4GL Reference

For information about related predefined commands, see Predefined commands in

Unify VISION: Application Reference:
uv_cancel_form
uv_dismiss_form
uv_return_values

Chapter 5: Script statements

195

CREATE PIPELINE
Script statement: transmit data through a pipeline

Syntax

Operating system dependent

UNIX only:
CREATE PIPELINE pipe_name program_list [ OUTPUT [ IS ] string_expression ]

Windows only:
CREATE PIPELINE pipe_name OUTPUT [ IS ] string_expression

Arguments

pipe_name

A general Unify VISION variable to receive the file descriptor of the

opened pipeline.

program_list

(UNIX only) A series of formatting program names, separated by

commas. Data is piped from program to program in the order that
programs are listed in program_list. If you use literal program names
rather than variables, each program name, along with any arguments,
must be enclosed within a pair of apostrophes ().

string_expression
The directory search path and file name of the data file to receive
output from the last process in the pipeline. The expression can be
either a string constant or string variable.

Description

The CREATE PIPELINE statement creates a pipeline. A pipeline sends information

out of the application to external formatting programs. When VISION Runtime
Manager executes the statement, it creates an operating system pipeline and stores the
pipelines file descriptor in the variable pipe_name.
The pipe_name variable is set to -1 in the event of an error. If an error occurred, then
subsequent WRITE PIPELINE or CLOSE PIPELINE statements with the same
pipe_name variable will not execute correctly.
When a WRITE PIPELINE statement is executed, VISION Runtime Manager transmits
data through the pipeline to the programs in program_list. The programs in
program_list represent the operating system pipe. That is, the output of the application
is passed to the first program. The output of the first program becomes the input to the
second program, and so on.

196

Unify VISION: 4GL Reference

Any command line arguments needed by a program in program_list must be part of

the same string as the program name.
With the OUTPUT clause, VISION Runtime Manager can direct the data from the last
program in the pipeline to a data file. The name of this data file is identified by
string_expression. If no OUTPUT clause is specified, the data is directed to the
standard output file.
Windows
Pipes, standard input, and standard output are not supported by Windows. The
OUTPUT clause is required in the CREATE PIPELINE statement. The OUTPUT
clause specifies a temporary output file that is opened by the CREATE PIPELINE
statement and written to by the WRITE PIPELINE statement.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This example creates a pipeline called pipe_one. This pipeline sends data from the
application to the report generator RPT and then to the line printer, lpr. The RPT call
in the program_list includes two RPT arguments. RPT receives its formatting
commands from the script file and the report information from the standard input
(indicated by the minus sign).
CREATE PIPELINE $pipe_one RPT script ,lpr

See also

Script language
CLOSE PIPELINE (page 183)
WRITE PIPELINE (page 395)

Chapter 5: Script statements

197

CREATE SCHEMA
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

CREATE SCHEMA SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the arguments permitted by the DBMS in a CREATE SCHEMA

statement.

When VISION Runtime Manager encounters a CREATE SCHEMA statement, it

prepares the statement for processing by the database. Because this statement is
executed by the DBMS, it must conform to the syntax requirements of the DBMS;
extensions provided by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

198

Unify VISION: 4GL Reference

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

199

CREATE SERVICE
Script statement: create a new service object class

Syntax

CREATE [REPLICATED] SERVICE OF [{ ACTIVEX| MESSAGE_QUEUE }]

CLASS class_name
[ IN PARTITION partition_objref ]
[ REGISTER AS service_name IN (sname_objref, . . . ) ]
[ REPLICATE IN replication_group
[ REGISTER AS rgroup_name IN (rname_objref, . . . ) ] ]
[ IDENTIFIED BY message_handle ]
OBJECT_REF INTO objref_var

Arguments

Arguments can be literals or variables specified as $variable_name

(for example, $class_idx). Variable values are determined at runtime.
class_name

The name of the class of the service object. For class type
MESSAGE_QUEUE, the class name must be MQSeries. The class
name, MQSeries, is case sensitive.

message_handle
If the IDENTIFIED BY clause is specified, the message_handle
variable receives the value of the message handle associated with the
request to create the service. The message handle can later be used for
checking the status of the request.
partition_objref
Specifies an object reference to the partition that the service object is
to be created in. partition_objref must reference a UVApplPartition
object.
service_name

Specifies the name to be associated with the service object.

sname_objref

Specifies an object reference to a name service in which to register the

(service_name, object_ref_var) pair.

replication_group
Specifies the name of the replication group for the service object to
join.
200

Unify VISION: 4GL Reference

Description

rgroup_name

Specifies the name used to register a newly created replication group.

rname_objref

Specifies an object reference to a name service in which to register the

replication group object reference.

objref_var

Specifies a variable that receives an object reference to the newly

created service object. objref_var must be a non-replicated object
reference.

The CREATE SERVICE statement creates a new object of class class_name.

Classes can be of type VISION, ACTIVEX, or MESSAGE_QUEUE. If the ACTIVEX
or MESSAGE_QUEUE clause is not specified, the default class type is VISION.
When the class type is VISION, a class definition identified by class_name must be on
the class library list of the partition in which the object is to be created.
When the class type is ACTIVEX, class_name must be a valid ActiveX Automation
class registered in the Windows Registry.
When the class type is MESSAGE_QUEUE, class_name must be MQSeries. An object
reference to an MQSeries object is returned.
The object reference can then be used with the CreateMQConnection() method to
obtain an object reference to an MQSeriesConnection object, or the object reference
can be used with the CreateMQOD( ), CreateMQMD( ), CreateMQGMO( ), or
CreateMQPMO( ) methods.
Use the message handle specified in the IDENTIFIED BY clause to check the status of
the request. The message handle contains attributes that are used specifically for error
processing. This is the preferred method for error processing.
When creating an ACTIVEX class of type Word.Basic, the CREATE SERVICE
statement can take longer than expected (approximately 20 seconds) to complete
execution. Once the service is created, however, performance will not be adversely
affected.
The service object can be replicated or nonreplicated. Replicated objects are created
by specifying the REPLICATE IN clause. The REPLICATE IN clause can be specified
for VISION classes only; replicated ACTIVEX classes are invalid.

Chapter 5: Script statements

201

The PARTITION clause specifies the partition in which the service object is to be
created. If a PARTITION clause is not specified, the service object is created within
the partition that is executing the CREATE SERVICE statement.
If a PARTITION clause is specified, the partition is identified by an object reference to
the partition. The partition object reference is specified by part_objref.
The REGISTER clause specifies a name to be associated with the service object within
the list of name services given. service_name specifies the name to be associated with
the service object. sname_objref specifies an object reference for a name service in
which to register the service object.
The REPLICATE IN clause specifies that the service object is to be a member of the
replication group identified by replication_group. If the replication group does not
exist, it is automatically created. The replication group name will be registered under
the rgroup_name specified by the REGISTER clause.
The OBJECT_REF clause specifies a variable to receive the object reference for the
newly created service object.
The parent object of the new object is the "_SYSTEM" form.

Restrictions If the REPLICATE IN clause is specified and the service class definition contains an
EVENT declaration as a PUBLIC attribute, every member of the replication group
must reside within the same partition group.
For service classes of type MESSAGE_QUEUE, you cannot specify the REPLICATED
keyword or the REPLICATE IN clause.

See also

Script language
DESTROY SERVICE (page 225)
SEND MESSAGE (page 354)

Example

The following example uses the CREATE SERVICE statement to create an MQSeries
service object:
BUTTON Init
METHOD ON CLICK(thebutton)
BEGIN
if (fInit = FALSE ) then
BEGIN
create service of message_queue class MQSeries
object_ref into mqs_objref;

202

Unify VISION: 4GL Reference

The newly-created MESSAGE_QUEUE service object is a factory object that creates

connection objects to message queues. The service object class name is MQSeries. It
provides an object creation method called CreateMQConnection() that creates an
object that encapsulates a connection to an MQSeries queue manager.

See Unify VISION: Class Reference for information about related classes and methods:
Related
information
bind( )
unbind( )
resolve( )
For descriptions of Unify VISION components that access MQSeries services and
functions, see Unify VISION:Interconnecting Applications with Enterprise Integrator.

Chapter 5: Script statements

203

CREATE TABLE
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

CREATE [ LOCAL ] TABLE SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the arguments permitted by the DBMS in a CREATE TABLE

statement.

When VISION Runtime Manager encounters a CREATE TABLE or CREATE LOCAL

TABLE statement, it prepares the statement for processing by the database. Because
this statement is executed by the DBMS, it must conform to the syntax requirements of
the DBMS; extensions provided by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

204

Unify VISION: 4GL Reference

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
When using Unify VISION parameters, do not enclose this statement within a
BEGIN_SQL and END_SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

205

CREATE TIMER EVENT

Script statement: install timer function

DBMS dependent

Syntax

CREATE TIMER EVENT variable IN float_expr SEC[OND[S]]

USING TIMER HANDLER function_name ;

Arguments

variable

The name of a variable where the event ID is to be stored.

float_expr

Expression that specifies the minimum number of seconds that must

transpire before the timer handler function is executed.

function_name The name of a global TIMER function declared by an EXTERN

statement.

Description

The CREATE TIMER EVENT statement installs a request for a timer event and
defines a timer function to be called when the timer event occurs. If the timer function
does not exist, a runtime error occurs.
When a timer event is installed, the variable is assigned an internal event ID for this
event. The event ID value must be used in later references to the timer event.
The value specified in float_expr is a number of seconds and can be a fractional value,
for example, 3.5 seconds.
Unify VISION services a timer only when the user has stopped on a field for input. If
the specified number of seconds has already expired when the user stops on a field for
input, the timer event is executed. Likewise, the timer event will be executed if the
number of seconds expires when the user is editing a field. To prevent execution of the
handler function, use the DELETE TIMER EVENT statement.
Each timer event is executed only once per installation. To execute the same timer
event function again, the timer event request must be reinstalled.
You must define a timer event handler function as a global FUNCTION, using the
following syntax:
TIMER FUNCTION function_name(event_ID)

function body
206

Unify VISION: 4GL Reference

You must declare a timer event handler function before it can be referenced in the
CREATE TIMER EVENT statement. The timer event handler function must be
declared in an EXTERN statement, using the following syntax:
EXTERN SCRIPT TIMER FUNCTION function_name(event_ID)

A timer event handler function requires one non-result parameter. You cannot use a
timer event handler function to return a value, and statements such as SET $a to
timefunc(3) are invalid.

Example

The following timer function definition displays a message to the user.

TIMER FUNCTION myfunc(id)
BEGIN
DISPLAY Please enter data.
FOR FYI_MESSAGE WAIT;
END;

The function is declared in an EXTERN statement and used in a script on the

description field. The timer event is deleted when the user exits the field:
EXTERN SCRIPT TIMER FUNCTION myfunc(id)
FIELD description
METHOD BEFORE FIELD
CREATE TIMER EVENT $tid IN 10 SECONDS USING TIMER HANDLER myfunc
...
METHOD AFTER FIELD
DELETE TIMER EVENT $tid

The following function definition installs itself and recursively displays its event ID
after 10 or more seconds:
TIMER FUNCTION timerfunc(id)
BEGIN
DISPLAY $id FOR FYI MESSAGE WAIT
CREATE TIMER EVENT $timer_id IN 10 SECONDS USING TIMER HANDLER timerfunc
END

The following statement installs a timer event so that the timer event function will be
called with the event ID returned in $a after 2.5 seconds. Meanwhile, statements
beyond the CREATE TIMER EVENT statement can be executed.
CREATE TIMER EVENT $a IN 2.5 SECONDS USING TIMER HANDLER functime

Chapter 5: Script statements

207

See also

Script language
DELETE TIMER EVENT (page 223)
EXTERN (page 263)
FUNCTION (page 271)

For information about how to create timer functions, see page 76.

208

Unify VISION: 4GL Reference

CREATE VIEW
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

CREATE VIEW SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the column names and SELECT statement permitted by the

DBMS in a CREATE VIEW statement.

The CREATE VIEW statement defines a database view. When VISION Runtime
Manager encounters this statement, it prepares the statement for processing by the
database. Because this statement is executed by the DBMS, it must conform to the
syntax requirements of the DBMS; extensions provided by the DBMS can also be
included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

209

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

210

Unify VISION: 4GL Reference

DEFINE CONNECTION
Script statement: create new database connection class

Syntax

DEFINE CONNECTION CLASS new_connection_class

[ SUBCLASS OF existing_connection_class ]
{ conn_attr IS conn_value [, conn_attr IS conn_value, . . . ] |
USING connection_values }

Arguments

new_connection_class
A string expression that contains the name of the new connection
class.
existing_connection_class
A string expression that contains the name of an existing connection
class.
conn_attr

An identifier specifying a DCM class attribute such as DBTYPE,

DBUSER, or DBSERVER.

conn_value

A string expression that contains the value for the associated

connection class attribute.

connection_values
A string expression that contains a comma-separated list of
name/value pairs in the format attr=value where attr can be any
connection class attribute such as DBTYPE, DBSERVER, or DBUSER.

Description

DEFINE CONNECTION creates a new connection class for a database connection.

New classes can be subclassed from existing class definitions specified in the DCM
file or from classes defined locally within the partition with the DEFINE
CONNECTION statement.

The name of the new connection class is specified by new_connection_class. This

name must not be equivalent to any other database connection class known to the
partition.
Chapter 5: Script statements

211

The SUBCLASS clause specifies the base class of the new connection class. The base
class is specified by existing_connection_class. This class must be an existing
database connection class either specified in the associated DCM file or defined by a
DEFINE CONNECTION statement previously executed by the partition.
The new database connection class will be defined throughout the lifetime of the
partition, but will not be stored or available to any other partition.
Connection class attributes can be supplied through either a USING clause or by
specifying conn_attr/conn_value pairs.

Restrictions The DEFINE CONNECTION statement can be used in all VISION 4GL methods.

Example

This example specifies connection values with the USING clause.

DEFINE CONNECTION CLASS salesconn SUBCLASS OF unifyconn
USING (DBTYPE=U2000, DBUSER=matt)

This example uses DCM class attributes.

DEFINE CONNECTION CLASS salesconn SUBCLASS OF unifyconn
DBTYPE IS $dbase_type,
DBUSER IS $dbase_user

See also

Script language
CLOSE CONNECTION (page 182)
CREATE CONNECTION (page 189)

DESTROY CONNECTION (page 224)

OPEN CONNECTION (page 298)

For information about .dcm file format, see Unify VISION: Application Reference.
Related
information

212

Unify VISION: 4GL Reference

DEINSTALL
Script statement: de-install event handler

Syntax

DEINSTALL {

Arguments

handler_ID

Description

The DEINSTALL statement de-installs an event handler. The event handler specified
by handler_ID must have been previously installed with the INSTALL statement.

handler_ID |
ALL { DBMS_ERROR | DDE_EVENT | SCRIPT_ERROR } }

Specifies the event handler to be de-installed.

When an object is destroyed, an implicit DEINSTALL is performed for all business

event handlers installed by that object.
When ALL is specified, every DBMS, DDE, and SCRIPT_ERROR handler installed by
the application is de-installed. BUSINESS_EVENT handlers are not affected.

Restrictions The DEINSTALL statement can be used in all VISION 4GL methods.

Example

This example installs and de-installs a DBMS error-handler function identified as

$genid:
METHOD ON CREATE
INSTALL DBMS_ERROR HANDLER gen_handler
FOR EVENTS EXCEPT SS_DUPK, SS_NOREC
IDENTIFIED BY $genid
. . .
METHOD AFTER FORM RETURN
DEINSTALL $genid

This statement de-installs all error-handler functions:

DEINSTALL ALL DBMS_ERROR

This example de-installs a script error-handling function.

METHOD ON DESTROY
DEINSTALL $scriptHandlerId

Chapter 5: Script statements

213

See also

214

Script language
EVENT (page 252)
EXTERN (page 263)
FUNCTION (page 271)
INSTALL (page 285)

System functions
status$( ) (page 551)

Unify VISION: 4GL Reference

DELETE
SQL DML statement

DBMS dependent

Syntax

[ USING [ CONNECTION ] connection ]

DELETE FROM SQL_clause ;

Support

This statement must conform to the syntax required by the DBMS. In addition, see the
restrictions in the Description section.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the SQL keywords or clauses permitted by the DBMS in a

DELETE command.

When VISION Runtime Manager encounters a DELETE statement, it prepares the

statement for processing by the database. Because this statement is executed by the
DBMS, it must conform to the syntax requirements of the DBMS; extensions provided
by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).

Chapter 5: Script statements

215

Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.
An exclusive lock is placed on each deleted row. If DELETE cannot obtain a lock on
the row or if any other error occurs, the delete operation fails and the statement
terminates.
If no WHERE clause is specified, DELETE attempts to delete all rows in the specified
table. These rows are deleted if DELETE does not encounter an error during the delete
operation.
You can use the status$( ) system function to test the success of a DELETE statement.
If the user does not have delete privilege, the status$( ) system function returns a
status code of SS_WRACS after a delete operation. If the record to be deleted is not
found, status$( ) returns SS_NOREC.
Warning

Using a non-interactive database statement to delete rows that have records in

the forms selected set does not delete the selected set records. The selected set
records remain unaffected by the delete operation although their associated rows have
been deleted.
INFORMIX
The WHERE clause cannot include a column having the TEXT or BYTE data type.
ORACLE
The WHERE clause cannot include a column having the LONG or LONG RAW data
type.

Restrictions This statement can be used in all VISION 4GL methods.

See also

System functions
status$( ) (page 551)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

216

Unify VISION: 4GL Reference

DELETE CURRENT RECORD

Script statement: interactive delete operation

Syntax

DELETE CURRENT RECORD

Description

The DELETE CURRENT RECORD statement simulates the uv_delete command. It

initiates an interactive delete operation to delete the target table row associated with
the forms current record. After the current record is deleted, another record in the
selected set becomes current.
If the selected set contains only one record, when the record is deleted, VISION
Runtime Manager executes a clear-to-add operation and any statements remaining in
the current method are not executed.
DELETE CURRENT RECORD does not cause the execution of any delete methods
(BEFORE DELETE or AFTER DELETE).

This statement requests an exclusive lock on the current records target table row. If
this exclusive lock request is successful, DELETE CURRENT RECORD performs the
interactive delete operation.
You can use the status$( ) system function to test the success of a DELETE
CURRENT RECORD statement.

Restrictions This statement cannot be used within a FUNCTION.

Example

This statement verifies that the user intends to delete the current record. If the user
responds yes, the delete operation is performed.
IF (yesno$(Are you sure you want to delete this record?; 1))
THEN DELETE CURRENT RECORD

Chapter 5: Script statements

217

See also

Script language
CLEAR TO ADD (page 180)
DELETE (page 215)
DELETE SELECTED ROW (page 221)
INSERT (page 283)
UPDATE (page 381)
UPDATE CURRENT RECORD (page 384)

See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
AFTER DELETE

218

Unify VISION: 4GL Reference

DELETE CURRENT SET

Script statement: delete operation

Syntax

DELETE CURRENT SET

Description

The DELETE CURRENT SET statement clears all records from the selected set; if the
form is associated with a target table, the associated database target table rows are also
deleted. If the FIND_COUNT attribute has a value greater than 0, those records not
included in the current subset are also retrieved and deleted.
After all records are deleted, VISION Runtime Manager executes a clear-to-add
operation and execution continues with any statements remaining in the current
method.
DELETE CURRENT SET does not cause the execution of any delete methods
(BEFORE DELETE or AFTER DELETE).

During a delete operation, an exclusive lock is requested on each of the associated

target table rows. If this exclusive lock request is successful, DELETE CURRENT SET
performs the delete operation. If the lock request is not successful, the affected row is
not deleted and the record remains in the selected set. However, if the
TX_MODE_DELETE_RECORD attribute is set to COMMIT and an error occurred
during the delete operation, the commit operation is not executed.
You can use the status$( ) system function to test the success of a DELETE
CURRENT SET statement. A successful delete operation returns a value of 0
(SS_NORM). Failure of this statement returns one of these possible values:
12
23
45
111
119

SS_NOTUP
SS_DELNA
SS_LMOUT
SS_RDONLY
SS_NRIDCOL

Restrictions This statement is invalid in the following methods:

FUNCTION
ON CREATE
ON FIND
Chapter 5: Script statements

219

Example

In this example, the DELETE CURRENT SET statement clears any existing selected
set for a form that has no target table. For each row retrieved by the SELECT
statement, a CLEAR TO ADD statement is executed and values are assigned to the
current record fields. Each record is then added to the new selected set by using the
UPDATE CURRENT RECORD statement.
VOID METHOD UpdateList (fClause,wClause,oClause)
BEGIN
DELETE CURRENT SET;
SET THIS_INSTANCE:$ListCount TO 0;
DISPLAY_STAT(Scanning);
SET THIS_INSTANCE:$tBug, THIS_INSTANCE:$tEngr, THIS_INSTANCE:$tD1
TO EXECUTE_SQL
select bug_id, bug_asneng, bug_desc1 +
from + $fClause +
where + $wClause +
+ $oClause
EXECUTING
BEGIN
CLEAR TO ADD;
SET THIS_INSTANCE:BugID TO THIS_INSTANCE:$tBug;
SET THIS_INSTANCE:AssignedTo TO THIS_INSTANCE:$tEngr;
SET THIS_INSTANCE:$Description TO THIS_INSTANCE:$tD1
UPDATE CURRENT RECORD;
IF THIS_INSTANCE:$ListCount >= THIS_INSTANCE:FindLimit THEN
BREAK;
END
IF status$() <> SS_NORM AND status$() <> SS_NOREC THEN
DISPLAY_DBE(Error Updating List!);
ELSE IF current_record_count$() > 1 THEN
BEGIN
CLEAR COMMAND QUEUE; /* others may have been queued */
QUEUE COMMAND FIRST_RECORD;
END
END

See also

System functions
status$( ) (page 551)

For information about selected sets, see Application execution in Unify VISION:
Related
information Concepts.

220

Unify VISION: 4GL Reference

DELETE SELECTED ROW

Script statement: non-interactive delete operation

Syntax

DELETE SELECTED ROW ;

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

Supported.

INGRES

Supported.

ORACLE

The DELETE SELECTED ROW statement is not supported for

ORACLE; use the DELETE statement.

SYBASE SQL

The DELETE SELECTED ROW statement is not

supported for SYBASE SQL Server; use the DELETE
statement.

Server

Unify DataServer

Supported.

Description

The DELETE SELECTED ROW statement initiates a non-interactive delete operation

to delete a row retrieved by a SELECT statement. The statement must be terminated
by a semicolon (;).
This statement can be used only within an EXECUTING block to delete a selected
row. If the EXECUTING block is nested within other EXECUTING blocks, the deleted
row is the row associated with the innermost block.
This statement can be used only when the table of the associated SELECT statement is
updateable, as determined by the DBMS. The SELECT statement can contain no more
than one table in the FROM clause and cannot contain a GROUP BY, ORDER BY, or
HAVING clause.
If DELETE SELECTED ROW cannot lock the selected row or if any other error
occurs, the delete operation fails.
The DELETE SELECTED ROW statement does not cause execution of the AFTER
DELETE or BEFORE DELETE statements.

Chapter 5: Script statements

221

Warning

Using the DELETE SELECTED ROW statement to delete rows that are in the
forms selected set does not delete the selected set records. The selected set records
remain unaffected by the delete operation although their associated rows have been
deleted.
Use the status$( ) system function to test the success of a DELETE SELECTED ROW
statement. If the user does not have delete privilege, the status$( ) system function
returns a status code of SS_WRACS after a delete operation.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This portion of a script uses the DELETE SELECTED ROW statement to delete all
records in the employee table where the emp_last_name field contains Harrigan.
SET emp_last, emp_first to
SELECT emp_last_name, emp_first_name FROM employee
EXECUTING
BEGIN
IF (emp_last = Harrigan) THEN
BEGIN
DISPLAY Deleted employee + emp_first + + emp_last
FOR FYI_MESSAGE WAIT
END
DELETE SELECTED ROW;
END

See also

Script language
DELETE (page 215)
DELETE CURRENT RECORD (page 217)
EXECUTING (page 259)
SELECT (page 351)
UPDATE (page 381)
UPDATE CURRENT RECORD (page 384)
UPDATE SELECTED ROW (page 386)

System functions
status$( ) (page 551)
See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
AFTER DELETE
ON FIND

222

Unify VISION: 4GL Reference

DELETE TIMER EVENT

Script statement: remove timer event

Syntax

DELETE { TIMER EVENT variable | ALL TIMER EVENTS }

Arguments

variable

Description

The DELETE TIMER EVENT statement removes a timer event request from internal
queues, thus preventing the timer event from being executed. The value of variable is
unchanged.

The name of the variable where the event ID is stored, as specified in

the CREATE TIMER EVENT statement.

The DELETE ALL TIMER EVENTS statement removes all installed timer events from
the internal queues.

Restrictions The DELETE TIMER EVENT statement can be used in all VISION 4GL methods.

Example

This statement deletes a timer event identified by $timer_id.

DELETE TIMER EVENT $timer_id

See also

Script language
CREATE TIMER EVENT (page 206)
EXTERN (page 263)

Chapter 5: Script statements

223

DESTROY CONNECTION
Script statement: destroy a database connection

Syntax

DESTROY CONNECTION connection_name

Arguments

connection_name
Specifies a string expression that contains the name of the database
connection instance to be destroyed.

Description

CLOSE CONNECTION allows a database connection instance to be dynamically

destroyed. Any future reference to the destroyed connection instance causes an error.
The connection instance to be destroyed is specified by connection_name. If that
connection instance is open, it will first be closed.
To recreate a connection instance that has been destroyed, use the CREATE
CONNECTION statement.

Restrictions The DESTROY CONNECTION statement can be used in all VISION 4GL methods.

See also

Script language
CLOSE CONNECTION (page 182)
CREATE CONNECTION (page 189)

224

DEFINE CONNECTION (page 211)

OPEN CONNECTION (page 298)

Unify VISION: 4GL Reference

DESTROY SERVICE
Script statement: destroy a service object

Syntax

DESTROY SERVICE objref

Arguments

objref

Description

The DESTROY SERVICE statement destroys the specified service object.

The object reference of the service object to be destroyed.

If the service object was created with a CREATE SERVICE statement, the service
object is automatically de-registered from the name services that were specified in that
statement.
If the service object was created at partition initialization time, the service object is
automatically de-registered from the name service that was specified in the Service
Properties panel of the Partition profile.
If the object reference identifies the same object that is executing the DESTROY
SERVICE statement, the object is destroyed, execution of the application thread is
terminated, and an error is returned to the sender of the message specifying that the
object no longer exists.

Restrictions The DESTROY SERVICE statement can be used in all VISION 4GL methods.
See also

Script language
CREATE SERVICE (page 200)

See Unify VISION: Class Reference for information about related classes and methods:
Related
information
Service::_Destroy( )
UONameService::bind( )
UONameService::unbind( )

Chapter 5: Script statements

225

DISABLE ZOOM TO
Script statement: disable zoom-enabled field

Syntax

DISABLE ZOOM TO form_name

Arguments

form_name

Description

The DISABLE ZOOM TO statement disables a zoom-enabled form field. When the
field is not zoom enabled, the user cannot access the zoom form.

The name of a zoom form. This name can either be the literal form
name (without quotation marks) or a string expression.

Disabling an already disabled zoom form does not produce an error.

Restrictions This statement can be used in any FIELD method.

Example

This sample disables the zoom form fsalesrep from the current form field, sales.
FIELD sales
METHOD BEFORE FIELD
DISABLE ZOOM TO fsalesrep

See also

Script language
ENABLE ZOOM (page 245)
VALUES TO RETURN ARE (page 389)

226

Unify VISION: 4GL Reference

DISMISS FORM
Script statement: dismiss form operation

Syntax

DISMISS FORM object_ref

Arguments

object_ref

Description

The DISMISS FORM statement closes the form specified by object_ref and returns
values to its parent form. After the DISMISS FORM statement is executed, the ON
RETURN VALUES method is executed to return specified values.

An expression that specifies the object reference of the form to be

dismissed.

If the DISMISS FORM statement is executed on the current form, execution of the
current method is terminated. However, if object_ref is not the current form, execution
of the current method is continued.
The DISMISS FORM statement does not cause execution of the ON DISMISS FORM
method.

Restrictions The DISMISS FORM statement is invalid in the following methods:

FUNCTION
ON CLEAR TO ADD
ON CLEAR TO FIND
ON DRAG ENTER
ON DRAG LEAVE

Example

ON DRAG START
ON EXIT
ON FIND
WHEN FIELD CHANGES

In the following example, the About form is dismissed if the user clicks on the Yes
button.
FORM CLASS About
COMMAND dismiss_it
BEGIN
DISPLAY NOTICE Close the form? LABELS YES DEFAULT, NO RESULT INTO
answer
IF answer = 0 THEN
DISMISS FORM About:OBJECT_ID
END

Chapter 5: Script statements

227

See also

Script language
NEXT ACTION IS DISMISS FORM (page 295)

For information about returning values, see Working with form classes in Unify
Related
information VISION: Designer.
See Predefined commands in Unify VISION: Application Reference for information
about related predefined commands:
uv_dismiss_form
See Unify VISION: Class Reference for information about related methods:
Methods
ON CANCEL FORM

228

Unify VISION: 4GL Reference

DISPLAY
Script statement: display an expression

Syntax

DISPLAY [ expression ]
[ FOR { form_field_exp | FYI_MESSAGE } ]
[ WAIT ] [ USING 'format_expression' ]
[ DISPLAY_JUSTIFY [IS] {LEFT | RIGHT | CENTERED | string_expression} ] [;]

Arguments

expression

The Unify VISION expression to be displayed. This expression can be

a string, a numeric constant, a numeric expression, or any other valid
Unify VISION expression.
(Partitioned applications only) The expression argument can include
OBJECT_REF values.

form_field_exp An expression that evaluates to an OBJECT_REF or string data type

where the value of expression is to be displayed.
format_expression
A Unify VISION format template that specifies a format for displaying
the expression.
string_expression
A string variable set to any of the values LEFT, RIGHT, or
CENTERED.

Description

The DISPLAY statement displays an expression on the screen. You can specify that the
expression be displayed in the form field specified by form_field_exp or in the
fyi_message system information field.
Identifying the value to be displayed
You list the value to be displayed after the keyword DISPLAY. This value is an
expression of any Unify VISION type except BINARY or OBJECT_REF. The object
name is used to position the display value. The expressions data type need not match
the data type of the form field where you display the expression.

Chapter 5: Script statements

229

Specifying the display field

The FOR clause specifies where the value is to be displayed. If the FOR keyword is
followed by a form_field_exp, the value is displayed in that field.
If the FOR clause refers to an expression of type OBJECT_REF, the value of the value
of this expression must identify a form field.
If expression is omitted and the FOR clause includes FYI_MESSAGE, VISION
Runtime Manager displays the current value of the current form field in the
fyi_message system information field of the screen form.
If the FOR clause is omitted, expression is displayed in the current form field. If
expression is omitted and the FOR clause includes a form field, VISION Runtime
Manager displays the current value of form_field. This form_field is the position where
the expression is displayed. None of the field attributes, such as DISPLAY_FORMAT,
affect the expression.
If the display value is omitted, Unify VISION displays the current value of the field
listed in the FOR clause.
The expression message can be any string expression. By using the concatenation
operator (+), you can create a longer string by joining two or more smaller strings.
If you include the WAIT clause in the DISPLAY statement, VISION Runtime Manager
displays a notice and waits for the user to respond to a button on the notice box. After
receiving the user response, VISION Runtime Manager resumes execution. Without the
WAIT clause, the expression can be overwritten by a form field message when VISION
Runtime Manager returns to the form field. If you omit the WAIT clause, the form
field message is displayed and execution continues.
If the fyi_message system information field is not defined, the DISPLAY FOR
FYI_MESSAGE statement has no effect. However, if you include the WAIT clause on
DISPLAY FOR FYI_MESSAGE and no fyi_message system information field is
defined, a notice box appears. In this case, the user must respond to continue
execution.
Formatting the value
You can include two types of custom display formatting in the DISPLAY statement:
field justification with the DISPLAY_JUSTIFY clause
a format specified with the USING clause
230

Unify VISION: 4GL Reference

The DISPLAY_JUSTIFY clause specifies how the display value is justified in the form
field. By default, VISION Runtime Manager displays values of all data types as left
justified.
To justify a field, include the DISPLAY_JUSTIFY clause followed by the keyword for
the type of field justification needed: LEFT, RIGHT, or CENTERED.
You can alternatively list the justification type as a string expression instead of as one
of the keywords.
The format_expression in the USING clause is a format template that determines how
AMOUNT, DATE, NUMERIC, FLOAT, and STRING values are displayed in the field
window. A display format in the USING clause overrides the setting of the fields
DISPLAY_FORMAT attribute.
If the DISPLAY statement is followed by a USING connection clause for the next
statement, separate the statements with a semicolon (;).

Restrictions When a FOR clause is included, the DISPLAY statement is valid in all VISION 4GL
methods.
If a FOR clause is omitted, this statement is not valid in a FUNCTION.
The DISPLAY statement cannot be used in a global function that is used by a service
object.

Example

The following DISPLAY statement uses the current_date$( ) system function to

display the data in the ld_next_date field on the fleads form.
DISPLAY current_date$() FOR fleads:ld_next_date

The next DISPLAY statement displays the status value in the fyi_message system
information field. This status message consists of the string status is followed by
the status$( ) return value that has been converted to a string.
DISPLAY status is + val_to_str$( status$() )
FOR FYI_MESSAGE WAIT

Chapter 5: Script statements

231

Related
For information about how to create format templates, see Format templates in
information Unify VISION: Application Reference.
See Unify VISION: Class Reference for information about the following attributes:
Attributes
DISPLAY_FORMAT

232

Unify VISION: 4GL Reference

DISPLAY FILE CHOOSER

Script statement: display a native file chooser and receive a selection

Syntax

DISPLAY FILE CHOOSER

[ TITLE IS title ]
[ INITIAL DIRECTORY IS { directory | PREVIOUS } ]
[ INITIAL SELECTION IS file | directory ]
[ DISABLE NON { READABLE | WRITABLE } FILES ]
[ ALLOW MULTIPLE SELECTIONS ]
[ CONFIRM OVERWRITE ]
[ FILE MUST EXIST ]
[ PATH MUST EXIST ]
[ SHOW HIDDEN FILES ]
RESULT INTO variable

Arguments

title

A string expression that specifies text, such as a title or message, to be

displayed at the top of the file chooser window.

directory

A string expression that specifies a relative or an absolute file path.

file

A string expression that specifies a file name.

variable

A string expression that receives the selected file or files.

Description

The DISPLAY FILE CHOOSER statement generates a file chooser dialog. The dialog
is native; that is, it appears and behaves consistent with the underlying operating
system. The file chooser dialog must be dismissed before another part of the
application can be accessed.
The optional TITLE clause specifies the title of the file chooser dialog. If omitted, the
title Unify VISION File Chooser is used.
The optional INITIAL DIRECTORY clause specifies the path of an existing directory
to open when the file chooser dialog displays. You cannot specify wild card characters
in the path specification. If the path is not absolute, it is assumed to be relative to the
current directory. If the PREVIOUS keyword is specified, the file chooser dialog
displays with the most recent directory used by the file chooser dialog in this
application. If PREVIOUS is specified and there was no previous directory in the
application, the current directory is used. If the INITIAL DIRECTORY clause is
omitted, the current directory is used.

Chapter 5: Script statements

233

The optional INITIAL SELECTION clause specifies a filename or directory to select

or open when the file chooser dialog displays. If the specified entry is not available in
the specified directory, nothing is selected in the list (it will still be the initial entry
setting). This may be useful for choosers intended to select something for writing. If
this clause is omitted, then no selection is made and the initial entry setting is an
empty string.
The optional DISABLE clause specifies whether the chooser should disable (stipple)
either non-readable files or non-writable files. If this clause is omitted, no files are
disabled. The non-readable option is useful for preventing a non-readable file from
being selected for a subsequent read operation. Similarly, the non-writable option is
useful for preventing a non-writable file from being selecting for a subsequent write
operation. Windows does not support non-readable files.
On Windows, the DISABLE NON READABLE FILES or DISABLE NON
WRITEABLE FILES optional clauses appear in the File Chooser window but do not
work if they are chosen.
The optional ALLOW MULTIPLE SELECTIONS clause specifies whether the file
chooser allows the user to select multiple files. If omitted, the chooser allows only a
single file or directory to be chosen. In this case, the RESULT INTO variable must be
scalar. If the clause is specified, then the user is allowed to make multiple selections
and the RESULT INTO variable must be a LIST.
The optional CONFIRM OVERWRITE clause specifies that the file chooser dialog
should prompt the user for whether or not they want to overwrite an existing file. This
would normally be used prior to write operations where the user is to confirm an
overwrite. If this clause is omitted, the chooser does not prompt the user for whether
or not they want to overwrite an existing file.
The optional FILE MUST EXIST clause specifies that the chooser must require the file
to exist. The chooser will then not allow the end user to type in a name of a file that
does not exist and apply it. If this clause is omitted, then the end user will be allowed
to type in the name of a file that does not exist.
The optional PATH MUST EXIST clause specifies that the directory path the user has
entered must exist. If this clause is omitted, then the directory path does not need to
exist in order for the user to apply the selection.
On Windows, the file chooser behaves as if the PATH MUST EXIST optional clause is
specified, even in the default state where this option is not specified. You cannot enter
a path as a file name if any directory element in the path does not exist.
234

Unify VISION: 4GL Reference

The optional SHOW HIDDEN FILES clause specifies to show files that are marked as
hidden by the operating system. If omitted, hidden files do not appear in the list of
files to choose from. This clause is operating system dependent. For example, on
Windows NT the Explorer determines whether or not to show hidden files.
On Windows, the Show Hidden Files setting in Windows NT Explorer takes
precedence. If the optional clause SHOW HIDDEN FILES in the File Choose
Statement is set, hidden files are displayed. If Windows NT Explorer does not have
Show Hidden Files set, they are not displayed.
The RESULT INTO clause specifies the variable to receive the file specification or
specifications. If the statement does not also include the ALLOW MULTIPLE
SELECTIONS clause, the variable must be a SCALAR. If the statement does also
include the ALLOW MULTIPLE SELECTIONS clause, the variable must be a LIST. If
the user cancelled the operation from the file chooser dialog, the variable is NULL . If
the user applied the operation, and the statement executes without error, the variable
will contain a scalar STRING or a LIST of STRING values that represent the path and
filename of the file or files chosen. If there is a runtime error in the statement, the
variable is not changed.
Your application should process any spaces in paths and filenames that occur in the
result variable.
The following dialog is a typical Windows NT file chooser dialog:

Restrictions The DISPLAY_FILE_CHOOSER statement can be used in all VISION 4GL methods.
The DISPLAY_FILE_CHOOSER statement cannot be used in a global function that is
used by a service object.
Chapter 5: Script statements

235

Example

In this example, the DISPLAY FILE CHOOSER statement is used to retrieve a single
file name from the file chooser dialog:
DISPLAY FILE CHOOSER RESULT INTO $filename;

In this example, the DISPLAY FILE CHOOSER statement is used to select a file to
which text is appended:
COMMAND DoAppendFile
BEGIN
display file chooser
title is Choose a File to Append
initial directory is PREVIOUS
path must exist
file must exist
disable non readable files
result into _TI:$tFilename;
if DEFINED(_TI:$tFilename) then
begin
set _FI:$ScriptError to SS_NORM;
retrieve text $tFile from file _TI:$tFilename;
if _FI:$ScriptError <> SS_NORM then
begin
DISPLAY_ERR(Unable to retrieve chosen file!\n + _TI:$tFilename);
end
else
begin
if not DEFINED(_TI:$Body) then
set _TI:$Body to ;
set _TI:$Body to _TI:$Body + \n + to_text$($tFile);
end
end
END

For more information about the commands and buttons on a File Chooser dialog, see
Related
information your operating system documentation or the Help system of the File Chooser dialog.

236

Unify VISION: 4GL Reference

DISPLAY NOTICE
Script statement: display a notice box

Syntax

DISPLAY NOTICE string_expression

[ LABELS button_label [ DEFAULT ] [ , button_label [ DEFAULT ] [ , . . . ]
[ RESULT INTO variable ] ]

Arguments

string_expression A string expression that specifies text, such as a title or message, to

be displayed at the top of the notice box.

Description

button_label

A string expression for a button label. Up to ten buttons can be

specified.

variable

A variable where the numeric value of the selected button is returned.

The DISPLAY NOTICE statement generates a notice box with a row of buttons. If no
labels are displayed, the notice must be dismissed by the ERASE NOTICE statement
or the user must use the Window Manager controls to close the window.
The optional LABELS clause specifies the number of buttons and their labels. A
button is created for each button_label specified. Any number of buttons can be
specified. The DEFAULT option can be specified for one button only and specifies the
button that is to be displayed as a default value. If more than one button_label is
specified, then the RESULT_INTO clause must also be specified.
If your labels are Yes and No, you can also use the yesno$( ) system function instead
of the DISPLAY NOTICE statement.
The optional RESULT INTO clause specifies a variable for receiving a value that
identifies the button selected by the user. Buttons are assigned consecutive ascending
integer values, where the leftmost button has a value of 0, the button to its right has a
value of 1, and so on.

Restrictions The DISPLAY NOTICE statement can be used in all VISION 4GL methods.
The DISPLAY NOTICE statement cannot be used in a global function that is used by a
service object.
Chapter 5: Script statements

237

Restrictions The DISPLAY NOTICE statement is invalid in the following methods:

ON DRAG ENTER
ON DRAG LEAVE
ON DRAG START

Example

In this example, a notice box appears that is titled Meal Selections and provides four
buttons. Standard is the default selection. The value of the users selection is
returned into mealplan. For example, if the user selects the Kosher button,
mealplan is set to a value of 3.
DISPLAY NOTICE Meal Selections
LABELS Standard DEFAULT, Low Salt/Low Fat, Vegan,
Kosher
RESULT INTO mealplan

In this example, a notice box appears with only one button; the statement does not use
the RESULT_INTO clause:
DISPLAY NOTICE Busy. Try again later. LABELS ok

See also

Script language
ERASE NOTICE (page 251)

238

Unify VISION: 4GL Reference

DROP SCHEMA
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

DROP SCHEMA SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Any of the keywords or statements permitted by the DBMS within a

DROP SCHEMA command.

Description

The DROP SCHEMA statement drops (destroys) a schema definition. When VISION
Runtime Manager encounters this statement, it prepares the statement for processing
by the database. Because this statement is executed by the DBMS, it must conform to
the syntax requirements of the DBMS; extensions provided by the DBMS can also be
included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

239

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($).
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions The DROP SCHEMA statement can be used in all VISION 4GL methods.

Example

This DROP SCHEMA statement destroys the schema named accounting.

DROP SCHEMA accounting;

See also

Script language
ALTER SCHEMA (page 158)
CREATE SCHEMA (page 198)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

240

Unify VISION: 4GL Reference

DROP TABLE
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

DROP TABLE SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Any of the keywords or statements permitted by the DBMS within a

DROP TABLE command.

Description

The DROP TABLE statement drops (destroys) a table definition. When VISION
Runtime Manager encounters this statement, it prepares the statement for processing
by the database. Because this statement is executed by the DBMS, it must conform to
the syntax requirements of the DBMS; extensions provided by the DBMS can also be
included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

241

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($)
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This DROP TABLE statement destroys the employee table.

DROP TABLE employee;

See also

Script language
ALTER TABLE (page 160)
CREATE TABLE (page 204)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

242

Unify VISION: 4GL Reference

DROP VIEW
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

DROP VIEW SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Any of the keywords or statements permitted by the DBMS within a

DROP VIEW command.

Description

The DROP VIEW statement drops (destroys) a view definition. When VISION
Runtime Manager encounters this statement, it prepares the statement for processing
by the database. Because this statement is executed by the DBMS, it must conform to
the syntax requirements of the DBMS; extensions provided by the DBMS can also be
included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

243

Unify VISION variables can be used as parameters within this statement but must be
prefixed by a dollar sign ($). When using Unify VISION parameters, do not enclose
this statement within a BEGIN_SQL and END_SQL statement block.

Restrictions The DROP VIEW statement can be used in all VISION 4GL methods.

Example

This DROP VIEW statement destroys the salary view.

DROP VIEW salary;

See also

Script language
CREATE VIEW (page 209)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

244

Unify VISION: 4GL Reference

ENABLE ZOOM TO
Script statement: specify zoom form for current field

Syntax

ENABLE ZOOM TO [ NEW ] CHILD FORM form_name

OF CLASS class_name
[ USING [ CONNECTION ] connection ]
[ OCCURRENCES numeric ]
[ CONSISTENCY IS consistency ]
[ TRANSACTION IS transaction ]
[ RETURN KEY
| RETURN VALUES [ INTO var1[, var2, . . . , varn ] ] ]
[ POSITION x, y ]
[ OBJECT_REF INTO variable ]

Arguments

form_name

The instance name of the zoom form. This name can either be the
literal form name or a string expression. You can use the same name
as the class_name or a different name. Use a name different from the
class_name when you want to display the same form multiple times at
runtime.

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
class_name

The name of a form class as defined in VISION Development

Environment. This name can either be the literal form class name or a
string expression.

numeric

A numeric expression that specifies the number of occurrences for

repeating groups on the form.

Chapter 5: Script statements

245

consistency

transaction

Description

One of the following keywords or a string expression that is

equivalent to one of the following keywords:
RECORD

Specifies record consistency for the form.

SET

Specifies set consistency for the form.

NONE

Specifies no consistency for the form.

One of the following keywords or a string expression that is

equivalent to one of the following keywords:
COMMIT

Specifies that the current transaction is to be

committed and locks are to be released.

CONTINUE

Specifies that the current transaction is to be

continued.

var

The name of a form field where the value is to be inserted. References

to object attributes that do not yield a VALUE are prohibited.

Specifies the pixel value at which to position the form horizontally.

Specifies the pixel value at which to position the form vertically.

variable

A variable that receives the value of the new object reference.

The ENABLE ZOOM statement specifies a zoom form for the current form field; you
can also enable zoom operations from box, button, canvas, label, and line objects.
From a zoom form the user can look up and retrieve data without leaving the context
of the current form.
A zoom form is displayed when the user executes the uv_zoom command or when the
NEXT ACTION IS ZOOM statement is executed.

Enabling an already enabled zoom form does not cause an error.

To enable the zoom capability, use the ENABLE ZOOM statement within BEFORE
FIELD method of the field that is to be zoom enabled. Including ENABLE ZOOM in
BEFORE FIELD zoom-enables the form field only in add/update/delete form mode
because BEFORE FIELD is not executed in find mode.
246

Unify VISION: 4GL Reference

The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
For each field on a form you can specify one zoom form; if you zoom-enable more
than one form, only the last form you specify is used as the zoom form.
The OCCURRENCES clause
The OCCURRENCES clause governs the number of occurrences for the repeating
group of the zoom form. By default, VISION Runtime Manager uses the number of
occurrences defined for the form in VISION Designer. If the zoom form has no
repeating group, this clause has no effect.
The CONSISTENCY IS clause
The CONSISTENCY IS clause determines the zoom form consistency level. If this
clause is omitted, the zoom form is executed at the same consistency level as the
calling form.
The RETURN KEY clause
The RETURN KEY clause enables the user to bring field values from the zoom form
back to the calling form. To bring back a value, the user executes the
uv_dismiss_form command or the uv_return_values command from the zoom form
when the record having the desired key value is current. At runtime values are
returned to check box, list box, radio group, and text field objects only.
To use the RETURN KEY clause, the zoom form must have a target table defined.
If a key consists of more than one column, there must be a form field on the original
form for each of the key values. The first key value is displayed in the zoom-enabled
field.
If RETURN KEY is specified but there is no key to return, input resumes on the
calling forms current field. Similarly, if the user executes the uv_cancel_form
command from the zoom form, no key value is returned.
The POSITION clause
The POSITION clause specifies the position of the form relative to the bottom left
corner of the screen.
Chapter 5: Script statements

247

INFORMIX

The RETURN KEY clause returns SERIAL field values.

INGRES

The RETURN KEY clause returns primary key values.

ORACLE

The RETURN KEY clause returns primary key values.

SYBASE SQL Server
The RETURN KEY clause returns primary key values.
Unify DataServer
The RETURN KEY clause returns primary key values.
The RETURN VALUES clause
The RETURN VALUES clause enables the user to bring non-key values from the zoom
form back to the calling form. To bring back a value, the user executes the
uv_dismiss_form command or the uv_return_values command from the zoom form
when the record having the desired value is current.
If the RETURN VALUES clause includes the INTO keyword, the number of variables
specified must match the number of fields specified in the VALUES TO RETURN
statement.
If the RETURN VALUES clause does not include the INTO keyword, the returned
values go first into the current field and then into the next sequential fields, up to the
number of values returned.
Field data types must match. The variables you are returning values from must have
the same data types as the corresponding variables into which you are assigning
values.
The OBJECT_REF INTO clause
The OBJECT_REF INTO clause specifics that the object reference of the zoom form is
to be returned into variable.
248

Unify VISION: 4GL Reference

Restrictions This statement can be used in any FIELD method.

Example

This example statement is in the BEFORE FIELD method of the fcompany form. The
statement enables a zoom to the fsalesrep form from the co_sales_rep field. The user
can execute the uv_dismiss_form command on fsalesrep to return the sales
representative key. The co_sales_rep field is zoom-enabled only when the form is in
add/update/delete mode because the ENABLE ZOOM statement is in the BEFORE
FIELD method.
FIELD co_sales_rep
METHOD BEFORE FIELD
ENABLE ZOOM TO CHILD FORM fsalesrep OF CLASS rep_form RETURN KEY

In the next example, the values returned from the Salesreps form are assigned to the
Salesrep and Ext fields on the Company form.
ENABLE ZOOM TO CHILD FORM Salesreps OF CLASS rep_form
CONSISTENCY IS RECORD
RETURN VALUES INTO Salesrep, Ext ;

This example uses the geography connection to display the states form.
ENABLE ZOOM TO CHILD FORM states OF CLASS states_class
USING CONNECTION geography

See also

Script language
DISABLE ZOOM TO (page 226)
VALUES TO RETURN (page 389)

For information about database connections, see Getting started in Unify VISION:
Related
information Developing an Application.
See Unify VISION: Class Reference for information about the following related
attributes and methods:
Attributes

Methods

AUTO_ZOOM
SCREEN_H
SCREEN_W
SCREEN_X
SCREEN_Y

AFTER ZOOM
BEFORE FIELD

Chapter 5: Script statements

249

END_SQL
Script statement: SQL block delimiter

Syntax

END_SQL

Description

The END_SQL statement marks the end of an SQL statement block. The SQL
statement block must begin with a BEGIN_SQL statement.
The database statements listed between the begin and end delimiters are sent directly
to the database for processing. Unify VISION variables can be used within the
statement block, but the database cannot return values to the Unify VISION
application. The BEGIN_SQL and END_SQL statements themselves are not passed to
the database.
This statement is not required for DML and DDL statements described in this manual.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This example shows how the BEGIN_SQL and END_SQL statements are used to
enclose a DBMS-specific statement.
BEGIN_SQL
CREATE UNIQUE HASH INDEX
orders_hidx ON orders (ord_number)
END_SQL

See also

Script language
BEGIN_SQL (page 162)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.

250

Unify VISION: 4GL Reference

ERASE NOTICE
Script statement: remove notice box

Syntax

ERASE NOTICE

Description

The ERASE NOTICE statement erases the last instance of a notice box. If the notice
box has been displayed several times on top of itself, ERASE NOTICE erases only the
most recently created occurrence.

Restrictions The ERASE NOTICE statement can be used in all VISION 4GL methods.
The ERASE NOTICE statement cannot be used in a global function that is used by a
service object.

See also

Script language
DISPLAY NOTICE (page 237)

Chapter 5: Script statements

251

EVENT
Declaration

Syntax

EVENT event_name ( [parm[, parm] . . . ] )

Arguments

event_name

Specifies the name of the business event.

parm

Specifies the actual parameters to be passed when the business event

is raised. A parameter declaration is specified as:
VALUE [parameter_type] parameter_name

The parameter_name declares the name of the parameter and

parameter_type specifies the data type of the parameter. The mode of
all parameters must be VALUE. Make sure that you declare LIST and
MATRIX parameters as VALUE because they otherwise default to REF.
Valid parameter types are:
AMOUNT
BINARY
BOOL
DATE
FLOAT
INTEGER
LIST

Description

MATRIX
NUMERIC
OBJECT_REF
STRING
TEXT
TIME

The EVENT statement declares a business event. EVENT statements can be placed
only within the PUBLIC section of a form or service class definition. Business events
must be derived from the form or service foundation class.
Objects of a class that declares a business event can publish the occurrence of an event
by executing the RAISE EVENT statement.
Objects that require notification of the occurrence of a business event can subscribe to
a business event by installing a business event handler using the INSTALL statement.

252

Unify VISION: 4GL Reference

The EVENT statement can optionally specify parameters to be sent to each subscribing
object when the event is raised. Because the messages sent to the subscribers are one
way, the mode of each of the parameters can be specified only as VALUE.
The data type for a parameter can be optionally specified. If the data type is not
specified, the data type of that parameter sent in the message to each subscriber will be
the data type of that parameter specified in the RAISE EVENT statement publishing
the event.
Business event handlers installed by a particular subscribing object must have a
parameter declaration list that is compatible with the parameter list declared in the
EVENT statement.
A business event handler parameter declaration is compatible with an EVENT
declaration if the following conditions are true:
The number of parameters match.
If for each of the parameters:
The data type of both parameters match exactly.
or
The data type of both parameters is not specified.
or
The data type of the parameter in the handler is not specified.
The name of each parameter in the EVENT declaration, specified by parameter_name,
declares that a VALUE parameter, possibly of a particular type, occurs at that position
in the parameter declaration list. The names need not correspond to any identifier.

See also

Script language
DEINSTALL (page 213)
INSTALL (page 285)

PUBLIC (page 314)

RAISE EVENT (page 327)

See Unify VISION: Class Reference for information about related classes:
Related
information
Service
Form

Chapter 5: Script statements

253

EXECUTE COMMAND
Script statement: execute a command

Syntax

EXECUTE COMMAND { predefined_cmd | developer_cmd }

[ ON FORM obj_ref_exp ]

Arguments

predefined_cmd
Specifies the keyword for a VISION Runtime Manager command. The
following table lists valid keywords and their equivalent VISION
Runtime Manager commands.

254

predefined_cmd

Equivalent VISION Runtime Manager command

ADD_UPDATE
ARRANGE
CANCEL_FORM
CASCADE
CHOOSE _FORM
CLEAR_TO_ADD
CLEAR_TO_FIND
DELETE
DISMISS_FORM
EXIT
FIND
FIRST_RECORD
LAST_RECORD
NEXT_FIELD
NEXT_FORM
NEXT_PAGE
NEXT_RECORD
NEXT_SET
NEXT_TAB
PREVIOUS_FIELD
PREVIOUS_PAGE
PREVIOUS_RECORD
PREVIOUS_SET
PREVIOUS_TAB
RECALL_ERROR_MESSAGE
RETURN_VALUES
TILE
ZOOM

uv_add_update
uv_arrange
uv_cancel_form
uv_cascade
none
uv_clear_to_add
uv_clear_to_find
uv_delete
uv_dismiss_form
uv_exit
uv_find
uv_first_record
uv_last_record
uv_next_field
uv_next_form
uv_next_page

uv_next_record
uv_next_set
uv_next_tab
uv_previous_field
uv_previous_page

uv_previous_record
uv_previous_set
uv_previous_tab
uv_recall_error_message
uv_return_values
uv_tile
uv_zoom
Unify VISION: 4GL Reference

developer_cmd Specifies the name of a developer-defined command. This command

must be defined in the specified form.
obj_ref_exp

Description

Specifies an expression that evaluates to an OBJECT_REF data type

that identifies the form on which to execute the command.

The EXECUTE COMMAND statement executes the specified command on the form
identified by obj_ref_exp. If the ON FORM clause is not specified, the command is
executed on the form where the EXECUTE COMMAND statement is invoked.
The command is executed in the context of the identified form. The form is not made
current before executing the command. Thus, the ON CURRENT method for the form
will not be executed before executing the command.
All methods that are normally executed for predefined_cmd are executed for the
EXECUTE COMMAND statement. The methods executed as part of the EXECUTE
COMMAND operation can cause the current form to be changed. After the execution

of the command is completed, execution resumes at the statement immediately

following the EXECUTE COMMAND statement, regardless of which form is current.
Any error that occurs is handled as an EXECUTE COMMAND error, and the method
that contains the EXECUTE COMMAND statement is terminated.
If the object that calls the method is in the same partition, SEND MESSAGE must be
specified as ONEWAY.

Restrictions The EXECUTE COMMAND statement cannot be used in any method associated with a
service object or in predefined VISION 4GL methods associated with a form object.
This statement can be used only in developer-defined methods and developer-defined
commands of a form object. It can also be used in any function that is invoked from a
developer-defined method or command. If a developer-defined method contains an
EXECUTE COMMAND statement and the method is invoked by a caller within the
same partition, in the SEND MESSAGE statement that invoked the method, use the
ONE WAY clause to avoid deadlocks with other commands.
See also

Script language
QUEUE COMMAND (page 323)

For more information about the COMMAND statement, see Classes in Unify
Related
information VISION: Class Reference.

Chapter 5: Script statements

255

EXECUTE_SQL
Script statement: execute a dynamic SQL statement

Syntax

[ USING [ CONNECTION ] connection ]

EXECUTE_SQL { SQL_handle | SQL_clause }
[ USING expression_list]
{ EXECUTING_clause | ; }
Shaded portions of the syntax are DBMS dependent.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

A string or text expression that specifies a new SQL statement to be

executed. The statement can contain question marks to be replaced by
expression_list. If the SQL statement is a SELECT statement, precede
that statement with the SET statement to accept the result.

SQL_handle

An SQL statement handle created by executing the PREPARE_SQL

statement. Since the SQL handle implicitly specifies a connection, do
not use the USING CONNECTION clause. If you specify a
connection, the status$( ) system function returns SS_HNDLNTAL.

expression_list Specifies a list of expressions that are used as input parameters to a

dynamic SQL statement. The number of expressions must be at least
as great as the required number of input parameters. If the number is
less than the required amount, then the associated statement is not
executed and an error is returned by the status$( ) system function.
256

Unify VISION: 4GL Reference

EXECUTING_clause
A VISION 4GL EXECUTING clause. The EXECUTING_clause is valid
only if SQL_handle includes a SELECT statement. This clause is
executed for each selected database row. An EXECUTING clause is
prohibited in the EXECUTE_SQL statement for matrix variables.

Description

The EXECUTE_SQL statement executes a dynamic SQL statement. The statement may
be a new statement using an expression, or a previously prepared statement referred to
by an SQL handle variable.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
If the SQL statement is a SELECT statement, then the optional EXECUTING block is
executed once for each row selected.
If the executed statement has no output parameters, the following attributes continue
to have their initial values:
OUTPUT_NAME
OUTPUT_ACCELL_TYPE
OUTPUT_DB_COLUMN_TYPE
OUTPUT_PRECISION
OUTPUT_SCALE
OUTPUT_DB_COLUMN_TYPE_CODE

If the prepared statement has no input parameters, the following attributes continue to
have their initial values:
INPUT_NAME
INPUT_ACCELL_TYPE
INPUT_DB_COLUMN_TYPE
INPUT_PRECISION
INPUT_SCALE
INPUT_DB_COLUMN_TYPE_CODE

Use the INPUT_COUNT and OUTPUT_COUNT attributes to determine the number of

input and output parameters after you have executed a statement.
When the EXECUTE_SQL statement is executed, VISION Runtime Manager frees any
dynamic resources, changes the size of the specified array to have the specified
number of rows and columns, resets the remaining array cells to UNDEFINED. The
lower bounds of the array is not changed.
Chapter 5: Script statements

257

If the array is bounded, the new size must be less than or equal to the original size. If
the array is unbounded, any size can be used. The resize operation causes the array
attributes to be set to UNDEFINED.
If the resize operation fails, the array data is lost and the upper bounds of both
bounded and unbounded arrays are reset to zero.

Restrictions The following statements are invalid in the EXECUTING block of an EXECUTE_SQL
statement:
DELETE SELECTED ROW
UPDATE SELECTED ROW

Example

In the following example, all of the first names are set to Jim in the music_collection
table when the form is created:
METHOD ON CREATE
EXECUTE_SQL UPDATE music_collection SET owner_f_name = \Jim\;

If you would like to execute the SELECT statement, you must use it in conjunction
with the SET statement to store the output from the SELECT statement. For an
example, see the example under the SET statement on page 368.
In the next example, the form1 subform script changes values for a database used by
the music_collection main form. The UPDATE statement changes the values of
ratings to 5.
FORM CLASS form1
METHOD ON CURRENT
USING CONNECTION u2kdb EXECUTE_SQL UPDATE music_collection SET \
rating TO 5;

See also

Script language
PREPARE_SQL (page 300)
FREE_SQL (page 269)

For information about dynamic SQL, see page 29.

258

Unify VISION: 4GL Reference

EXECUTING
Executing clause

Syntax

[ SET_statement ]
EXECUTING [ WITH SELECT COUNT row_count ]
BEGIN

statement_block
END

Arguments

row_count

Description

The EXECUTING clause is an optional component of the SET statement and the SQL
SELECT statement.

A numeric expression that specifies the number of selected rows to

return at a time.

The EXECUTING clause is executed for each selected database row. Without an
EXECUTING clause, the statement selects only the first row that matches the specified
search criteria and stops; any other matching rows are not selected.
The EXECUTING clause causes VISION Runtime Manager to select all matching
rows. For each selected row, VISION Runtime Manager assigns the column values to
the variables in the SET statement variable list (if one exists) and then executes the
statements in statement_block.
The variable list in the SET statement must have at least as many elements as the
column list in the SELECT statement. In addition, these lists are ordered: the value
from the first column in the column list is assigned to the first variable in variable list,
the value from the second column value to the second variable, and so on until the end
of both lists. For this reason, corresponding elements of the database column list and
the variable list must be type compatible. Additional, unused variables in the SET list
are unaffected.
VISION Runtime Manager assigns the specified column values to the variables in the
SELECT variable list and then executes statements in the execution block once for

each selected row. Therefore, you can use the variables in the variable list within the
execution block.
Chapter 5: Script statements

259

The following table summarizes the combinations of the WHERE and EXECUTING
clauses and the rows selected by the SELECT statement.
Clause

Rows selected

No EXECUTING clause and no WHERE

clause

First row in the table

WHERE clause and EXECUTING clause

All rows that meet the WHERE

clause search criteria

WHERE clause only

First row that meets the WHERE

clause search criteria

EXECUTING clause only

All rows in the table

The WITH SELECT COUNT clause applies to VISION/Web only. It is ignored in

standard Unify VISION. This clause determines the row buffering behavior across the
network to the uodsd.
The WITH SELECT COUNT specifies the number of rows to return at a time. If this
clause is not provided, the default of 100 rows is used. This clause is useful in cases
where the result set can be easily limited programmatically but more difficult or
expensive to limit using only relational SQL semantics.
For instance, finding the three rows with the highest value of a particular column.
First, you perform the SELECT sorting on the column of interest with a select count of
three. Then, break out of the EXECUTING clause after saving the first three rows
encountered. The number of rows returned will affect the size of messages passed on
the network between the uowebd and the Web client partition, the amount of memory
in the uodsd and Web client partition for managing the result row set, and (depending
on the query) the number of extra rows that are locked in the database.

Restrictions This clause can be used in all VISION 4GL methods.

The ROLLBACK WORK statement is invalid within the statement block unless
ROLLBACK WORK DEMOTING LOCKS is specified.

260

Unify VISION: 4GL Reference

Example

This example shows a SELECT statement with an ORDER BY clause. The SELECT
statement sorts all rows in the employee table alphabetically by last name. If two
employees have the same last name, the employees are sorted by first name. It then
sends the last_name, first_name, and salary values over the Unify VISION pipeline
report for formatting.
SET $last_name, $first_name, $salary TO
SELECT emp_last_name, emp_first_name, emp_salary
FROM employee
ORDER BY emp_last_name ASCENDING, emp_first_name ASCENDING
EXECUTING
BEGIN
WRITE PIPELINE $report, $last_name, $first_name, $salary
END

The next SELECT statement selects all employees with a job code of REP. The
EXECUTING clause is executed once for each row selected. The effect is to display
the values of the three variables for every employee with a job code of REP. Note
that none of the selected rows are locked, because the locking clause has been omitted.
SET s_emp_first, s_emp_last, s_emp_ext TO
SELECT emp_first_name, emp_last_name, emp_ext
FROM employee
WHERE emp_job_code = REP
EXECUTING
BEGIN
DISPLAY s_emp_first + + s_emp_last + + s_emp_ext WAIT
END

See also

Script language
BREAK (page 168)
CONTINUE (page 187)
DELETE SELECTED ROW (page 221)
INSERT (page 283)
SELECT (page 351)

Chapter 5: Script statements

SET (page 359)

SLOCK (page 369)
UPDATE SELECTED ROW (page 386)
XLOCK (page 398)

261

EXIT
Script statement: exit the application

Syntax

EXIT

Description

The EXIT statement ends execution of the application. This statement simulates the
VISION Runtime Manager uv_exit command.
The ON DESTROY methods of all forms are executed. Then the ON EXIT method of
the current form is executed.

Restrictions The EXIT statement can be used in all VISION 4GL methods and functions.

Example

This EXIT statement exits the application when an error occurs.

IF (status$() <> SS_NORM) THEN
BEGIN
DISPLAY Database is unavailable at this time. Try again later.
FOR FYI_MESSAGE WAIT
EXIT
END

See also

See Unify VISION: Class Reference for information about the following related
methods:
Methods
ON DESTROY
ON EXIT

262

Unify VISION: 4GL Reference

EXTERN
Script statement: external function declaration

Syntax

DBMS dependent

EXTERN
{ {C | HOOK |SCRIPT | STORED } function_clause

| message_handler }

Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

The STORED keyword is supported for INFORMIX as described on

page 264.

ORACLE

The STORED keyword is supported for ORACLE as described on page

264.

SYBASE SQL

The STORED keyword is supported for SYBASE SQL

Server as described on page 264.

Server

Unify DataServer

The STORED keyword is supported for Unify DataServer stored

procedures.

Arguments

function_clause A FUNCTION statement.

message_handler
A VISION 4GL MESSAGE_HANDLER definition.

Description

The EXTERN statement declares an external function within a script. This statement is
the declaration for a function with a definition that is not in the same file as the
function call. A function declaration notifies the Unify VISION compiler that the
function variable is not defined within the script but refers to an external function. 3GL
functions and global functions must be declared with the EXTERN statement.

Chapter 5: Script statements

263

For an external language function, use the HOOK keyword. For a VISION 4GL
function, use the SCRIPT keyword. For an INFORMIX or Unify DataServer stored
procedure, use the STORED keyword.
The EXTERN statement must correspond to the definition of the external function.
This external function can be written in the C programming language (C) or in the
VISION 4GL language (SCRIPT).
For a VISION 4GL function, the EXTERN statement must match the definition of the
global function. The difference between the function header in the definition and the
EXTERN statement is the presence of the keyword EXTERN. You do not have to
match the functions actual parameter names in the EXTERN statement.
For a C language function, the EXTERN statement must list the Unify VISION data
type that corresponds to the functions return type, the function name, and the function
parameters. To set a value in the application through the parameter list, the parameter
to contain the value must be preceded by the keyword RESULT.
EXTERN statements must be the first statements in a script. Subsequent function calls
must be compatible with the function type declared by the EXTERN statement.

INFORMIX
The STORED keyword declares a stored procedure of type ROW_VALUED.
ORACLE
The parameter names listed in the function must match the parameter names specified
in the stored procedure definition.
SYBASE SQL Server
A function type of either NUMERIC or ROW_VALUED is required. The parameter
names listed in the function must match the parameter names specified in the stored
procedure definition.
Unify DataServer
The STORED keyword declares a stored procedure. The stored procedure must use the
syntax described in the Unify DataServer SQL/A documentation.
264

Unify VISION: 4GL Reference

Restrictions The EXTERN statement is not valid in any method.

Example

This EXTERN statement declares an external C function named paycalc( ) that has as
three value parameters principal, rate, and term. It returns a FLOAT value.
EXTERN C FLOAT FUNCTION paycalc(principal,rate,term)

This next EXTERN statement declares an external VISION 4GL function named
calculate_pay( ). This global function has three arguments: two are value parameters
(gross_salary and days_in_period) and one is a result parameter (taxes). The
function returns an AMOUNT value.
EXTERN SCRIPT AMOUNT FUNCTION calculate_pay
(gross_salary, days_in_period, RESULT taxes)

SYBASE SQL
Server

The following EXTERN statement declares a NUMERIC stored procedure named

sp_sum( ) that has two parameters and returns a numeric value.
EXTERN STORED NUMERIC FUNCTION sp_sum(a,b);

The following EXTERN statement declares a ROW_VALUED stored procedure named

sp_nbrs( ) that has two parameters and returns a RESULT value.
EXTERN STORED ROW_VALUED FUNCTION sp_nbrs(RESULT a, b);

The sp_nbrs( ) stored procedure definition contains an OUTPUT parameter that

corresponds to the EXTERN statement RESULT parameter.
CREATE PROC sp_nbrs @a int OUTPUT, @b int
AS SELECT . . .

INFORMIX

The following EXTERN statement declares a ROW_VALUED stored procedure

named sp_items( ).
EXTERN STORED ROW_VALUED
FUNCTION sp_items(ge_value);

The sp_items( ) function is called in a script by using the following statements:

SET $cnt TO 0;
SET $key, $item_cost TOsp_items(100.00)
EXECUTING
BEGIN
. . .
SET $cnt TO $cnt + 1;
END

Chapter 5: Script statements

265

Unify DataServer
The following EXTERN statement declares a NUMERIC stored procedure named
sp_sum( ) that has two parameters and returns a numeric value.
EXTERN STORED NUMERIC FUNCTION sp_sum(a,b);

See also

Script language
CREATE TIMER EVENT (page 206)
DEINSTALL (page 213)
DELETE TIMER EVENT (page 223)
FUNCTION (page 271)
INSTALL (page 285)
SET (page 359)

System functions
sp_compute$( ) (page 536)
sp_return$( ) (page 538)
sp_select$( ) (page 541)

For information about how to use functions, see Script functions (page 57).

266

Unify VISION: 4GL Reference

FOR
Script statement: loop execution

Syntax

FOR ( [ initialization ]; [ logical_expression ];

[ re-initialization ] )

statement_body

Arguments

initialization

Any valid Unify VISION expression. The expression is evaluated once

at the beginning of the loop. It usually initializes the loops control
variable.

logical_expression
Any Unify VISION BOOLEAN expression. The expression is
evaluated at the beginning of each loop iteration. The statement_body
is executed until this expression becomes FALSE.
re-initialization Any valid Unify VISION expression. This expression is evaluated at
the end of each loop iteration. It usually re-initializes the loops
control variable.
statement_body Any valid VISION 4GL statement: either a single statement or a
statement block (statements surrounded by BEGIN and END).

Description

The FOR statement executes statement_body as long as the logical_expression is

TRUE.
The FOR statement can have up to three possible expressions following the keyword
FOR: the initialization expression, the logical_expression, and the re-initialization
expression. All three expressions are optional. Expressions must be separated by a
semicolon (;). Even if you omit one of the FOR expressions, you must still include the
separator.
To execute the FOR statement, VISION Runtime Manager first evaluates the
initialization expression, if it exists. The initialization expression usually initializes the
FOR loops control variable. The control variable can be used in logical_expression to
control the number of times that the loop is executed.

Chapter 5: Script statements

267

Next, VISION Runtime Manager evaluates the logical_expression. The

logical_expression is the second expression that follows the keyword FOR (if the
initialization expression exists). This expression determines the number of times that
the statement body is executed.
If the logical_expression evaluates to TRUE, the statement_body is executed. If
logical_expression evaluates to FALSE, the FOR loop exits. If logical_expression
contains a null value, it evaluates to FALSE.
After it has completed execution of the statement_body, VISION Runtime Manager
evaluates the re-initialization expression, if it exists. The re-initialization expression
usually re-initializes the FOR loops control variable.
VISION Runtime Manager continues executing the re-initialization expression, testing

the logical_expression and executing the statement_body until logical_expression is

FALSE. When the logical_expression is FALSE, the FOR loop ends.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This statement displays the numbers 1 through 99 in the current form field.
FOR (SET $index TO 1; $index < 100; SET $index TO $index + 1)
BEGIN
DISPLAY index
END

See also

268

Script language
BREAK (page 168)
CONTINUE (page 187)

REPEAT (page 337)

WHILE (page 393)

Unify VISION: 4GL Reference

FREE_SQL
Script statement: release resources for an SQL handle

Syntax

FREE_SQL SQL_handle_var

Arguments

SQL_handle_var

An SQL statement handle created by executing the PREPARE_SQL

statement. Since the SQL handle implicitly specifies a connection, do
not use the USING CONNECTION clause. If you specify a
connection, the status$( ) system function returns SS_HNDLNTAL.

Description

The FREE_SQL statement releases any resources used by the previously prepared
statement referenced by the specified SQL_handle_var. SQL handles do not need to be
explicitly freed. VISION Runtime Manager frees an SQL handle when the variable is
out of scope or is reused in a PREPARE_SQL statement.
Use the IS_VALID attribute to determine if the SQL handle needs to be freed. SQL
handles are implicitly freed when a handle variable goes out of scope or is reused in a
PREPARE_SQL statement.
Use the status$( ) system function to see if the SQL handle is a handle and if the SQL
handle is currently valid. If the SQL handle was not currently valid, status$( ) system
function returns SS_INVHNDL. If the SQL handle was not a handle, status$( ) returns
SS_NOTHNDL.
If the FREE_SQL statement is successful, the IS_VALID attribute is set to FALSE.

Example

The following example releases the memory used by the chng_owner_hndl SQL
handle.
METHOD ON CREATE
PREPARE_SQL UPDATE music_collection SET owner_f_name = \Jim\
INTO chng_owner_hndl;
EXECUTE_SQL $chng_owner_hndl;
FREE_SQL $chng_owner_hndl;

Chapter 5: Script statements

269

See also

Script language
EXECUTE_SQL (page 256)
PREPARE_SQL (page 300)

For information about dynamic SQL, see Writing scripts (page 3).

270

Unify VISION: 4GL Reference

FUNCTION
Script statement: function definition

Syntax

DBMS dependent

[LOCAL] function_type FUNCTION { function_name |

[package.]procedure_name[@db_link] }
{ ( [ [ parameter_type ] parameter [, [ parameter_type ] parameter . . .] ) |
(event_ID) }
[ PUBLIC_variables ]
[ PRIVATE_variables ]
BEGIN

function_body
END [ ; ]

Arguments

function_type

Specifies the type of data returned by the function. Valid types are:
AMOUNT
BINARY
BOOL
DATE
DBMS_ERROR
FLOAT
INTEGER
NUMERIC

OBJECT_REF
ROW_VALUED
STRING
SCRIPT_ERROR
TEXT
TIME
TIMER
VOID

If the function does not return a value, use the keyword VOID as the
function_type.
For a DBMS error-handling function, specify the function_type as
DBMS_ERROR. Only one parameter can be specified.
For a timer function, specify the function_type as TIMER.
For a global script error-handling function, specify the function_type
as SCRIPT_ERROR. SCRIPT_ERROR cannot be used for a LOCAL
function. Only one parameter can be specified.
(INFORMIX only) For a stored procedure, specify a function_type of
ROW_VALUED.
(ORACLE only) For a stored procedure, specify a function_type of
VOID or a Unify VISION data type, such as NUMERIC.
Chapter 5: Script statements

271

(SYBASE SQL Server only) For a stored procedure, specify a

function_type of NUMERIC or ROW_VALUED.
(Unify DataServer only) For a stored procedure, specify a
function_type of VOID or a Unify VISION data type, such as
NUMERIC.
function_name The name of a LOCAL or EXTERN function. The specified function
name can appear in only one EXTERN statement per script.
(INFORMIX, SYBASE SQL Server and Unify DataServer only) For a
STORED function, the name of a stored procedure.
[package.]procedure_name[@db_link]
(ORACLE only) Provides the specification for a packaged subprogram
stored in a remote database.
parameter_type One of the following parameter types:
REF[ERENCE]
REF[ERENCE] LIST
REF[ERENCE] MATRIX
RESULT
RESULT LIST
RESULT MATRIX
VALUE
VALUE LIST
VALUE MATRIX

If no parameter type is specified for a LIST or MATRIX variable, the

default type is REF. If no parameter type is specified for other types of
variables, the default type is VALUE.
For an error-handling function, specify the parameter_type as LIST.
(ORACLE only) For a stored procedure, formal parameters must be
scalar; list and matrix variables are prohibited. IN parameters of a
stored procedure must be declared as VALUE parameters. OUT or
IN/OUT parameters of a stored procedure must be declared as
RESULT parameters.
(Unify DataServer only) For a stored procedure, specify RESULT or
VALUE.
272

Unify VISION: 4GL Reference

parameter

Specifies an identifier used as the parameter name. Only one

parameter can be specified for DBMS_ERROR or SCRIPT_ERROR
functions.

event_ID

For a TIMER event, identifies the current timer.

PUBLIC_variables

For a global function, specifies a VISION 4GL PUBLIC statement; this

argument is invalid for a LOCAL function.
PRIVATE_variables
A VISION 4GL PRIVATE statement.

function_body The VISION 4GL statements that define the function task. Some
statements are invalid in a function body. Invalid statements are listed
under Restrictions in this section.

Description

The FUNCTION statement defines a VISION 4GL function. A function contains

VISION 4GL statements. Functions can have parameters and they can return values.
There are two types of VISION 4GL functions: global functions and local functions.
You can call a global function from any script. Within a global function, you can
define one or more local functions. The FUNCTION statement must be used after the
global function header and any existing local variable definitions.
The FUNCTION statement cannot be used within a local function.
To declare a global function, use the EXTERN statement in the script where you call
the global function. In some cases, to prevent compiler errors you must also include
the EXTERN statement in a local function, for example:
If a local function calls a function that is defined further in the script, you must
include an EXTERN statement for the called function.
If a local function in a global function recursively calls the global function, the
global function script must include an EXTERN statement.
You can call a local function only from within the script in which it is defined. VISION
Runtime Manager treats a local function as another VISION 4GL method. To define a
local function, include the function definition in the FORM section, after the PRIVATE
and PUBLIC clauses. You do not need to declare local functions.

Chapter 5: Script statements

273

Parameters are not required in a function, but if a function has a parameter list, this list
must include the parentheses.
These function parameters can be a combination of value parameters, reference
parameters, or result parameters. Changing the value of a value parameter within the
function does not affect the value of the associated argument in the calling script.
Changing the value of a result parameter causes VISION Runtime Manager to copy the
result parameter value into the associated function argument when the function exits.
To call a function, include the function name and any associated function arguments in
parentheses. Even if a function does not have parameters, you must include the open
and close parentheses in the function call. If the function returns a value, you can save
this value by assigning the return value to a variable with a SET statement.
To pass a NULL constant into a function you must first use a data type conversion
system function.
The PRIVATE_variables and PUBLIC_variables clauses specify local variables for the
function. Public local variables are declared with a PUBLIC clause and can only be
specified for a global function.
Private local variables are declared with a PRIVATE clause and can be specified for
both local and global functions.
Local and global functions can be recursive.

Restrictions The following statements are invalid in a function:

CANCEL FORM
CHANGE CURRENT RECORD TO
CLEAR TO ADD
DISABLE ZOOM TO
DISMISS FORM

274

ENABLE ZOOM TO
EXTERN
INPUT
MAKE CURRENT

Unify VISION: 4GL Reference

Example

This first FUNCTION statement example defines a local function called

calculate_benefit( ). This local function has three parameters: one result parameter
(cum_benefit) and two value parameters (benefit_rate and days_in_period). This
function also has a local PRIVATE variable, benefit. The calculate_benefit( ) function
does not return a value.
LOCAL VOID FUNCTION calculate_benefit
(RESULT cum_benefit, benefit_rate, days_in_period)
PRIVATE benefit
BEGIN
SET benefit TO benefit_rate * days_in_period
SET cum_benefit TO cum_benefit + benefit
END

The next function defines a global function called calculate_pay( ). This global
function has three parameters: one result parameter (taxes) and two value parameters
(gross_salary and days_in_period).
This function also has two local PRIVATE variables: net_salary and net_pay. The
calculate_pay( ) function returns the AMOUNT value of net_pay. Defined within the
global calculate_pay( ) function is the local function, get_netpay( ).
LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)
PRIVATE the_taxrate, net_pay
BEGIN
SET the_taxrate TO
SELECT tax_rate FROM rates
WHERE lower_sal <= gross_salary
AND upper_sal >= gross_salary
SET taxes TO (gross_salary * the_taxrate)
SET net_salary TO gross_salary taxes
RETURN (net_salary)
END
AMOUNT FUNCTION calculate_pay
(gross_salary, days_in_period, RESULT taxes)

PRIVATE net_salary, net_pay

BEGIN
SET taxes TO 00.00
SET net_salary TO get_netpay(gross_salary, taxes)
SET net_pay TO (net_salary / days_in_period)
RETURN (net_pay)
END

Chapter 5: Script statements

275

See also

Script functions (page 57)

Script language
CREATE TIMER EVENT (page 206)
DEINSTALL (page 213)
EXTERN (page 263)
INSTALL (page 285)

PRIVATE (page 304)

PUBLIC (page 314)
RETURN (page 344)

Related
For information about ORACLE packaged subprogram specifications, see your
information ORACLE documentation.

276

Unify VISION: 4GL Reference

GRANT
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

GRANT SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the keywords or statements permitted by the DBMS within a

GRANT command.

When VISION Runtime Manager encounters the GRANT statement, it prepares the
statement for processing by the database. Because this statement is executed by the
DBMS, it must conform to the syntax requirements of the DBMS; extensions provided
by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

Chapter 5: Script statements

277

Restrictions The GRANT statement can be used in all VISION 4GL methods.

See also

Script language
DELETE (page 215)
INSERT (page 283)
REVOKE (page 346)

SELECT (page 351)

UPDATE (page 381)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

278

Unify VISION: 4GL Reference

IF
Script statement: conditional execution

Syntax

IF logical_expression THEN statement_body1

[ ELSE statement_body2 ]

Arguments

logical_expression
Any Unify VISION expression that evaluates to a BOOLEAN value.
The expression determines whether statement_body1 is executed. If
there is an ELSE clause, this expression determines whether
statement_body1 or statement_body2 is executed.
statement_body1
Any valid Unify VISION statement: either a single statement or a
statement block (statements surrounded by BEGIN and END). This
statement body is executed if logical_expression is TRUE.
statement_body2
Any valid Unify VISION statement: either a single statement or a
statement block (statements surrounded by BEGIN and END). This
statement body is executed if logical_expression is FALSE.

Description

The IF statement conditionally executes statement_body1. To execute the IF

statement, VISION Runtime Manager first evaluates logical_expression. The
logical_expression determines whether statement_body1 is executed.
TRUE

If the logical_expression is TRUE, statement_body1 is executed.

FALSE

If there is an ELSE clause and logical_expression is FALSE, VISION

Runtime Manager executes statement_body2. If there is no ELSE
clause and logical_expression is FALSE, VISION Runtime Manager
skips over statement_body1 and continues execution with the next
statement.

If the logical_expression contains a null value, it evaluates to FALSE.

Chapter 5: Script statements

279

Restrictions This statement can be used in all VISION 4GL methods.

Example

The first IF statement example sets the order terms to the default value of 2% 10, net
30 days if the user does not enter a value for it.
IF ( forders:ord_terms IS UNDEFINED ) THEN
SET forders:ord_terms TO 2% 10, net 30 days

The next example checks the value of the pay_periods variable in order to determine
the action to take. If pay_periods is 0, VISION Runtime Manager sets period_sal to
NULL. If pay_periods is any value other than 0, VISION Runtime Manager uses that
value to calculate the value of the period_sal variable.
IF ( pay_periods = 0) THEN
SET period_sal TO NULL
ELSE
SET period_sal TO total_sal / pay_periods

The next example checks that the value of the ORDPAID field is either undefined or
null before setting the ORDPAID field to zero.
/* If the client has not paid, set amount paid to zero: */
IF ($ORDPAID is undefined) OR ($ORDPAID is null) THEN
SET $ORDPAID to 0

See also

280

Script language
SWITCH (page 375)

Unify VISION: 4GL Reference

INPUT
Script statement: suspend execution for user input

Syntax

FIELD_section
ON_FIELD_method
INPUT

Arguments

FIELD_section A FIELD section.

ON_FIELD_method

An ON FIELD method.

Description

The INPUT statement retrieves information that the user enters in the current form
field. When VISION Runtime Manager reaches an INPUT statement in an ON FIELD
method, it pauses execution until the user selects another field.
When the user moves to another form with either uv_next_form (to a child form) or
uv_zoom (to a zoom form), VISION Runtime Manager suspends execution of the ON
FIELD method. When the user returns to this form, execution resumes at the
beginning of the ON FIELD method.
The INPUT statement is affected by the current value of the fields attributes. If a
fields FOCUSABLE attribute is set to FALSE, then the INPUT statement is not
executed. However, the remaining statements in ON FIELD are executed regardless of
the fields FOCUSABLE setting.
If you use ON FIELD, you must include the INPUT statement somewhere within ON
FIELD if you want input to be accepted. VISION Runtime Manager does not perform
an automatic INPUT operation if the FIELD section has an ON FIELD method.
If the fields UPDATEABLE attribute is set to FALSE, the user cannot enter new data in
the field when the form is in add/update/delete mode. If the fields FINDABLE
attribute is set to FALSE, the user cannot enter search values in the field when the form
is in find mode.

Chapter 5: Script statements

281

If the fields REQUIRED attribute is set to TRUE, the user must enter data before
being allowed to continue to the next form field.
You can test information entered by the user in the ON FIELD method. If the input is
not correct, you can require that the user reenter it by including the RESTART ON
FIELD statement in ON FIELD.
You can use the INPUT statement only in the ON FIELD method. If you omit the
INPUT statement, VISION Runtime Manager does not pause to accept data.

Restrictions This statement is valid only in an ON FIELD method.

Example

This script sample receives input from the field sc_name_field. After the user enters a
value, the input value is passed to a user function, namechk( ).
If namechk( ) returns FALSE, the input is not valid. The code then displays an error
message in the fyi_message system information field and restarts the ON FIELD
method.
FIELD sc_name_field
METHOD ON FIELD
INPUT
IF (NOT namechk($sc_name_field)) THEN
BEGIN
DISPLAY
Letters, blanks, apostrophes, hyphens only
FOR FYI_MESSAGE WAIT
RESTART ON FIELD
END

See also

Script language
RESTART ON FIELD (page 340)

See Unify VISION: Class Reference for information about the following related
Related
information method:
Methods
ON FIELD

282

Unify VISION: 4GL Reference

INSERT INTO
SQL DML statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

INSERT INTO SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Any of the keywords or statements permitted by the DBMS within an

INSERT INTO command.

Description

The INSERT INTO statement initiates a non-interactive insert operation to create a

new row in the database table. The INSERT INTO statement does not cause execution
of the BEFORE ADD or AFTER ADD methods.
The INSERT INTO statement allows access to only one database table at a time. You
cannot include more than one table name in this statement.

Chapter 5: Script statements

283

The INSERT INTO statement issues an exclusive lock request on the new row. After
the insert operation is completed, the lock remains until the current transaction is
committed.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
You can use the Unify VISION system function status$( ) to test the success of a
non-interactive insert operation. If the user does not have insert privilege, the
status$( ) function returns a status code of SS_WRACS.

Restrictions The INSERT INTO statement can be used in all VISION 4GL methods.

See also

System functions
status$( ) (page 551)

For complete syntax information, see the documentation provided by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

284

Unify VISION: 4GL Reference

INSTALL
Script statement: install a global event handler

Syntax

INSTALL BUSINESS_EVENT HANDLER name

FOR EVENT event_name IN event_objref
IDENTIFIED BY handler_id
INSTALL DDE_EVENT HANDLER name
FOR EVENTS dde_event
IDENTIFIED BY handler_id
INSTALL SCRIPT_ERROR HANDLER name
FOR ALL EVENTS
IDENTIFIED BY handler_id
INSTALL DBMS_ERROR HANDLER name
FOR { ALL EVENTS | EVENTS [ EXCEPT ] expression_list }
IDENTIFIED BY handler_id

Arguments

name

Specifies the method to be invoked in the subscribing object when the

specified business event occurs or the global function name that is to
be called when a DBMS error, script error, or DDE event occurs.

event_objref

Specifies the object reference to the object that declares and publishes
a business event.

event_name

Specifies the name of the business event to subscribe to.

expression_list For DBMS_ERROR handlers, one or more status$( ) return values,

separated by commas.
dde_event

For DDE_EVENT handlers, dde_event can be one of the following

keywords:
EXECUTE_COMMAND
INITIATE_HOT_LINK
INITIATE_LINK
RECEIVE_DATA

REQUEST_DATA
TERMINATE_HOT_LINK
TERMINATE_LINK

For BUSINESS_EVENT handlers this parameter is not used.

handler_id
Chapter 5: Script statements

A variable that identifies the particular installation of the handler.

285

Description

The INSTALL statement installs an event handler. The method specified by name must
be declared as an EXTERN function in the script where the function is installed.
A FOR clause is required to specify the events to be installed. The FOR ALL EVENTS
clause specifies that all events of the specified type are to be installed; this clause is
invalid for the DDE_EVENT HANDLER option.
The FOR EVENTS clause specifies events to be included. The FOR EVENTS clause
with the EXCEPT option specifies events to be excluded. The FOR EVENTS clause is
required for the DDE_EVENT HANDLER option.
DDE event handlers
The global functions for DDE events require certain parameters, depending on the
DDE event:
Events and event handler global functions
For this type of DDE event:

The global function requires these arguments:

Execute command

Client_link_ID, command

Initiate hot link

Link_ID, item

Initiate link

Client_link_ID, application, topic

Receive data

Client_link_ID or server_link_ID, item, data

Request data

Client_link_ID, item

Terminate hot link

Client_link_ID or server_link_ID, item

Terminate link

Client_link_ID or server_link_ID

The following table describes the types of data represented by the DDE event-handler
function arguments.
Event handler global function arguments
Parameter

Data type

Description

Application

STRING

Name of the application that the client wants to act as a

DDE server or the name of the application link file.

Client_link_ID NUMERIC
286

If the application name is NULL, VISION Runtime

Manager links to any available application.
Unique identifier for a DDE client.
Unify VISION: 4GL Reference

Event handler global function arguments (continued)

Parameter

Data type

Description

Command

STRING

Data

STRING

Item

STRING

Name of a command that the DDE client wants Unify

VISION to execute.
Data value that is passed to Unify VISION by a DDE
client.
Name of a data item that the client requests through a
request data event or an initiate_hot_link event.
Unique identifier for a DDE server.

Server_link_ID NUMERIC
Topic

STRING

Name of a set of related items from which the client

will usually request a specific data item, for example, a
table name or a form name.

Business event handlers

A business event handler is invoked when a particular business event occurs. A
business event is a developer-defined event that is declared with the EVENT
statement. The object that installs a business event handler is the subscriber to the
event.
The object that executes the INSTALL statement is the subscribing object. The
subscribing object must be derived from either the form or service foundation class.
The handler method must be declared as a METHOD in the class of the subscribing
object. The method parameters must match the declaration of the parameters specified
in the EVENT declaration for the business event. The parameters must be declared
with a mode of VALUEthe compiler does not verify the mode.
The business event to subscribe to is specified by event_name. The reference to the
object in which the event exists is specified by event_objref; this object is the
publishing object. event_name must be declared as an EVENT in the PUBLIC section
for the class of the publishing object.
The subscribing object and the publishing object can be contained in the same or
different partitions, possibly on different machines connected through a network.
The publishing object raises or publishes an event occurrence by executing a RAISE
EVENT statement. When an event is raised, an asynchronous message is sent to each
subscribing object, thereby notifying those objects of the occurrence of the event.
When the message is received, the business event handler installed for that event is
invoked. The parameter values passed to the invocation of method_name will be those
specified by the publishing object in the RAISE EVENT statement.
Chapter 5: Script statements

287

A subscribing object can unsubscribe from a business event by executing a

DEINSTALL statement.
When an object is destroyed, an implicit DEINSTALL is performed for all business
event handlers installed by that object.

Restrictions This statement is valid in all VISION 4GL methods.

Example

This statement installs a function that is called when a database deadlock occurs:
INSTALL DBMS_ERROR HANDLER deadlock_handler FOR EVENTS SS_DEADLOCK
IDENTIFIED BY $deadlockid

This statement installs a function that is called when any DBMS error occurs except
when a duplicate key or no records are found:
METHOD ON CREATE
INSTALL DBMS_ERROR HANDLER gen_handler
FOR EVENTS EXCEPT SS_DUPK, SS_NOREC
IDENTIFIED BY $genid

This example installs a script error-handling function:

EXTERN SCRIPT SCRIPT_ERROR FUNCTION script_handler(LIST error_info)
METHOD ON CREATE
INSTALL SCRIPT_ERROR HANDLER script_handler FOR ALL EVENTS IDENTIFIED BY
handler_id

This example declares several DDE event handler functions (InitiateLink,

RequestData, StartHotLink, StopHotLink, ReceiveData, ExecuteCmd, and
Terminate) and then installs three DDE event handler functions in the ON CREATE
method.
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN
EXTERN

SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT
SCRIPT

BOOL FUNCTION InitiateLink(Client_ID, Appl_name, Topic)

STRING FUNCTION RequestData(Client_ID, Item)
BOOL FUNCTION StartHotLink(Link_ID, Item)
BOOL FUNCTION StopHotLink(Client_ID, Item)
VOID FUNCTION ReceiveData(Client_ID, Item, Data)
BOOL FUNCTION ExecuteCmd(Client_ID, Command)
VOID FUNCTION Terminate(Client_ID)

FORM tutorial
PUBLIC MATRIX hotlinks[1 TO UNKNOWN, 1 TO 2], numhotlinks

288

Unify VISION: 4GL Reference

METHOD ON CREATE
INSTALL DDE_EVENT HANDLER InitiateLink
FOR EVENTS INITIATE_LINK
IDENTIFIED BY $initid
INSTALL DDE_EVENT HANDLER RequestData
FOR EVENTS REQUEST_DATA
IDENTIFIED BY $reqid
INSTALL DDE_EVENT HANDLER StartHotLink
FOR EVENTS INITIATE_HOT_LINK
IDENTIFIED BY $hotlinkid

See also

Script functions (page 57)

Script language
DEINSTALL (page 213)
EVENT (page 252)
EXTERN (page 263)
FUNCTION (page 271)
PUBLIC (page 314)
RAISE EVENT (page 327)

Chapter 5: Script statements

System functions
status$( ) (page 551)

289

MAKE CURRENT
Script statement: change current form

Syntax

MAKE form_ref CURRENT

Arguments

form_ref

Description

The MAKE CURRENT statement makes the referenced form the current form. VISION
Runtime Manager performs the same actions that occur when the user selects a form.

Specifies the object reference of the current form or a new form.

The make current operation is performed only if form_ref refers to a different form. If
form_ref does not exist, a runtime error occurs. If form_ref is the current form, the
statement has no effect.

Restrictions The MAKE CURRENT statement is invalid in the following sections:

FUNCTION
ON CLEAR TO ADD
ON CLEAR TO FIND
ON CURRENT
ON DESTROY
ON DISMISS FORM

Example

ON DRAG ENTER
ON DRAG LEAVE
ON DRAG START
ON EXIT
ON FIND
WHEN FIELD CHANGES

This example creates a new form, makes it the current form, and then places the cursor
in the last current field of the new form.
CREATE FORM company_form OF CLASS $fcompany
OBJECT_REF INTO company_form
MAKE company_form CURRENT

290

Unify VISION: 4GL Reference

Related
See Unify VISION: Class Reference for information about related attributes and
information methods:
Attributes
OBJECT_ID
TX_MODE_BECOME_CURRENT
TX_MODE_NOT_CURRENT

Methods
ON CURRENT
ON NOT CURRENT

Chapter 5: Script statements

291

METHOD
Declaration: developer-defined method

Syntax

method_type METHOD method_name

( [ [parm_mode][parm_type]parameter[, [parm_mode] [parm_type]parameter] ] ) [;]
[private_variables]
BEGIN

method_body
END [;]

Arguments

method_type

Specifies the type of data returned by the method. Valid types are:
AMOUNT
BINARY
BOOL
DATE
FLOAT
INTEGER

NUMERIC
OBJECT_REF
STRING
TEXT
TIME
VOID

method_name Specifies the name of the method.

parm_mode

Specifies the name of the parameter. Valid modes are:

REF[ERENCE]
RESULT
VALUE

parm_type

Specifies the type of the parameter. Valid types are:

AMOUNT
BINARY
BOOL
DATE
FLOAT
INTEGER
LIST

parameter

MATRIX
NUMERIC
OBJECT_REF
STRING
TEXT
TIME

Specifies the name of a parameter.

private_variables
Specifies a PRIVATE clause that defines local, private variables for
the method.
292

Unify VISION: 4GL Reference

method_body

Description

Specifies VISION 4GL statements that implement the method.

Developer-defined methods are declared using the METHOD statement. Methods are
functions that are declared by a class for the purpose of performing operations on that
particular class.
Methods are invoked by sending messages to an object. A message can be sent using a
SEND MESSAGE statement or the dereference operator.
Developer-defined methods can be declared for any form or service class.
Parameters can be value parameters, reference parameters, or result parameters.
Reference parameters can only be used when the method is invoked using local form
object references. They can not be declared in methods of service classes.
Changing the value of a value parameter within the method does not affect the value
of the associated argument in the calling script. Changing the value of a result
parameter does affect the argument value: VISION Runtime Manager copies the result
parameter value into the associated function argument when the method returns.
The mode of each parameter is specified by parm_mode. If parm_mode is not
specified, VALUE is the default mode.
The data type of each parameter is specified by parm_type. If parm_type is not
specified, the parameter can accept any data type.
Local variables for the method are specified in the private_variables section. Variables
declared in this section are accessible only to statements within the body of the
method.

Restrictions The following statements are invalid in method_body:

DELETE CURRENT RECORD
DISPLAY (without a FOR clause)
EXTERN
INPUT

REJECT OPERATION
REJECT RECORD
RESTART ON FIELD
UPDATE CURRENT RECORD

In addition, the statements that are valid in method_body depend on the method where
the SEND MESSAGE statement was executed. Certain statements are invalid in
method_body if the SEND MESSAGE statement was executed from a global function
or from any of the following methods:
WHEN FIELD CHANGES
ON CLEAR TO ADD
ON CLEAR TO FIND

Chapter 5: Script statements

ON EXIT
ON DESTROY
ON FIND

293

If the SEND MESSAGE statement was executed from the methods listed above, then
following statements are invalid in method_body:
CANCEL FORM
DISMISS FORM
MAKE CURRENT

NEXT ACTION
QUEUE COMMAND

The following statements are invalid when a method is invoked by Unify Object
Broker:
CANCEL FORM
CHANGE CURRENT RECORD TO
CLEAR TO ADD
DELETE CURRENT RECORD
DELETE CURRENT SET
DISABLE ZOOM TO
DISMISS FORM
DISPLAY (without a FOR clause)
ENABLE ZOOM TO

See also

EXTERN
INPUT
MAKE CURRENT
NEXT ACTION
REFRESH CURRENT
REJECT OPERATION
REJECT RECORD
RESTART ON FIELD
UPDATE CURRENT RECORD

Dereference operator (page 127)

Script language
FUNCTION (page 271)
PRIVATE (page 304)
SEND MESSAGE (page 354)

294

Unify VISION: 4GL Reference

NEXT ACTION
Script statement: simulate predefined command

Syntax

NEXT ACTION [ IS ]

{ command_name | RECORD numeric_expression | PAGE object_ref }

Arguments

command_name
The next command that is to be executed. Valid commands are
specified by one of the following keywords:
command_name

Equivalent VISION Runtime Manager command

ADD_UPDATE
ARRANGE
CANCEL_FORM
CASCADE
CLEAR_TO_ADD
CLEAR_TO_FIND
DELETE
DISMISS_FORM
EXIT
FIND
FIRST_RECORD
LAST_RECORD
NEXT_FIELD
NEXT_FORM
NEXT_PAGE
NEXT_RECORD
NEXT_SET
NEXT_TAB
PREVIOUS_FIELD
PREVIOUS_PAGE
PREVIOUS_RECORD
PREVIOUS_SET
PREVIOUS_TAB
RETURN_VALUES
TILE
ZOOM

uv_add_update
uv_arrange
uv_cancel_form
uv_cascade
uv_clear_to_add
uv_clear_to_find
uv_delete
uv_dismiss_form
uv_exit
uv_find
uv_first_record
uv_last_record
uv_next_field
uv_next_form
uv_next_page
uv_next_record
uv_next_set
uv_next_tab
uv_previous_field
uv_previous_page
uv_previous_record
uv_previous_set
uv_previous_tab
uv_return_values
uv_tile
uv_zoom

Chapter 5: Script statements

295

numeric_expression
A defined, non-null expression for the nth record in the selected set. If
the record specified is after the current record, the ON NEXT
RECORD SECTION is executed. If the record specified is before the
current record, the ON PREVIOUS RECORD section is executed.
object_ref

Description

Specifies the object reference of a notebook page. The PAGE clause

specifies that the current page of the notebook is to be changed to the
page identified by object_ref.

The NEXT ACTION statement simulates the execution of a Unify VISION user
command. NEXT ACTION forces execution of a user command without having to rely
on the user to execute the command.
VISION Runtime Manager discontinues execution of the current method at the NEXT
ACTION statement and executes the specified action as if the user had executed the
command associated with the NEXT ACTION statement. If the user-defined method

that executed this statement was called by another method, the calling methods
execution is also ended, as is each method up the call chain. If NEXT ACTION causes
another form to be opened, that form is made current.
For example, when VISION Runtime Manager encounters a NEXT ACTION IS FIND
statement, it performs the following operations:
discontinues execution of the current method at the NEXT ACTION statement
automatically performs a clear-to-find operation and enters find mode
executes the ON CLEAR TO FIND section, if it exists
evaluates the clear-to-find expressions
executes the BEFORE FIND section, if it exists
searches the forms target table with the specified search criteria, creating a
selected set record for each selected target table row
executes the ON FIND section, if one exists, for each selected set record
executes the AFTER FIND section, if one exists

Restrictions The NEXT ACTION statement is invalid in the following VISION 4GL methods:
AFTER VALUES RETURN
FUNCTION
ON CREATE
ON DRAG ENTER
ON DRAG LEAVE
296

ON DRAG START
ON EXIT
ON FIND
WHEN FIELD CHANGES

Unify VISION: 4GL Reference

In addition to the restrictions above, the commands listed in the following table are
also restricted in the methods listed in the second column. For example, NEXT
ACTION IS CLEAR_TO_ADD, in addition to the restrictions above, is also invalid in
the ON CLEAR TO ADD method.
command_name

Additional invalid methods

CLEAR_TO_ADD
CLEAR_TO_FIND
FIND
FIRST_RECORD
LAST_RECORD
NEXT_FORM
NEXT_RECORD
NEXT_SET
PREVIOUS_RECORD
PREVIOUS_SET

ON CLEAR TO ADD
ON CLEAR TO FIND
ON CLEAR TO FIND
ON PREVIOUS RECORD
ON NEXT RECORD
ON NEXT FORM
ON NEXT RECORD
ON NEXT RECORD
ON PREVIOUS RECORD
ON PREVIOUS RECORD

The NEXT ACTION IS RECORD numeric_expression statement is invalid in the ON

NEXT RECORD method.
The NEXT ACTION IS NEXT_FIELD, NEXT ACTION IS NEXT_TAB, NEXT
ACTION IS PREVIOUS_FIELD, and NEXT ACTION IS PREVIOUS_TAB statements
are valid only in the following methods:
AFTER FIELD
BEFORE FIELD
ON FIELD

Warning

Example

Do not include a next action in the method that the action invokes unless you
provide some way to conditionally execute the NEXT ACTION statement.

This NEXT ACTION statement automatically performs a clear-to-add operation when

the user leaves the last field of the last record in the selected set.
IF ( current_record_num$() = current_record_count$() ) THEN
NEXT ACTION IS CLEAR_TO_ADD

See Unify VISION: Class Reference for information about related attributes:
Related
information
Attributes
CLEAR_FIND_EXP

Chapter 5: Script statements

297

OPEN CONNECTION
Script statement: open a database connection

Syntax

OPEN CONNECTION connection_name

Arguments

connection_name
Specifies a string expression that contains the name of a connection
instance to be opened.

Description

The OPEN CONNECTION statement opens a database connection instance. The name
of the database connection instance is specified by connection_name. This connection
instance must have been previously created with the CREATE CONNECTION
statement or match the name of a connection class defined in the DCM file.
Execution of the OPEN CONNECTION statement does not change the current
connection of the object that executed the statement.
The database connection can be closed with the CLOSE CONNECTION statement.

Restrictions The OPEN CONNECTION statement is valid in all VISION 4GL methods.

Example

This example opens the connection instance named s_connection.

OPEN CONNECTION $s_connection;

See also

Script language
CLOSE CONNECTION (page 182)
CREATE CONNECTION (page 189)

DEFINE CONNECTION (page 211)

DESTROY CONNECTION (page 224)

For information about .dcm file format, see Unify VISION: Application Reference.
Related
information
298

Unify VISION: 4GL Reference

POSITION
Clause: form position

Syntax

[ POSITION x, y ]

Arguments

Specifies the pixel value at which to position the form horizontally.

Specifies the pixel value at which to position the form vertically.

Description

The POSITION clause specifies the position of the form relative to the bottom left
corner of the screen. The POSITION clause is valid in the CREATE FORM, CHOOSE
FORM USING, and ENABLE ZOOM TO statements.

Example

In the following example, the position of the inventory form is specified by dividing
the width of the screen by 4.
SET tmpx TO SCREEH_W / 4
SET tmpy TO SCREEH_H / 4
CREATE FORM OF CLASS inventory POSITION tmpx, tmpy;

Related
See Unify VISION: Class Reference for information about related attributes:
information
Attributes
SCREEN_H
SCREEN_W
SCREEN_X
SCREEN_Y

Chapter 5: Script statements

299

PREPARE_SQL
Script statement: prepare dynamic SQL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

PREPARE_SQL SQL_expression INTO SQL_handle_var ;
Shaded portions of the syntax are DBMS dependent.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_expression
A string or text expression that specifies a new SQL statement to be
prepared. Must be supported by the DBMS.
SQL_handle_var

A variable to store the statement as specified by SQL_expression and

the connection specified by connection. If the SQL handle is already
associated with a statement, the previous statement is freed.

Description

The PREPARE_SQL statement orders the DBMS to examine the statement text and
prepare it for execution.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Once a statement is prepared, all SQL handle attributes supported by the DBMS can be
referenced. The IS_PREPARED attribute is set to TRUE after a successful prepare
operation.

300

Unify VISION: 4GL Reference

If the prepared statement does not have any output parameters, the following attributes
continue to have their initial values:
OUTPUT_NAME[ ]
OUTPUT_ACCELL_TYPE[ ]
OUTPUT_DB_COLUMN_TYPE[ ]
OUTPUT_PRECISION[ ]
OUTPUT_SCALE[ ]
OUTPUT_DB_COLUMN_TYPE_CODE[ ]

If the prepared statement does not have any input parameters, then the following
attributes continue to have their initial values:
INPUT_NAME[ ]
INPUT_ACCELL_TYPE[ ]
INPUT_DB_COLUMN_TYPE[ ]
INPUT_PRECISION[ ]
INPUT_SCALE[ ]
INPUT_DB_COLUMN_TYPE_CODE[ ]
SQL handles do not need to be explicitly freed. SQL handles are implicitly freed when
a handle variable goes out of scope or is reused in a PREPARE_SQL statement. To
explicitly free an SQL handle, see the FREE_SQL statement.
SYBASE SQL Server

For SYBASE SQL Server, the SQL handle attributes have invalid values until after the
EXECUTE_SQL statement.

Example

In the following example, after the form is created, the PREPARE_SQL statement
prepares an UPDATE statement that changes all of the first names in the
music_collection table to Jim. The UPDATE statement is stored in the
chng_owner_hndl SQL handle. The EXECUTE_SQL statement executes the UPDATE
SQL statement stored in the chng_owner_hndl SQL handle.
METHOD ON CREATE
PREPARE_SQL UPDATE music_collection SET owner_f_name = \Jim\
INTO chng_owner_hndl;
EXECUTE_SQL $chng_owner_hndl;

Chapter 5: Script statements

301

See also

Script language
EXECUTE_SQL (page 256)
FREE_SQL (page 269)

For information about dynamic SQL, see Writing scripts (page 3).

302

Unify VISION: 4GL Reference

PRINT FORM
Script statement: print current form

Syntax

PRINT FORM [WITH TITLE] [WITH CHOOSER]

Support

The WITH CHOOSER option is supported only on Windows NT.

Description

The PRINT FORM statement prints the current form. Use the WITH TITLE option to
include the form border and form name.
The form is printed on the default printer. On UNIX the default printer is determined
by the PRINTER environment variable. On Windows the default printer is determined
by the printer setup dialog in the Control Panel.
(Windows NT only) Use the WITH CHOOSER option to let the user choose the printer
at runtime from a popup dialog. You can specify WITH TITLE and WITH CHOOSER
in any order.

Restrictions This statement is valid in all VISION 4GL methods. This statement cannot be used in a
global function that is used by a service object.

Example

The following example prints the form after the user clicks on the print button
associated with a developer-defined command, print_form.
COMMAND print_form
BEGIN
DISPLAY NOTICE Print this form? LABELS YES DEFAULT, NO RESULT INTO
print_answer
/* Yes = 0 and No = 1 */
IF print_answer = 0 THEN
BEGIN
PRINT FORM
DISPLAY NOTICE Form Printed LABELS OK RESULT INTO temp
END
END

For information about how to print a form , see Getting started in Unify VISION:
Related
information Designer.

Chapter 5: Script statements

303

PRIVATE
Declaration: private variables

Syntax

PRIVATE

variable_description [ [ , variable_description ] . . . ]
For a scalar variable, variable_description has the following syntax:
[ AMBIGUOUS ] variable_name [ data_type ]
For a one-dimensional array variable_description has the following syntax:
[ AMBIGUOUS ] LIST array

[ [ROWS] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ] } ]

For a two-dimensional array, variable_description has the following syntax:
[ AMBIGUOUS ] MATRIX array
[ [ ROWS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]},
[ COLUMNS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]}]

Support

Support for this feature is DBMS dependent.

INFORMIX

The data_type options of the PRIVATE declaration are supported for

INFORMIX with the enhancements described on page 306.

ORACLE

The data_type options of the PRIVATE declaration are supported for

ORACLE with the enhancements described on page 308.

SYBASE SQL

The data_type options of the PRIVATE declaration are

supported for SYBASE SQL Server with the
enhancements described on page 309.

Server

Unify DataServer

The DATE and TIME data_type options of the PRIVATE declaration

are not supported for Unify DataServer. See also page 309.
304

Unify VISION: 4GL Reference

Arguments

variable_name Specifies an identifier for the variable. The variable name can have up
to 44 characters. These characters include both uppercase and
lowercase letters (a-z, A-Z), numeric characters (0-9), and the
underscore character (_). The first character of the variable name must
be a letter. A dollar sign ($) prefix is optional. Because system
variables are suffixed by a dollar sign, the variable name must not be
terminated by the dollar sign ($) character.
data_type

For a target table column, specifies the Unify VISION data type:
AMOUNT
BINARY
BOOL
DATE
FLOAT
INTEGER

NUMERIC
OBJECT_REF
STRING
TEXT
TIME

In a FORM script, data_type specifies the data type to which the

variable is to be converted. Data type conversion compatibility is
DBMS dependent, as described under Description.

Description

array

the name of a one-dimensional (LIST) or two-dimensional (MATRIX)

array.

num_expr

a numeric expression for delimiting the lower or upper bounds of an

array.

The PRIVATE statement is an optional statement for any class definition, local
function, method, or global function. The PRIVATE statement declares private local
variables for any object of that class, function, or method.
Private local variables for a class are created when an object of that class is created.
These local variables are created before the constructor for that class, ON CREATE, is
invoked.
Private local variables for a class are destroyed when the object that contains the
variables is destroyed. The local variables are destroyed after the destructor for the
class, ON DESTROY, is invoked.
Private local variables for a method or function are created when the method or
function is invoked. These local variables are destroyed when the method or function
returns.

Chapter 5: Script statements

305

Access to private local variables by name for a class is restricted. These variables are
accessible by name only from methods and local functions declared within that class.
Access to private local variables declared within a function or method are accessible
by name only from within that method or function.
Private variables can be passed as parameters outside of the class, function, or method
in which they are declared.
INFORMIX

The PRIVATE clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, INFORMIX DATE column
types are converted to the DATE data type; in a FORM header, the STRING data type
can be used to convert an INFORMIX DATE column type to STRING. By default,
INFORMIX DATETIME YEAR TO DAY column types are converted to the DATE data
type, DATETIME HOUR TO MINUTE column types are converted to the TIME data
type, and other DATETIME column types are converted to the STRING data type
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert an INFORMIX TEXT
column type to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert INFORMIX
CHARACTER(n) or VARCHAR column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
INFORMIX FLOAT, DOUBLE PRECISION[(n)], SMALL FLOAT,
DEC[IMAL][(m,[n])], NUMERIC[(m,[n])], or MONEY[(m,[n])] column type to
NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert INFORMIX FLOAT,
DOUBLE PRECISION[(n)], SMALL FLOAT, DEC[IMAL][(m,[n])],
NUMERIC[(m,[n])], INT[EGER], or SMALLINT column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert INFORMIX INT[EGER],
SMALLINT, or MONEY[(m,[n])] column type to FLOAT.
306

Unify VISION: 4GL Reference

By default, INFORMIX DATETIME YEAR TO DAY column types are converted to the
DATE data type, DATETIME HOUR TO MINUTE column types are converted to the
TIME data type, and other DATETIME column types are converted to the STRING
data type.
INGRES

The PRIVATE clause cannot be used to override the default data type conversion for a
target variable that obtains data from a date-time column. INGRES date-time column
types are converted to the STRING data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert an INGRES text or
varchar(n) column type to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert INGRES char(n) or c
column type to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
INGRES float4, real, float, float8, double precision, or money column type to
NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert INGRES integer,
integer4, smallint, integer2, integer1, float4, real, float, float8, or double precision
column type to NUMERIC.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert INGRES integer, integer4,
smallint, integer2, integer1, or money column type to FLOAT.
At runtime, the target variable types that are defined in the PUBLIC clause must match
the data types defined in VISION Designer. You cannot specify the data type option in
a PRIVATE clause that is in a global or local function, or for a nontarget variable.
ODBC
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert ODBC
SQL_LONGVARCHAR column type to STRING.
Chapter 5: Script statements

307

The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert ODBC SQL_CHAR or
SQL_VARCHAR column type to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert ODBC
SQL_NUMERIC(X,2), SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC,
SQL_NUMERIC(X,1), SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column
type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert ODBC
SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, SQL_SMALLINT,
SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC, SQL_NUMERIC(X,1),
SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert ODBC
SQL_NUMERIC(X,2), SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, or
SQL_SMALLINT column type to FLOAT.
ORACLE
The PRIVATE clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, ORACLE DATE column
types are converted to the DATE data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert ORACLE LONG, CHAR,
or VARCHAR2 column types to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert ORACLE CHAR or
VARCHAR2 column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
ORACLE FLOAT or NUMBER(X,Y) (where Y is not 0 or 2) column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert ORACLE FLOAT,
NUMBER(X,Y) (where Y is not 2), DECIMAL, INTEGER, or SMALLINT column type
to AMOUNT.
308

Unify VISION: 4GL Reference

The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert ORACLE NUMBER(X,2),
NUMBER(X,0), DECIMAL, INTEGER, or SMALLINT column type to FLOAT.
SYBASE SQL Server
The PRIVATE clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, SYBASE SQL Server
datetime column types are converted to the DATE data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert SYBASE SQL Server
datetime column types to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert SYBASE SQL Server
char(n), varchar(n), nchar(n), nvarchar(n) column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
SYBASE SQL Server money, smallmoney, float, real, decimal(X,Y), or numeric(X,Y)
(where Y > 0) column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert SYBASE SQL
Server float, real, decimal(X,Y), numeric(X,Y) (where Y > 0), int, tinyint, smallint,
decimal(X,0), or numeric(X,0) column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be NUMERIC; in
a FLOAT header, the FLOAT data type can be used to convert SYBASE SQL Server
money, smallmoney, int, tinyint, smallint, decimal(X,0), or numeric(X,0) column
type to FLOAT.
Data type conversions are not allowed in stored procedures.
Unify DataServer
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert Unify DataServer TEXT
column types to STRING.
Chapter 5: Script statements

309

The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert Unify DataServer STRING
column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
Unify DataServer AMOUNT, HUGE AMOUNT, or FLOAT column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert Unify DataServer
FLOAT, NUMERIC(9), SMALLINT, or INTEGER column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert Unify DataServer
AMOUNT, HUGE AMOUNT, NUMERIC(9), SMALLINT, or INTEGER column type to
FLOAT.

Example

The following clause declares a one-dimensional array with a subscript range of seven
elements from 0 to 6.
PRIVATE LIST days_of_the_week[0 TO 6]

The next clause declares a two-dimensional array with an upper bound of three for
both rows and columns.
PRIVATE MATRIX tic_tac_toe[1 TO 3,1 TO 3]

The next example declares a two-dimensional array called songs that has an estimated
number of rows and columns. This declaration is useful for dynamic SQL when you do
not know how many columns are to be selected from a table during runtime:
PRIVATE MATRIX songs[1 TO UNKNOWN ESTIMATING 40, 0 to UNKNOWN ESTIMATING 51]

The next example declares a two-dimensional array called company_records having

nine columns in each row. When records are selected, approximately 100 records are
expected.
PRIVATE company_records[1 TO UNKNOWN ESTIMATING 100,1 TO NUM_COLUMNS]
. . .
METHOD ON CREATE
SET NUM_COLUMNS TO 9

This example declares multiple target variables and specifies their data types.
FORM orders
PRIVATE order_date DATE, ship_date TIME, index

310

Unify VISION: 4GL Reference

The following example converts a database date-time column to a STRING field and
uses the field in various database statements. The dttm_tbl database table contains a
date-time column named dttm_field. An integer column i is also used.
FORM sample
/* Define the target datetime column as a string field */
PUBLIC dttm_field STRING;
FIELD dummy
METHOD AFTER FIELD
/* Initialize temporary variables */
SET dttm_value TO 12/3/1992 10:10:11.996AM;
SET ndttm_value TO 12/3/1992 10:10:12.996AM;
SET dttm_field TO something
/* Insert data into database */
INSERT INTO dttm_tbl VALUES ( 110, $dttm_value );
SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110
EXECUTING
BEGIN
DISPLAY $dttm_field FOR FYI_MESSAGE WAIT;
END
/* Update the datetime value in the database */
UPDATE dttm_tbl SET dttm_field = $ndttm_value
WHERE dttm_field = $dttm_value;
/* Determine whether column has been updated */
SET dttm_field TO SELECT dttm_field FROM dttm_tbl
WHERE dttm_field = $ndttm_value
EXECUTING
BEGIN
DISPLAY $dttm_field FOR FYI_MESSAGE WAIT;
END
/* Delete the inserted row from the database */
DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

SYBASE SQL

The following example script converts a database date-time column to a Unify VISION
Server STRING field and uses the field in various database statements. The SYBASE SQL
Server dttm_tbl database table contains a datetime column named dttm_field. An
integer column i is also used.
FORM sample
/* Define the target datetime column as a string field */
PRIVATE dttm_field STRING;

Chapter 5: Script statements

311

FIELD dummy
METHOD AFTER FIELD
/* Initialize temporary variables */
SET dttm_value TO 12/3/1992 10:10:11.996AM;
SET ndttm_value TO 12/3/1992 10:10:12.996AM;
SET dttm_field TO something
/* Insert dat into database */
INSERT INTO dttm_tbl VALUES ( 110, $dttm_value );
SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110
EXECUTING
BEGIN
DISPLAY $dttm_field FOR FYI_MESSAGE WAIT;
END
/* Update the datetime value in the database */
UPDATE dttm_tbl SET dttm_field = $ndttm_value
WHERE dttm_field = $dttm_value;
/* Determine whether column has been updated */
SET dttm_field TO SELECT dttm_field FROM dttm_tbl
WHERE dttm_field = $ndttm_value
EXECUTING
BEGIN
DISPLAY $dttm_field FOR FYI_MESSAGE WAIT;
END
/* Delete the inserted row from the database */
DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

See also

312

Script language
EVENT (page 252)
PUBLIC (page 314)

Unify VISION: 4GL Reference

Related
See Unify VISION: Class Reference for information about the following attributes:
information
COLUMN_BOUNDED
COLUMN_LOWER_BOUNDS
COLUMN_UPPER_BOUNDS
DIMENSION
LIST_INDEX

LIST_LOWER_BOUNDS
LIST_UPPER_BOUNDS
ROW_BOUNDED
ROW_LOWER_BOUNDS
ROW_UPPER_BOUNDS

For information about LIST, and MATRIX see Identifiers in Unify VISION:
Application Reference.

Chapter 5: Script statements

313

PUBLIC
Declarations

Syntax

DBMS dependent

PUBLIC variable_description [ [, variable_description] . . . ]

variable_description
For a scalar variable, variable_description has the following syntax:
[ AMBIGUOUS ] variable_name [data_type]
For a one-dimensional array variable_description has the following syntax:
[ AMBIGUOUS ] LIST array

[ [ROWS] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ] } ]

For a business event, variable_description has the following syntax:
EVENT event_name ( [parmlist] )

For a two-dimensional array, variable_description has the following syntax:

[ AMBIGUOUS ] MATRIX array
[ [ ROWS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]},
[ COLUMNS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]}]
Shaded portions of the syntax are DBMS dependent.

Support

Support for date_type is DBMS dependent.

INFORMIX

The data_type options of the PUBLIC declaration are supported for

INFORMIX with the enhancements described on page 316.

ORACLE

The data_type options of the PUBLIC declaration are supported for

ORACLE with the enhancements described on page 319.

SYBASE SQL

The data_type options of the PUBLIC declaration are

supported for SYBASE SQL Server with the
enhancements described on page 319.

Server

Unify DataServer

The DATE and TIME data_type options of the PUBLIC declaration

are not supported for Unify DataServer. See also page 320.
314

Unify VISION: 4GL Reference

Arguments

variable_name An identifier for the variable. The variable name can have up to 44
characters. These characters include both uppercase and lowercase
letters (a-z, A-Z), numeric characters (0-9), and the underscore
character (_). The first character of the variable name must be a letter.
A dollar sign ($) prefix is optional. Because system variables are
suffixed by a dollar sign, the variable name must not be terminated by
the dollar sign ($) character.
data_type

For a target table column, specifies the Unify VISION data type:
AMOUNT
BINARY
BOOL
DATE
DATETIME
FLOAT

INTEGER
NUMERIC
OBJECT_REF
STRING
TEXT
TIME

In the PUBLIC section of a script, data_type specifies the data type to

which the variable is to be converted. Data type conversion
compatibility is DBMS dependent, as described under Description.

Description

array

The name of a one-dimensional (LIST) or two-dimensional

(MATRIX) array.

num_expr

A numeric expression for delimiting the lower or upper bounds of an

array.

parmlist

See EVENT.

The PUBLIC statement is an optional statement for any class definition. The PUBLIC
statement declares public local variables.
A PUBLIC variable that has the same name as a target table column is treated as a
target variable regardless of the class in which it is defined.
Public local variables for a class are created when an object of that class is created.
The local variables are created before the constructor for the class, ON CREATE, is
invoked.
Public local variables are destroyed when the object containing the variables is
destroyed. The local variables are destroyed after the destructor for the class, ON
DESTROY, is invoked.

Chapter 5: Script statements

315

Public local variables for a global function are created when that function is invoked.
The variables are destroyed when the function returns.
The variables are accessible by name from any method or local function of the class or
any derived class.
Public local variables are also accessible by name from any other object. Access to a
variable can be achieved through the use of the object_name:variable_name syntax, or
through the use of the dereference operator and the object ID for the object, through
normal parameter passing, or through resolution at runtime of AMBIGUOUS variables.
The AMBIGUOUS clause specifies a variable to be ambiguous.
Array declarations
You can specify the lower and upper subscript bounds for each dimension of an array.
The bounds of the array must be enclosed by brackets[ ]. LIST indicates a
one-dimensional array. MATRIX indicates a two-dimensional array. The bounds of an
array can be specified by any expression that is equivalent to an integer. To optimize
memory usage, you can use a variable to dynamically declare the bounds when a form
is activated.
The lower bounds of an array can be any positive or negative integer, up to the
maximum allowed by your operating system for long integers. By default, the lower
bound is 1.
For an unbounded array, use the keyword UNKNOWN to indicate that the upper limit
of a row is unknown or unlimited. You can specify an estimated upper bound by using
the phrase UNKNOWN ESTIMATING numeric expression. By default, if the
estimating clause is omitted, the estimated upper bound is 100.
To verify whether an array has an upper bound, use the ROW_BOUNDED and
COLUMN_BOUNDED attributes. To determine the type of an array, use the
DIMENSION attribute.
INFORMIX

The PUBLIC clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, INFORMIX DATE column
types are converted to the DATE data type; in a FORM header, the STRING data type
can be used to convert an INFORMIX DATE column type to STRING. By default,
INFORMIX DATETIME YEAR TO DAY column types are converted to the DATE data
type, DATETIME HOUR TO MINUTE column types are converted to the TIME data
type, and other DATETIME column types are converted to the STRING data type
316

Unify VISION: 4GL Reference

The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert an INFORMIX TEXT
column type to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert INFORMIX
CHARACTER(n) or VARCHAR column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
INFORMIX FLOAT, DOUBLE PRECISION[(n)], SMALL FLOAT,
DEC[IMAL][(m,[n])], NUMERIC[(m,[n])], or MONEY[(m,[n])] column type to
NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert INFORMIX FLOAT,
DOUBLE PRECISION[(n)], SMALL FLOAT, DEC[IMAL][(m,[n])],
NUMERIC[(m,[n])], INT[EGER], or SMALLINT column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert INFORMIX INT[EGER],
SMALLINT, or MONEY[(m,[n])] column type to FLOAT.
By default, INFORMIX DATETIME YEAR TO DAY column types are converted to the
DATE data type, DATETIME HOUR TO MINUTE column types are converted to the
TIME data type, and other DATETIME column types are converted to the STRING
data type.
INGRES

The PUBLIC clause cannot be used to override the default data type conversion for a
target variable that obtains data from a date-time column. INGRES date-time column
types are converted to the STRING data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert an INGRES text or
varchar(n) column type to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert INGRES char(n) or c
column type to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
INGRES float4, real, float, float8, double precision, or money column type to
NUMERIC.
Chapter 5: Script statements

317

The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert INGRES integer,
integer4, smallint, integer2, integer1, float4, real, float, float8, or double precision
column type to NUMERIC.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert INGRES integer, integer4,
smallint, integer2, integer1, or money column type to FLOAT.
At runtime, the target variable types that are defined in the PUBLIC clause must match
the data types defined in VISION Designer. You cannot specify the data type option in
a PUBLIC clause that is in a global or local function, or for a nontarget variable.

ODBC
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert ODBC
SQL_LONGVARCHAR column type to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert ODBC SQL_CHAR or
SQL_VARCHAR column type to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert ODBC
SQL_NUMERIC(X,2), SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC,
SQL_NUMERIC(X,1), SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column
type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert ODBC
SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, SQL_SMALLINT,
SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC, SQL_NUMERIC(X,1),
SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert ODBC
SQL_NUMERIC(X,2), SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, or
SQL_SMALLINT column type to FLOAT.
318

Unify VISION: 4GL Reference

ORACLE
The PUBLIC clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, ORACLE DATE column
types are converted to the DATE data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert ORACLE LONG, CHAR,
or VARCHAR2 column types to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert ORACLE CHAR or
VARCHAR2 column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
ORACLE FLOAT or NUMBER(X,Y) (where Y is not 0 or 2) column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert ORACLE FLOAT,
NUMBER(X,Y) (where Y is not 2), DECIMAL, INTEGER, or SMALLINT column type
to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert ORACLE NUMBER(X,2),
NUMBER(X,0), DECIMAL, INTEGER, or SMALLINT column type to FLOAT.
SYBASE SQL Server
The PUBLIC clause can be used to override the default data type conversion for a
target variable that obtains data from a date-time column. The DATE keyword
specifies that the target variable data type is to be DATE. The TIME keyword specifies
that the target variable data type is to be TIME. By default, SYBASE SQL Server
datetime column types are converted to the DATE data type.
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert SYBASE SQL Server
datetime column types to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert SYBASE SQL Server
char(n), varchar(n), nchar(n), nvarchar(n) column types to TEXT.
Chapter 5: Script statements

319

The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
SYBASE SQL Server money, smallmoney, float, real, decimal(X,Y), or numeric(X,Y)
(where Y > 0) column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert SYBASE SQL
Server float, real, decimal(X,Y), numeric(X,Y) (where Y > 0), int, tinyint, smallint,
decimal(X,0), or numeric(X,0) column type to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be NUMERIC; in
a FLOAT header, the FLOAT data type can be used to convert SYBASE SQL Server
money, smallmoney, int, tinyint, smallint, decimal(X,0), or numeric(X,0) column
type to FLOAT.
Unify DataServer
The STRING keyword specifies that the target variable data type is to be STRING; in a
FORM header, the STRING data type can be used to convert Unify DataServer TEXT
column types to STRING.
The TEXT keyword specifies that the target variable data type is to be TEXT; in a
FORM header, the TEXT data type can be used to convert Unify DataServer STRING
column types to TEXT.
The NUMERIC keyword specifies that the target variable data type is to be
NUMERIC; in a FORM header, the NUMERIC data type can be used to convert
Unify DataServer AMOUNT, HUGE AMOUNT, or FLOAT column type to NUMERIC.
The AMOUNT keyword specifies that the target variable data type is to be AMOUNT;
in a FORM header, the AMOUNT data type can be used to convert Unify DataServer
FLOAT, NUMERIC(9), SMALLINT, or INTEGER column types to AMOUNT.
The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a
FORM header, the FLOAT data type can be used to convert Unify DataServer
AMOUNT, HUGE AMOUNT, NUMERIC(9), SMALLINT, or INTEGER column types
to FLOAT.

Example

The following clause declares a one-dimensional array with a subscript range of seven
elements from 0 to 6.
PUBLIC LIST days_of_the_week[0 TO 6]

320

Unify VISION: 4GL Reference

The next clause declares a two-dimensional array with an upper bound of three for
both rows and columns.
PUBLIC MATRIX tic_tac_toe[1 TO 3,1 TO 3]

The next example declares a two-dimensional array called songs that has an estimated
number of rows and columns. This declaration is useful for dynamic SQL when you do
not know how many columns are to be selected from a table during runtime:
PUBLIC MATRIX songs[1 TO UNKNOWN ESTIMATING 40, 0 to UNKNOWN ESTIMATING 51]

The next example declares a two-dimensional array called company_records having

nine columns in each row. When records are selected, approximately 100 records are
expected.
PUBLIC company_records[1 TO UNKNOWN ESTIMATING 100,1 TO NUM_COLUMNS]
. . .
METHOD ON CREATE
SET NUM_COLUMNS TO 9

This example declares multiple target variables and specifies their data types.
FORM orders
PUBLIC order_date DATE, ship_date TIME, index

The following example converts a database date-time column to a STRING field and
uses the field in various database statements. The dttm_tbl database table contains a
date-time column named dttm_field. An integer column i is also used.
FORM sample
/* Define the target datetime column as a string field */
PUBLIC dttm_field STRING;
FIELD dummy
METHOD AFTER FIELD
/* Initialize temporary variables */
SET dttm_value TO 12/3/1992 10:10:11.996AM;
SET ndttm_value TO 12/3/1992 10:10:12.996AM;
SET dttm_field TO something
/* Insert data into database */
INSERT INTO dttm_tbl VALUES ( 110, $dttm_value );
SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110
EXECUTING
BEGIN
DISPLAY $dttm_field FOR FYI_MESSAGE WAIT;
END

Chapter 5: Script statements

321

/* Update the datetime value in the database */

UPDATE dttm_tbl SET dttm_field = $ndttm_value
WHERE dttm_field = $dttm_value;
/* Determine whether column has been updated */
SET sale_id TO SELECT dttm_field FROM dttm_tbl
WHERE dttm_field = $ndttm_value
EXECUTING
BEGIN
DISPLAY $sale_id FOR FYI_MESSAGE WAIT;
END
/* Delete the inserted row from the database */
DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

See also

Script language
EVENT (page 252)
PRIVATE (page 304)
RAISE EVENT (page 327)

For information about LIST and MATRIX see Identifiers in Unify VISION:
Related
information Application Reference.

322

Unify VISION: 4GL Reference

QUEUE COMMAND
Script statement: queued command execution

Syntax

QUEUE COMMAND { command_name | defined_command }

Arguments

command_name
The keyword for a VISION Runtime Manager command. The
following table lists valid keywords and their equivalent VISION
Runtime Manager commands.
command_name

Equivalent VISION Runtime Manager command

ADD_UPDATE
ARRANGE
CANCEL_FORM
CASCADE
CHOOSE _FORM
CLEAR_TO_ADD
CLEAR_TO_FIND
DELETE
DISMISS_FORM
EXIT
FIND
FIRST_RECORD
LAST_RECORD
NEXT_FIELD
NEXT_FORM
NEXT_PAGE
NEXT_RECORD
NEXT_SET
NEXT_TAB
PREVIOUS_FIELD
PREVIOUS_PAGE
PREVIOUS_RECORD
PREVIOUS_SET
PREVIOUS_TAB
RECALL_ERROR_MESSAGE
RETURN_VALUES
TILE
ZOOM

uv_add_update
uv_arrange
uv_cancel_form
uv_cascade
none
uv_clear_to_add
uv_clear_to_find
uv_delete
uv_dismiss_form
uv_exit
uv_find
uv_first_record
uv_last_record
uv_next_field
uv_next_form

Chapter 5: Script statements

uv_next_page

uv_next_record
uv_next_set
uv_next_tab
uv_previous_field
uv_previous_page

uv_previous_record
uv_previous_set
uv_previous_tab
uv_recall_error_message
uv_return_values
uv_tile
uv_zoom
323

defined_command
The name of a developer-defined user command. This command must
be defined in the COMMAND method.

Description

The QUEUE COMMAND statement places a request to execute the specified command
in the pending command queue. The queued command will be executed when Unify
VISION is about to retrieve user input. Queued commands are executed in the current
context. In most cases, the current context is the form associated with the script where
this statement appears.
If a QUEUE COMMAND cannot be executed because the command cannot be found
on the current form, no error is given and all of the remaining queued commands are
lost.

Restrictions This statement can be executed within any method, or from a local or global function.
At least one field on the form must have the FOCUSABLE attribute set to TRUE.
Otherwise, the next form operation is automatically executed instead of the command
specified in the QUEUE COMMAND statement. This statement cannot be used in a
global function that is used by a service object.

Example

This statement executes a developer-defined command named mycommand.

QUEUE COMMAND mycommand

This statement executes the VISION Runtime Manager uv_zoom command.

QUEUE COMMAND ZOOM

See also

Script language
CLEAR COMMAND QUEUE (page 179)

324

Unify VISION: 4GL Reference

System functions
last_command$( ) (page 502)
last_command_name$( ) (page 504)

See Unify VISION: Class Reference for information about related classes and methods:
Related
information
Methods
BEFORE RECORD
ON EXIT
Classes
COMMAND

Chapter 5: Script statements

325

RAISE
Script statement: raise specified object to front

Syntax

RAISE object_ref

Arguments

object_ref

Description

The RAISE statement displays the specified object in front of any other overlapping
objects. If the specified object is a primary form, it is raised to the top of the stacking
order of windows on the screen.

A variable that specifies an object reference.

Restrictions The RAISE statement can be used in all VISION 4GL methods.

Example

This example displays the form identified by fcompany_form_instance.

RAISE $fcompany_form_instance

326

Unify VISION: 4GL Reference

RAISE EVENT
Script statement: publish business event

Syntax

RAISE EVENT event_name [ USING (expression[[, expression] . . . ) ]

Arguments

event_name

Specifies the name of the business event to be raised.

expression

Specifies the parameters to be passed to each business event handler

installed by objects subscribing to the event.

Description

The RAISE EVENT statement performs a publish or raise operation on the event
identified by event_name. event_name must be an EVENT declared in the PUBLIC
section of the class in which the RAISE EVENT statement occurs.
When an event is raised, an asynchronous message is sent to each subscribing object,
thereby notifying those objects of the occurrence of the event.
Objects can subscribe to an event by installing a business event handler with the
INSTALL statement.

The EVENT definition can optionally specify parameters to be sent when the event is
raised. Since the messages sent to the subscribers are one way, the mode of each of the
parameters can only be specified as VALUE.
The number of parameters as well as their respective data types specified in expression
must match the parameters specified in the event definition.
Use the status$( ) system function to determine the success of a RAISE EVENT
statement. In failure cases, use the dap_ti_errcode$( ), dap_td_errcode_i$( ),
dap_td_errcnt$( ), and dap_4gl_errcode$( ) system functions to determine the exact
cause of the failure.
An unsuccessful attempt to deliver a message to a subscribing object is treated as
nonfatal and is ignored. The application raising the event will not be notified of any
such errors.
Chapter 5: Script statements

327

Restrictions The RAISE EVENT statement can be used in all VISION 4GL methods.

See also
Script language
DEINSTALL (page 213)
EVENT (page 252)
INSTALL (page 285)
PUBLIC (page 314)

System functions
dap_4gl_errcode$( ) (page 433)
dap_td_count$( ) (page 434)
dap_td_errcode_i$( ) (page 435)
dap_ti_errcode$( ) (page 438)
status$( ) (page 551)

See Unify VISION: Class Reference for information about related classes:
Related
information
Form
Service

328

Unify VISION: 4GL Reference

REFRESH CURRENT
Script statement: refresh field values

Syntax

REFRESH CURRENT { RECORD | SET }

Description

The REFRESH CURRENT RECORD statement retrieves the values of the current
record from the associated database table row. The REFRESH CURRENT SET
statement retrieves the values of all records in the current selected set from the
associated database table rows. If an associated table row has been deleted from the
target table, the affected record is deleted from the selected set and the statements
refresh the record values regardless of consistency mode and the current values of the
fields. The fields are updated to reflect the current values in the database. Additionally,
any WHEN FIELD CHANGES methods are executed for every field in the record
because they are all re-retrieved from the database.
When a form uses the no consistency mode for retrieving records, no locks of any type
are requested when the selected set is displayed. Therefore, during the time that the
user views the records in the selected set, another form within the application, user, or
process can modify the values in the associated target table rows. You can use the
REFRESH CURRENT statement to modify the values displayed to match those
currently stored in the database.
The REFRESH CURRENT statement is valid only in add/update/delete mode and for
forms that have a target table. It is not valid in find mode or for forms that have no
target table. If REFRESH CURRENT is used with a form under set consistency, it has
no effect. If the REFRESH CURRENT RECORD statement is used with a form under
record consistency, it has no effect. The REFRESH CURRENT SET statement can be
used to refresh records for a form under record consistency.
You can use the status$( ) system function to test the success of the REFRESH
CURRENT statement. A successful refresh operation returns a value of 0 (SS_NORM).
Failure of this statement returns one of these possible values:
5
12
45
60
121

Chapter 5: Script statements

SS_NOCUR
SS_NOTUP
SS_LMOUT
SS_NORID
SS_RMOD
329

If the current record is deleted, another record in the selected set becomes current and
a next record operation is executed. If the selected set contains only one record, when
that record is deleted, a clear-to-add operation is executed and any statements
remaining in the current method are not executed.
If the current record has no unique identifier in the database row, all column values
must be used to identify the associated row. If the value of any column in the
associated row has been changed, the row cannot be identified; therefore, the current
record will be deleted, and status$( ) will return a value of SS_NOTUP.

Restrictions This statement is invalid in the following methods:

AFTER FIND
BEFORE FIND
FUNCTION (global only)
ON FIND
ON CREATE

Example

This example uses a global function named ChangeState( ) to update a table. Because
the function updates columns other than the column passed in, a form that calls this
function must refresh the current record.
/*
* Updates the State for a given customer. Also changes the
* Region, based on the state. Any form calling this function
* should refresh its data.
*
* Requires function RegionFromState().
*/
EXTERN SCRIPT STRING FUNCTION RegionFromState(TheState);
NUMERIC FUNCTION ChangeState( CustomerID, NewState )
/* LOCAL definitions */
PRIVATE NewRegion;
BEGIN
SET NewRegion TO RegionFromState($NewState);
UPDATE customers set Region = $NewRegion, State = $NewState
where CustomerID = $CustomerID;
RETURN(status$());
END; /* ChangeState() */

330

Unify VISION: 4GL Reference

If the State field on the Customers form has been changed, the script calls the
ChangeState( ) function to update other column values in the target table. Because the
update operation can change the values of the associated table row, the current record
must be refreshed.
#include sscodes.h
EXTERN SCRIPT NUMERIC FUNCTION ChangeState(CustID, NewState);
FORM CLASS Customers
METHOD AFTER UPDATE
IF $StateHasChanged THEN
BEGIN
SET $tResult TO ChangeState($CustomerID, $State);
IF $tResult <> SS_NORM THEN
DISPLAY NOTICE Error + to_string$($tResult) +
updating the Customers State/Region information.\n +
Try again later or contact the DBA!
LABELS Bummer! DEFAULT RESULT INTO $tDummy;
ELSE
REFRESH CURRENT RECORD;/* ChangeState() may have changed it */
END

See also

System functions
status$( ) (page 551)

For information about record consistency and locking, see Managing transactions and
Related
information locks in Unify VISION: Developing an Application.

Chapter 5: Script statements

331

REFRESH DISPLAY
Script statement: refresh video display

Syntax

REFRESH DISPLAY

Description

The REFRESH DISPLAY statement causes the screen to be immediately redrawn. Use
this statement to refresh the screen during execution of long sections of VISION 4GL
statements that would otherwise prevent the screen from being redrawn until execution
finished.
Using this statement in a loop can impact performance.

Restrictions This statement can be executed in any method or from a local or global function.
However, REFRESH DISPLAY is not valid in service object or in a function called by
a service object.

See also

332

Writing scripts (page 3) and Script functions (page 57).

Unify VISION: 4GL Reference

REJECT OPERATION
Script statement: reject user command

Syntax

REJECT OPERATION

Description

The REJECT OPERATION statement prevents the user from performing a specific
user operation.
The table on the next page shows the methods that can include the REJECT
OPERATION statement. For each method, the table also lists the user operation that is
rejected.
VISION Runtime Manager continues executing any remaining statements in the
method after the REJECT OPERATION statement completes. In addition, any AFTER
method (AFTER ADD, AFTER DELETE, AFTER FIND, AFTER UPDATE) that
corresponds to a BEFORE method is also executed.

For example, if REJECT OPERATION is in the BEFORE ADD method, VISION

Runtime Manager executes all statements in BEFORE ADD and all statements in the
AFTER ADD statement as well.
If REJECT OPERATION is in the BEFORE FIND method, VISION Runtime Manager
executes all statements in BEFORE FIND and AFTER FIND but does not execute the
ON FIND method.
If an AFTER method is not to be executed when a REJECT OPERATION is used in
the BEFORE method, you can use a BOOL reject flag and test this reject flag in
the AFTER method. If the reject flag is TRUE, the REJECT OPERATION occurred
and the AFTER statements are not executed. Otherwise, the AFTER statements are
executed.

Chapter 5: Script statements

333

Method

Rejected operation

BEFORE FIND

uv_find

BEFORE ADD

uv_add_update

BEFORE UPDATE

uv_add_update

BEFORE DELETE

uv_delete

ON CANCEL FORM

uv_cancel_form

ON CLEAR TO FIND

uv_clear_to_find

ON DISMISS FORM

uv_dismiss_form

ON EXIT

uv_exit

ON NEXT FORM

uv_next_form

ON NEXT RECORD

uv_last_record
uv_next_record
uv_next_set

ON PREVIOUS RECORD

uv_first_record
uv_previous_record
uv_previous_set

ON RETURN VALUES

uv_return_values

ON ZOOM

uv_zoom

Restrictions The REJECT OPERATION statement is valid only in the following methods:

BEFORE ADD
BEFORE DELETE
BEFORE FIND
BEFORE UPDATE
ON CANCEL FORM
ON CLEAR TO FIND
ON DISMISS FORM
334

ON EXIT
ON NEXT FORM
ON NEXT RECORD
ON PREVIOUS RECORD
ON RETURN VALUES
ON ZOOM

Unify VISION: 4GL Reference

Example

This script sample prevents anyone with a user name other than Alexander from
executing an add operation. If the user named Alexander adds a new row, the
AFTER ADD method displays a status message. If some other user tries to add a row,
the status message is not displayed even though the AFTER ADD method is executed.
METHOD BEFORE ADD
SET $valid_add TO TRUE
IF ( user_name$() <> Alexander ) THEN
BEGIN
REJECT OPERATION
SET $valid_add TO FALSE
END
METHOD AFTER ADD
IF $valid_add THEN
DISPLAY New row added to the Database
FOR FYI_MESSAGE WAIT

See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
BEFORE ADD
BEFORE DELETE
BEFORE FIND
BEFORE UPDATE
ON CANCEL FORM
ON CLEAR TO FIND
ON DISMISS FORM
ON EXIT
ON NEXT FORM
ON NEXT RECORD
ON PREVIOUS RECORD
ON ZOOM

Chapter 5: Script statements

335

REJECT RECORD
Script statement: record selection

Syntax

REJECT RECORD

Description

The REJECT RECORD statement discards a target table row found during an
interactive find operation.
Within the ON FIND method, you can process each target table row as it is selected.
You can use the REJECT RECORD statement to prevent a record from being added to
the selected set. The rejected row does not have a selected set record created and
cannot be viewed by the user. If the selected row is not rejected, VISION Runtime
Manager creates a selected set record for the row.
Under set consistency, all rows in the selected set are read-locked; the row that
corresponds to the rejected record is not unlocked.

Restrictions This statement is valid only in an ON FIND method.

Example

This script sample uses the REJECT RECORD statement to prevent the database row
for Smithers from being added to the selected set. Because it is not in the selected
set, this row cannot be selected, viewed, or updated.
METHOD ON FIND
IF ( emp_last_name = Smithers ) THEN
REJECT RECORD

Related
See for information about related methods:
information Unify VISION: Class Reference
Methods
AFTER FIND
BEFORE FIND
ON FIND

336

Unify VISION: 4GL Reference

REPEAT
Script statement: execute statement list

Syntax

REPEAT statement_list UNTIL logical_expression

Arguments

statement_list One or more VISION 4GL statements. If there is more than one
statement, do not begin and end the statements with the keywords
BEGIN and END.
logical_expression
Any Unify VISION BOOL expression. The expression is evaluated at
the end of each loop iteration. The statement_list is executed until this
expression becomes TRUE.

Description

The REPEAT statement executes statement_list until logical_expression is TRUE.

VISION Runtime Manager executes statement_list as long as the logical_expression is
FALSE.
To execute the REPEAT statement, VISION Runtime Manager first executes
statement_list. Next, it evaluates logical_expression to determine whether to
re-execute statement_list. This expression determines the number of times that the
statement body is executed.
If logical_expression evaluates to TRUE, the REPEAT loop exits. If logical_expression
evaluates to FALSE, statement_list is re-executed. If logical_expression contains a null
value, it evaluates to FALSE.
If logical_expression contains a variable, this variable must have an initial value
assigned before the UNTIL clause of the REPEAT statement so that the
logical_expression can be evaluated the first time.
VISION Runtime Manager continues the process of executing the statement_list and
testing the logical_expression until logical_expression is TRUE. When the
logical_expression is TRUE, the REPEAT loop ends.

Chapter 5: Script statements

337

Because VISION Runtime Manager evaluates the logical expression in a REPEAT

statement after each execution of the statement body, the REPEAT statement is always
executed at least once.

Restrictions The REPEAT statement can be used in all VISION 4GL methods.

Example

This REPEAT statement displays the value 100 in the current form field, then the
values 99, 98, and so on until the value 50 is displayed; the loop is then exited.
SET index TO 100
REPEAT
DISPLAY index
SET index TO index 1
UNTIL index < 50

See also

338

Script language
BREAK (page 168)
CONTINUE (page 187)

FOR (page 267)

WHILE (page 393)

Unify VISION: 4GL Reference

RESIZE
Script statement: resize unbounded array

Syntax

RESIZE
{
LIST array TO num_expr [ ROWS ]
|
MATRIX array TO num_expr { ROWS | COLUMNS }
[, num_expr { ROWS | COLUMNS } }

Arguments

array

The array name as declared in a PUBLIC or PRIVATE declaration.

num_expr

A numeric expression for the number of elements in the array.

Description

The RESIZE statement changes the size of an unbounded dimension of an array to the
new size specified by num_expr. New elements are initialized with a value of
UNDEFINED. Use this statement to reset the upper bounds of an array to the actual
number of elements in the array.
Bounded dimensions and the lower bound of an array cannot be resized.

Restrictions This statement is valid in all VISION 4GL methods.

Example

In this example, two arrays supply values to a list box. The RESIZE statement
removes all rows from both the food and labels arrays.
PRIVATE
LIST food [1 TO UNKNOWN],
LIST box_labels [1 TO UNKNOWN]
SET food[1] TO baked potato
SET food[2] TO fries
SET box_labels[1] TO low fat
SET box_labels[2] TO high fat
set_scrolling_list$(alistbox, box_labels, food)
RESIZE LIST food TO 0 ROWS
RESIZE LIST box_labels TO 0 ROWS

See also

PUBLIC (page 314)

Chapter 5: Script statements

339

RESTART ON FIELD
Script statement: re-execute user input on field

Syntax

RESTART [ ON ] FIELD

Description

The RESTART ON FIELD statement causes VISION Runtime Manager to begin

execution of the ON FIELD method again. RESTART ON FIELD lets the user enter
input again by restarting the ON FIELD method.
When VISION Runtime Manager encounters a RESTART ON FIELD statement, it
discontinues execution of the current ON FIELD method. VISION Runtime Manager
then returns to the beginning of the ON FIELD method and begins execution.
Any statements in the current method that follow the RESTART ON FIELD statement
are not executed after the RESTART ON FIELD statement is executed.
You can test information entered by the user in the ON FIELD method. You use the
INPUT statement to stop for user input. If the input is not correct, you can require that
the user reenter it by including the RESTART ON FIELD statement in ON FIELD. You
can use the DISPLAY statement to display an appropriate error message explaining
why the input must be reentered.

Restrictions The RESTART ON FIELD statement is valid only in an ON FIELD or an ON DATA

ACCEPT method.

Example

This script sample receives input from the field sc_name_field. After the user enters a
value, the input value is passed to a user function, namechk( ).
FIELD sc_name_field
METHOD ON FIELD
INPUT
IF (NOT namechk($sc_name_field)) THEN
BEGIN
DISPLAY
Letters, blanks, apostrophes, hyphens only
FOR FYI_MESSAGE WAIT
RESTART ON FIELD
END

340

Unify VISION: 4GL Reference

If namechk( ) returns FALSE, the input is not valid. An error message is then
displayed in the fyi_message system information field, and RESTART ON FIELD
restarts the ON FIELD method.

See also

Script language
INPUT (page 281)

See Unify VISION: Class Reference for information about related methods and
Related
information attributes:
Methods
ON FIELD

Attributes
EDIT_ACTION

Chapter 5: Script statements

341

RETRIEVE
Script statement: read external file

Syntax

RETRIEVE [ TEXT | BINARY ] variable_name FROM FILE string_expression

Arguments

variable_name
The name of the variable that is to contain the data retrieved from
string_expression.
string_expression
The directory search path and file name of the data file that the data is
to be retrieved from. The expression can be either a string constant or
string variable.

Description

The RETRIEVE statement reads the contents of BINARY or TEXT files. If the file does
not exist or cannot be opened or read, the variable value is set to UNDEFINED.
Use the status$( ) system function to verify the results of the RETRIEVE statement:
If the file does not exist, the status is SS_NOFIL.
If the file cannot be opened, the status is SS_FLACS.
An error results in these cases:
The argument used as the string_expression is not a STRING expression.
The variable is not a general, TEXT, or BINARY variable.
The result is undefined or null.
Windows
Each carriage return/line-feed sequence is changed to a line-feed character.

Restrictions The RETRIEVE statement can be used in all VISION 4GL methods.
342

Unify VISION: 4GL Reference

Example

This example retrieves a memorandum contained in the memo file and places it into a
local text variable named $memo.
RETRIEVE TEXT $memo FROM FILE memo

See also

Script language
STORE (page 373)

Chapter 5: Script statements

343

RETURN
Script statement: terminate execution of a function

Syntax

RETURN [ ( return_value ) ]

Arguments

return_value

The value to return to the calling function. This value can be an

expression, a variable or a constant. The value must have the same
data type as the functions return value, defined in the functions
FUNCTION statement.
For a SCRIPT_ERROR function, specify TRUE to suppress the error
window. Specify FALSE to permit display of the standard error
window. If the RETURN bool clause is omitted, the default value is
TRUE.

Description

The RETURN statement terminates execution of a VISION 4GL function. When

VISION Runtime Manager reaches the RETURN statement, it evaluates any result
parameters and exits from the function.
You can use this statement anywhere within a VISION 4GL function. You can include
more than one RETURN statement in a single function.
For functions that do not return values, the use of the RETURN statement in the
function body is optional. If control passes to the end of the function body without
encountering a RETURN statement, VISION Runtime Manager performs the RETURN
statement automatically and does not return a value.
For functions that do return values, you must use this statement to return the value. To
return values, include the return value within parentheses after the RETURN keyword.
If control passes to the end of the function body without encountering a RETURN
statement, VISION Runtime Manager returns an undefined value.
Make sure that the data type of the value being returned matches the functions return
value defined in the FUNCTION statement.

344

Unify VISION: 4GL Reference

Restrictions The RETURN statement is valid only in a FUNCTION method.

Example

This script sample defines a local function called get_netpay( ). This local function
uses the RETURN statement to return the AMOUNT value of net_salary.
LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)
PRIVATE the_taxrate, net_pay
BEGIN
SET the_taxrate TO
SELECT tax_rate FROM rates
WHERE lower_sal <= $gross_salary
AND upper_sal >= $gross_salary
SET taxes TO (gross_salary * the_taxrate)
SET net_salary TO gross_salary taxes
RETURN (net_salary)
END

See also

Script language
FUNCTION (page 271)

Chapter 5: Script statements

345

REVOKE
SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

REVOKE SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Any of the keywords or statements permitted by the DBMS within a

REVOKE command.

Description

When VISION Runtime Manager encounters the REVOKE statement, it prepares the
statement for processing by the database. Because this statement is executed by the
DBMS, it must conform to the syntax requirements of the DBMS; extensions provided
by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.

346

Unify VISION: 4GL Reference

Restrictions The REVOKE statement can be used in all VISION 4GL methods.

Example

This REVOKE statement drops SELECT privileges on the emp_salary column of the
emp_table from all PUBLIC users.
REVOKE SELECT (emp_salary) ON TABLE emp_table FROM PUBLIC;

See also

Script language
GRANT (page 277)

Related
For complete syntax information, see the documentation provided by the DBMS
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

347

ROLLBACK WORK
Script statement: abort current transaction

Syntax

[ USING [ CONNECTION ] connection ]

ROLLBACK WORK [ DEMOTING LOCKS ]

Support

Support for this feature is DBMS dependent.

DBMS dependent

The DEMOTING LOCKS clause is supported for Unify DataServer only; it has no
effect on any other DBMS.
ODBC

The ROLLBACK WORK statement has no effect.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

Supported. The optional DEMOTING LOCKS clause retains all

records of the selected set but demotes exclusive locks to shared
locks, regardless of the form consistency level.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
348

Unify VISION: 4GL Reference

Description

The ROLLBACK WORK statement causes the database to abort the current
transaction and begin a new one. The DBMS handles backing out all uncommitted
database operations, interactive and non-interactive, in the current transaction.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Transaction rollback is possible only if the database has transaction logging and
logging is enabled.
When the current transaction is aborted, the following events occur:
All current locks are released.
All uncommitted update, delete, and insert operations are undone.
The user does not see any changes on the screen when ROLLBACK WORK is
executed. The current form is still displayed along with any data on the form.
If the aborted transaction contains a selected set, all records in the selected set no
longer have locks, even if the records still display on the form.
If the form uses the Browse feature, the current selected set may have been only a
subset of all matching records. In this case, the full selected set is lost when the
transaction aborts. The user cannot use uv_next_set or uv_next_record to see
additional subsets of the selected set.
To regain the locked selected set, use NEXT ACTION IS CLEAR_TO_FIND to clear
the form. If necessary you can recreate the selected set with NEXT ACTION IS FIND.
After the transaction is aborted, VISION Runtime Manager continues to execute any
VISION 4GL statements that follow the ROLLBACK WORK statement within the
method.

Restrictions The ROLLBACK WORK statement is invalid in the ON FIND method and the
EXECUTING clause.
Chapter 5: Script statements

349

Example

This example attempts an INSERT after the user inputs the form field doinsert. If the
database insert fails, the transaction is aborted and execution returns to the previous
form.
FIELD doinsert
METHOD AFTER FIELD
INSERT INTO stock (st_number, st_description, st_unit_price)
VALUES ($snum, $sdesc, $price);
IF (status$() <> SS_NORM) THEN
BEGIN
ROLLBACK WORK
NEXT ACTION IS DISMISS_FORM
END

See also

Script language
BEGIN WORK (page 165)
COMMIT WORK (page 184)
UNLOCK (page 378)

System functions
tx_mode$( ) (page 594)

Related
For information about transaction control, see Managing transactions and locks in
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

350

Unify VISION: 4GL Reference

SELECT
SQL DML statement

Syntax

DBMS dependent

[ SET_statement ]
[ USING [ CONNECTION ] connection ]
SELECT SQL_clause
{ EXECUTING_clause
|;}

Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

SET_statement A VISION 4GL SET statement.

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

The clauses permitted by the DBMS within a SELECT command.

EXECUTING_clause
A VISION 4GL EXECUTING clause.

Description

The SELECT statement initiates a non-interactive find operation.

Unify VISION variables can be used in the selection list but must be prefixed by a
dollar sign ($) and used as part of an expression.

Chapter 5: Script statements

351

The set of rows to be selected is determined by a WHERE clause. As the DBMS

searches the tables, the logical_expression for each row is evaluated and the value is
returned. If the logical_expression evaluates to TRUE for a row, SELECT selects the
row. If the logical_expression evaluates to FALSE or to a null value, the row is not
selected.
If no WHERE clause is specified, the first row in the table is selected. To select all
table rows, you must include an EXECUTING clause with SELECT.
If the SELECT statement includes a locking clause, locks are requested for all selected
rows.
Use the Unify VISION status$( ) system function to test the success of a SELECT
statement.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
If an EXECUTING clause is not included, the SELECT statement must be terminated
by a semicolon (;).

INFORMIX
A WHERE clause cannot include a column having the TEXT or BYTE data type.

ORACLE
A WHERE clause cannot include a column having the LONG or LONG RAW data type.

Restrictions The SELECT statement can be used in all VISION 4GL methods.
The ROLLBACK WORK statement is invalid within the EXECUTING clause unless
ROLLBACK WORK DEMOTING LOCKS is specified.
352

Unify VISION: 4GL Reference

Example

This SELECT statement selects the first row in the employee table. The
emp_last_name value is then assigned to the Unify VISION variable one_name.
SET one_name TO
SELECT employee.emp_last_name
FROM employee
WHERE emp_no = $emp_no;

See also

Script language
EXECUTING (page 259)
SET (page 359)

Related
For information about multiple database connections, see Getting started in Unify
information VISION: Developing an Application.
See Unify VISION: Application Reference for information about this related external
preference:
DBFETCHCOUNT

See Unify VISION: Class Reference for information about this related attribute:
FIND_COUNT

Chapter 5: Script statements

353

SEND MESSAGE
Script statement: message handler execution

Syntax

SEND [ ONEWAY ] [ ASYNC[HRONOUS] ] MESSAGE method_name

TO obj_ref_exp
[ USING (expression [, expression . . . ] ) ]
[ IDENTIFIED BY message_handle ]
[ RETURNING return_variable ]

Arguments

method_name The name of the method to be invoked on the object specified by

obj_ref_exp. To use a variable so that the method name can be
determined at runtime, use the format $method_name, for example,
$method_idx. Otherwise, method_name is interpreted as a literal.
obj_ref_exp

An expression that evaluates to an OBJECT_REF data type that

identifies the object to which the message is directed.

expression

Specifies the actual parameters to be passed to the specified method.

message_handle
If the IDENTIFIED BY clause is specified, message_handle receives
the value of the message handle associated with the message request.
The message handle can later be used for checking the status of the
message and for performing a WAIT FOR operation on a message
request.
return_variable
Receives the return value of the method invocation, if any. If
obj_ref_exp is an ActiveX object, return_variable can be an array.

Description

The SEND MESSAGE statement sends a message to an object to invoke the specified
method on the specified object.
Any object of a class derived from the service or form foundation classes can receive
messages. obj_ref_exp must be a reference to an object of one of these classes. The
object can be located within the same partition as the object sending the message or
within a different partition on the same or different systems connected via a network.
The object can be replicated or non-replicated.

354

Unify VISION: 4GL Reference

The method to be invoked is identified by method_name. The method must be defined

as a developer-defined method in the declaration for the class.
The USING clause specifies a comma-separated list of parameters to be passed to the
method. The number of parameters as well as their types must match the
corresponding method declaration in the class script where the message is declared.
The RETURNING clause specifies a variable for receiving the value returned by the
method invocation. If the RETURNING clause is specified, the type of method_name
cannot be VOID.
The ONEWAY clause specifies that the message is to be sent without an
acknowledgement message. One-way messages cannot return any result parameters or
a method result.
The ASYNCHRONOUS clause specifies that the message is to be sent asynchronously.
When asynchronous messaging is specified, the SEND MESSAGE operation returns
immediately upon sending the message. The sending partition does not wait for the
invocation of the method to be completed.
The IDENTIFIED BY clause specifies a variable for receiving the value of the message
handle associated with a message request. The message handle can subsequently be
used for checking the status of the message and for waiting for the completion of the
message using the WAIT FOR statement. The message handle continues to refer to this
specific message request until the variable is either destroyed or the variable is reused
in a subsequent SEND MESSAGE statement.
If the ASYNCHRONOUS clause is specified, the assignment of result parameters and
the method return value is not performed until a WAIT FOR statement is executed
using the associated message handle.
If the ASYNCHRONOUS clause is specified and the method to be invoked has
RESULT parameters or a non-VOID method return value, the IDENTIFIED BY clause
must also be specified.
If the ASYNCHRONOUS clause is specified and obj_ref_exp refers to an object that is
implemented within the same partition as the object sending the message, the
invocation of the method on the destination object can occur before the successful
completion of the WAIT FOR statement on the associated message handle. A partition
should not rely on occurrence before the WAIT FOR statement is executed.
If a partition requires notification of the completion of an asynchronous method
invocation, the application must perform a WAIT FOR operation that specifies the
message handle returned by the SEND MESSAGE.
Chapter 5: Script statements

355

Use the message handle specified in the IDENTIFIED clause to check the status of the
message. The message handle contains attributes that are used specifically for error
processing. This is the preferred method for error processing.
If the IDENTIFIED clause was not specified, use the status$( ) system function to
determine the success of a SEND MESSAGE statement. In failure cases, use the
dap_ti_errcode$( ), dap_td_errcode_i$( ), dap_td_errcnt$( ), and
dap_4gl_errcode$( ) system functions to determine the exact cause of a failure.
If obj_ref_exp refers to a replication group and the initial attempt to deliver a message
to a member of the group is unsuccessful, Unify VISION automatically attempts to
deliver the message to another member of the group. The SEND MESSAGE statement
can fail in these cases only if an attempt to deliver the message to every member of the
group has failed.
In many cases, parameters are used as out only by the method. If these parameters are
of type LIST or MATRIX, before executing SEND MESSAGE the sender of the
message should resize the parameter to 0 rows and 0 columns. This can greatly reduce
the amount of data being sent in a message, thus increasing performance and reducing
network traffic.
Messages can be sent using two different mechanisms: by using Unify Object Broker
or by using direct, local messaging. Direct local messaging is used when the object
reference specified for the destination of the message request is a local object
reference. When a nonlocal object reference is specified, Unify Object Broker is used
to deliver the message. Nonlocal object references are obtained from service objects,
system management objects, any object reference obtained from a UONameService
object, or any object reference being passed in as a parameter from another partition.
When a local object reference is specified and either the ONEWAY or
ASYNCHRONOUS clause is used, Unify Object Broker is used to deliver the message.

Restrictions SEND MESSAGE is invalid in the following VISION 4GL methods:

ON DRAG ENTER
ON DRAG LEAVE
ON DRAG START

If one or more parameters of a method are declared with the REFERENCE clause,
obj_ref_exp must be a local object reference (obj_ref_exp:TRANSPORT must be
LOCAL). Local object references are valid for objects of the form class only.
356

Unify VISION: 4GL Reference

Example

In this example, the SEND MESSAGE statement notifies the subform that the user has
modified the account order (ORDACCKEY) field. The value parameter in the USING
clause corresponds to the parameter of the METHOD NewKey in the $SubformBillTo
subform.
FIELD ORDACCKEY
METHOD BEFORE FIELD
SET $SaveKey TO $ORDACCKEY;
METHOD AFTER FIELD
if $SaveKey <> $ORDACCKEY THEN
SEND MESSAGE NewKey TO $SubformBillTo USING ($ORDACCKEY);

In this example, the application locates the service object named "invoice_srv" using
the resolve method provided by the global name service. It then sends a message to
"invoice_srv" specifying the execution of the method "invoice_fax" on
"invoice_srv".
SET $nmsrv_objref TO acquire_global_uvns$();
SEND MESSAGE resolve TO $nmsrv_objref USING (invoice_srv, $inv_objref);
SEND MESSAGE invoice_fax to $inv_objref USING ($invoice_id);

See also

Script language
WAIT FOR (page 391)

System functions
acquire_global_uvns$( ) (page 405)
acquire_local_uvns$( ) (page 406)
dap_4gl_errcode$( ) (page 433)
dap_td_count$( ) (page 434)
dap_td_errcode_i$( ) (page 435)
dap_ti_errcode$( ) (page 438)
status$( ) (page 551)

Related
For information about building and managing a partitioned application, see Unify
information VISION: Developing an Application.
See Unify VISION: Class Reference for information about related classes and methods:
Form::OBJECT_ID
GENERAL_DATA::TRANSPORT
MSG_HANDLE
Service
Service::OBJECT_ID
Service::TRANSPORT
UONameService
UONameService::bind( )
UONameService::resolve( )

Chapter 5: Script statements

357

SEND SUPER
Script statement: invoke a method

Syntax

SEND SUPER [ USING ( expression [ , expression . . . ] ) ] [ RETURNING variable ]

Arguments

expression

Specifies a parameter to be passed to the method invocation.

variable

Receives the value of the method result, if any.

Description

The SEND SUPER statement invokes an inherited method.

When a derived class is defined, the derived class can override one or more methods
defined in the base class. When an overridden method is invoked, the behavior defined
for that method in the base class is not automatically invoked. The inherited behavior
is invoked only by the execution of a SEND SUPER statement in the overridden
method.
If the method declaration contains a parameter list, the parameters are automatically
passed to the method in the base class. The optional USING clause overrides the
default parameters.
If the method that is being invoked is a non-VOID method, the RETURNING clause
can be used to receive the result of the method invocation.

Restrictions The SEND SUPER statement is invalid in the following VISION 4GL methods:
ON CREATE
ON DESTROY

See also

358

Script language
METHOD (page 292)

Unify VISION: 4GL Reference

SET
Script statement: assign variable or attribute value

Syntax

DBMS dependent

SET

{
|

{ variable | attribute } TO expression

{variable_list | list_var | matrix_var }
TO { SELECT_statement | row_valued_function_call | EXEC_SQL_statement }
[ EXECUTING_clause ] }

[;]

Support

The row_valued_function_call argument is valid only for a stored procedure where the
FUNCTION type is specified as ROW_VALUED.

Arguments

variable

Any valid Unify VISION variable, including an array element. The

variable is set to the value of the expression. The expression and the
variable must be type compatible. variable can be an array if
expression dereferences an ActiveX object method that returns an
array or an attribute of an ActiveX object that is an array.

variable_list

One or more Unify VISION variable names separated by commas.

Each variable is assigned the value of the corresponding column in the
SELECT_statement, row_valued_function_call, or EXEC_SQL
statement clause. If fewer variables are specified than the number of
SELECT list elements, a runtime error occurs. If you specify more
variables than the number of SELECT list elements, the unused
variables are set to UNDEFINED.
(INFORMIX only/SYBASE SQL Server only) When setting target
variables, field variables, and target field variables to values returned
by a ROW_VALUED stored procedure call, the data type of each
variable must be compatible with the data type of the corresponding
database column. For general variables, the variables take the types of
the values returned by the stored procedure call.

list_var

Chapter 5: Script statements

A one-dimensional array (type LIST) to store the output from the

SELECT statement. Only the first row of any selected rows is
retained. Each element in the LIST is set to its corresponding select
list element. If the number of select list elements is greater than the
359

maximum size of the array, the status$( ) system function returns

SS_NUMCOLS. If the array is unbounded, the SELECT expression is
always successful, unless there is not enough memory. If the SET
statement runs out of memory while the first row is selected, all of the
array elements are set to undefined before status$( ) system function
returns SS_NOMEM.
matrix_var

A two-dimensional array to store the output from the SELECT

statement. An EXECUTING clause is prohibited in the
EXECUTE_SQL statement for matrix variables.
The number of columns in the array corresponds to the number of
select list elements in the SQL statement. The number of rows
corresponds to the number of rows selected. Each row in the array
corresponds to a selected row.
Size errors can occur when the bounds of the matrix are too small. If
the number of columns returned by the SELECT declaration is larger
than the COLUMNS specified in the LOCAL statement, no records are
returned and the status$( ) system function returns SS_NUMCOLS. If
the number of rows returned by the SELECT declaration is larger than
the ROWS specified in the LOCAL declaration, records are returned
only up to the limits declared; records that exceed the limit are not
included and status$( ) system function returns SS_NUMROWS. If the
matrix includes more columns than the number of select expressions,
the unused columns are set to UNDEFINED.
Size errors can occur when the matrix is unbounded. If insufficient
memory is available to contain the selected rows, the array is resized
to [0,0] and status$( ) system function is set to SS_NOMEM.

attribute

Any Unify VISION attribute (for example, form attribute, field

attribute, or command attribute) that is settable in a script.
When the SET statement is executed to set a command attribute, the
command must be defined in the current form. If the command is not
defined in the current form, a runtime error is displayed.

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

360

Unify VISION: 4GL Reference

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file. If you are
using an SQL handle, do not specify a connection.
expression

Any valid Unify VISION expression. The SET statement assigns

expression to the variable or attribute. expression can be an array if
variable dereferences an ActiveX object method that returns an array
or an attribute of an ActiveX object that is an array.

SELECT_statement

Any valid SQL SELECT statement. The SELECT statement can

include locking clauses and an EXECUTING block.
row_valued_function_call
(SYBASE SQL Server only) The name of a ROW_VALUED stored
procedure, in the following format:
[USING [ CONNECTION ] connection ]
function_name([parameter_list])
The function_name must be the name of a stored procedure that is
declared as ROW_VALUED.
The parameter_list is one or more input parameters, separated by
commas, that are passed to the stored procedure. If a default value for
an input parameter has been specified in the stored procedure
definition, you can indicate that you want to use the default value by
replacing the parameter name with the keyword UNDEFINED:
function_name(UNDEFINED)
EXEC_SQL_statement

Any valid EXECUTE_SQL statement that executes a SELECT

statement.
EXECUTING_clause
A VISION 4GL EXECUTING clause.

Description

The SET statement is the VISION 4GL assignment statement. This statement can set
variables of all Unify VISION data types. It can also set the Unify VISION variable and
form attributes.

Chapter 5: Script statements

361

If variable is a field variable, the displayed value changes when the variables value
changes. If variable is a target variable, the new target column value is not added to
the database until the current record is added or updated.
If variable is a general variable, the variables data type is determined when you
assign the first value to the variable. To change the data type of a general variable, you
must first set the variable to UNDEFINED and then assign the value of the new data
type. You cannot assign the NULL constant to an undefined general variable.
If the SELECT statement finds no matching database rows, the value of variable is set
to UNDEFINED.
You cannot change the data type of a field, target, or target field variable.
The SET statement is not only a statement; it is also an expression. Unlike most
VISION 4GL statements, the SET statement has a value. The value of the SET
expression is the value of variable or attribute. You can use the SET statement
wherever a Unify VISION expression is valid.

Warning

Because the SET statement is also an expression, make sure that the placement of SET
within your statements is unambiguous. Do not use the SET statement after a
statement that ends with an optional expression unless you terminate the previous
statement with a semicolon (;). In most statements, the use of a semicolon (;) is
optional. However, it is required in this case to distinguish the statements. If the
previous statement is not terminated, the SET statement is interpreted as an expression
belonging to the previous statement.
The SET statement cannot be used within a database SQL statement.
ActiveX objects
variable can be set to an array for an ActiveX object method that returns an array or
an attribute of an ActiveX object that is an array where the return results are of type
LIST or MATRIX. The variable destination array is resized to 0 or 0,0. The return
values in the ActiveX array are assigned to the destination array starting at the lower
bounds of each array. The destination array type must match the type returned by the
method.
If the destination array is bounded and the return value array is larger than the bounds,
status$( ) returns SS_NUMCOLS or SS_NUMROWS.

362

Unify VISION: 4GL Reference

If the destination array is unbounded, the assignment is successful, provided that

sufficient memory is available. If memory is insufficient, the destination array is
resized to 0 or 0,0, and status$( ) returns SS_NOMEM.
If a MATRIX destination array includes more columns that the number of columns in
the returned array, the unused columns are set to UNDEFINED. If the number of
columns in the destination array is less than the number of columns in the returned
array, status$( ) returns SS_NUMCOLS.
INFORMIX
SYBASE SQL Server
A ROW_VALUED stored procedure can contain one or more SELECT statements.

Restrictions This statement can be used in all VISION 4GL methods.

Example

The following paragraphs show examples of some of the ways you can use the SET
statement to set variables, attributes, expressions, and so on.
Selecting variable values
This SET statement selects the first row in the employee table. The emp_last_name
value is then assigned to the Unify VISION variable one_name.
SET one_name TO
SELECT employee.emp_last_name
FROM employee

The next example shows how to display the current form fields value and then select
the first name from employee where last_name is Smith and assign it to var1. You
must end the DISPLAY statement with the statement terminator.
DISPLAY;
SET var1 TO
SELECT emp_first_name FROM employee
WHERE emp_last_name = Smith

Setting variable attributes

The next SET example sets the UPDATEABLE field attribute of the field variable
screen_field to FALSE. Setting the UPDATEABLE field attribute to FALSE means that
the user cannot edit the fields value.
SET screen_field:UPDATEABLE TO FALSE

Chapter 5: Script statements

363

The next SET statement assigns the value TRUE to the BOOL variable valid_add.
SET valid_add TO TRUE

The next SET statement assigns the value 0 to the three variables, var1, var2, and
var3.
SET var1 TO SET var2 TO SET var3 TO 0

Setting clear-to-find expressions

To set the initial search criteria for the NUMERIC target field variable inumber (on the
form inventory) to inventory numbers in the range 100 to 500 (inclusive):
SET inventory:inumber:CLEAR_FIND_EXP TO 100 => 500

To set the initial search criteria for the AMOUNT target field variable price (on the
form inventory) to all prices greater than $25,525.50:
SET inventory:price:CLEAR_FIND_EXP TO 25,525.50 =>

To set the initial search criteria for the NUMERIC target field variable count (on the
form inventory) to inventory items with counts less than ten (10):
SET inventory:count:CLEAR_FIND_EXP TO => 10

To set the initial search criteria for the NUMERIC target field variable location (on the
form inventory) to the location code of the current warehouse:
SET inventory:location:CLEAR_FIND_EXP TO $warehouse

To negate search criteria, use the NOT metacharacter in the first position, for example:
SET inventory:location:CLEAR_FIND_EXP TO !warehouse

In any position other than the first, this character always represents a literal. To search
for a literal character in the first position, override the NOT metacharacter by
enclosing it with brackets: [!].
The NOT metacharacter is valid only in an equality test; in a range of values, the NOT
metacharacter and brackets are treated as literal values. The NOT metacharacter is
defined by the NOT_METACH external preference.
Setting clear-to-add expressions
The following examples show a variety of ways to set clear-to-add expressions.
364

Unify VISION: 4GL Reference

To set the initial value for the NUMERIC target field variable order_time (on the
inventory form) to 4 weeks:
SET inventory:order_time:CLEAR_ADD_EXP TO 4

To set the initial value for the NUMERIC target field variable location (on the
inventory form) to the location code to indicate the current warehouse:
SET inventory:location:CLEAR_ADD_EXP TO $warehouse

Setting variables with system functions

The next SET statement assigns the null value to the NUMERIC variable total.
Because assigning the NULL constant to an undefined general variable is not valid,
this SET statement converts the NULL constant to a NUMERIC null value with the
to_num$( ) type-conversion function.
SET total TO to_num$(NULL)

Setting array values

This example sets the initial value of a field array cell:
SET array2[5]:CLEAR_ADD_EXP TO $base + 5
FOR (SET $index TO 1; $index <= 100; SET $index TO $index + 1)
INSERT INTO stock(st_number) VALUES ($index);

Using SET with control statements

The next example adds 100 database rows to the table stock. The SET statement
assigns the initial value and the re-initialized value to the FOR loops control variable,
index.
FOR (SET $index TO 1; $index <= 100; SET $index TO $index + 1)
INSERT INTO stock(st_number) VALUES ($index);

Setting command attributes

The following SET statement enables a developer-defined command named userls:
SET userls:AUD_ACTION TO ENABLED

Chapter 5: Script statements

365

To set attributes of predefined commands, use the command name without its uv_
prefix, for example:
SET ADD_UPDATE:AUD_ACTION TO DISABLED

To set the EDIT_ACTION attribute for a selected set scrollbar object, specify
RECORD for the attribute argument, for example:
SET RECORD:EDIT_ACTION TO ACCEPT

Using a stored procedure

SYBASE SQL

The following example calls the emp_info( ) stored procedure to select information
Server from the employee table for the employee having the employee number specified in
emp_num:
Call to emp_info( ) stored procedure
SET $dept, $lname, $fname, $title TO emp_info($emp_num)

$emp_num parameter
passed to emp_info( )
stored procedure

emp_info( ) stored
procedure definition

366

CREATE PROC emp_info @emp_num int

AS SELECT dept, lastname, firstname, title
FROM employee
WHERE emp_num = @emp_num

Unify VISION: 4GL Reference

The following example shows a call to a stored procedure named sp_calc( ), in which
default input parameter values are defined. If either of the input parameters passed
from Unify VISION to the stored procedure is UNDEFINED, sp_calc( ) uses the default
value defined in the stored procedure definition.

Call to stored
procedure

. . .
INPUT
IF ($nbr2 < 0) THEN
SET $Num1, $Num2 TO sp_calc (18, UNDEFINED)
EXECUTING
. . .

If $nbr2 is
LESS THAN
0, use default
value defined
in sp_calc( )

Default input values

sp_calc( ) stored
procedure definition

CREATE PROC sp_calc @nbr1 int = 10

@nbr2 int = 20
AS . . .

In the following example, the procedures first SELECT returns one column value, the
second SELECT returns three column values and two compute values, and the third
SELECT returns five column values. Therefore, the SET statement must contain five
variables.
SYBASE SQL Server stored procedure

First SELECT
Second SELECT
COMPUTE clause
Third SELECT

CREATE PROC stored_proc AS . . .

Needs 1 variable
SELECT col1
FROM table1
...
Needs 3 variables
SELECT col1, col2, col3
FROM table2
Needs 2 variables
ORDER BY col1
COMPUTE SUM(col3), AVG(col3)
Needs 5 variables
...
SELECT col1, col2, col3, col4, col5
FROM table3
...
Maximum number of variables = 5
SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()
EXECUTING
...
SET statement

Chapter 5: Script statements

367

Using SET with dynamic SQL

The following example accepts input from a user. The user types the name of the artist
into the text1 field. The SELECT statement retrieves the matching titles and stores the
titles in the title_names variable. The DISPLAY statement displays the name of the
titles into a notice box. If multiple records are found, the DISPLAY statement displays
a notice box for each record.
FIELD text1 /* Text Field (STRING) */
METHOD ON FIELD
INPUT
IF $text1 IS NOT NULL THEN
BEGIN
SET $title_names TO EXECUTE_SQL SELECT title FROM music_collection \
WHERE artist = ? USING $text1
EXECUTING
BEGIN
DISPLAY The titles are + $title_names for FYI_MESSAGE WAIT;
END
SET $text1 to NULL
NEXT ACTION IS PREVIOUS_FIELD
END

System functions
sp_compute$( ) (page 536)
sp_return$( ) (page 538)
sp_select$( ) (page 541)

See also

Script language
EXECUTING (page 259)
EXTERN (page 263)
SELECT (page 351)

Related
information

See Unify VISION: Class Reference for information about these related attributes:
Attributes
ADD_ALLOWED
CLEAR_ADD_EXP
CLEAR_FIND_EXP

For more information about data type conversions, see Data types in Unify
VISION: Application Reference.

368

Unify VISION: 4GL Reference

SLOCK
Script statement: read-lock request

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

SLOCK [schema_name.]table_name [ WHERE logical_expression ] ;
Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

Supported with the restrictions described on page 371.

ODBC

The SLOCK statement has no effect.

ORACLE

Supported with the restrictions described on page 371.

SYBASE SQL

Supported as described.

Server
Unify DataServer

Supported as described.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
Chapter 5: Script statements

369

schema_name The name of a database schema. If not specified, the users default
schema is used.
table_name

The name of the database table to be read-locked or of the table

containing the rows to be read-locked.

logical_expression
A DBMS boolean expression. The expression is evaluated to
determine which database rows are issued a read lock request.

Description

An SLOCK statement issues a read-lock request on a database object. This object can
be either a table or a set of database rows. A read lock allows a transaction to read an
object with the assurance that another transaction cannot update it while the lock is
held on that object. When a table or row has a read lock, the transaction can read the
locked object, but it cannot modify it. Other transactions can obtain read access on the
locked object. You need not use locking statements when selecting records with the
SELECT statement.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Use Unify VISION locking statements (SLOCK, XLOCK, UNLOCK) in a multiuser
application to protect selected rows and tables from modification. A transaction has
read access on any object it has read-locked and both read and write access on any
object it has write-locked.
An object can be read without being locked.
Using the WHERE clause
The set of rows for which to issue the lock request is determined by the WHERE
clause. SLOCK requests a read lock for all rows that satisfy the logical_expression in
the WHERE clause. This logical_expression must include a test on at least one column
name from the table table_name.
If the logical_expression evaluates to TRUE for a selected row, SLOCK issues a read
lock request for the row. If the logical_expression evaluates to FALSE or to a null
value for a selected row, SLOCK does not issue a read-lock request for the row.
If the WHERE clause is omitted, SLOCK requests a read lock on the entire table,
table_name.

370

Unify VISION: 4GL Reference

INFORMIX
If the WHERE clause is specified, read locks are obtained on the rows that satisfy the
WHERE clause condition. If the WHERE clause is omitted, a read lock is obtained on
the table.
The WHERE clause cannot include a column having the TEXT or BYTE column type.
ORACLE
The SLOCK statement with a WHERE clause obtains share update locks on the rows
that satisfy the WHERE clause condition. (ORACLE does not have read locks on rows
that are equivalent to the lock expected by the SLOCK statement.)
The SLOCK statement without a WHERE clause obtains a read lock on the target
table. After a read lock is obtained on a table, a subsequent request for a write lock
fails. However, if the table is read locked, share update locks on rows can be obtained
by another process.
The WHERE clause cannot include a column having the LONG or LONG RAW data
type.
Controlling locks
Execution of an SLOCK statement does not guarantee that the specified row or table is
read-locked. The statement generates a request for a read lock on the object. If the
request cannot be granted, another transaction is probably holding a conflicting lock.
Use the Unify VISION status$( ) system function to test the success of an SLOCK
statement. Any time an SLOCK requests a read lock on a set of rows, the lock request
fails if any one of the rows cannot be locked. In this case, the status$( ) system
function returns an SS_LMOUT status code.
You can write your application so that it attempts a lock several times if an SLOCK
fails. If, after repeated attempts, the SLOCK request still fails, it is best to restart the
transaction and release all locks.

Restrictions The SLOCK statement can be used in all VISION 4GL methods.

Example

This SLOCK statement requests a lock on the entire employee table:

SLOCK employee ;

Chapter 5: Script statements

371

This SLOCK statement requests a lock on the rows in the employee table with a job
code of REP.
SLOCK employee
WHERE emp_job_code = REP ;

See also

Script language
CHOOSE FORM USING (page 174)
COMMIT WORK (page 184)
EXECUTING (page 259)
SELECT (page 351)
SET (page 359)
UNLOCK (page 378)
XLOCK (page 398)

System functions
status$( ) (page 551)

Related
For information about transaction locking, see Managing transactions and locks in
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

For information about related external preferences, see External preferences syntax
descriptions in :Unify VISION: Application Reference
OSEC2WAIT

372

Unify VISION: 4GL Reference

STORE
Script statement: write values to external file

Syntax

STORE expression TO FILE string_expression [ file_mode ]

Arguments

expression

The expression must be a BINARY or TEXT expression. If the

expression is of any other type or if the expression is undefined, an
error results. If the expression is a NULL value or a zero-length string
(''), a zero-length file is created.

string_expression
The directory search path and file name of the file to contain the
stored TEXT or BINARY value. The expression can be either a string
constant or a string variable.
file_mode

The file mode determines how the file will be opened. If specified,
file mode must be one of the following keywords:
CREATE

(Default) If the file does not exist, it is created. If the

file exists and cannot be created, the value returned
by status$( ) is SS_FLCR.

OVERWRITE If the file exists, it is overwritten. If the file does not

exist, it is created.
APPEND

If the file exists, data is appended at the end of the

file. If the file does not exist, it is created.

For CREATE and APPEND, if the file cannot be opened, the value
returned by status$( ) is SS_FLACS.

Description

The STORE statement allows you to write TEXT or BINARY values to disk. If the
storage file cannot be written or created, an error results.
Windows
Each line-feed character is changed to a carriage return/line-feed sequence.

Chapter 5: Script statements

373

Restrictions This statement can be used in all VISION 4GL methods.

Example

This statement stores the contents of the text field description to the file specified by
the string variable $copy_file.
FIELD description
...
METHOD AFTER FIELD
IF ($save_copy=TRUE) THEN
STORE description TO FILE $copy_file

See also

374

Script language
RETRIEVE (page 342)

Unify VISION: 4GL Reference

SWITCH
Script statement: conditional execute cases

Syntax

SWITCH expression
BEGIN
CASE constant:

statement_list
[ CASE constant:
statement_list. . . ]
[ DEFAULT:
statement_list ]
END

Arguments

expression

Any valid Unify VISION expression. The expression is evaluated to

determine the CASE clause to be executed. The expression and the
constant must be type compatible.

constant

A valid Unify VISION constant. The constant can be of any of the

valid Unify VISION types: NUMERIC, FLOAT, AMOUNT, BOOL,
STRING, TEXT, BINARY, DATE, or TIME. It can also be the NULL
constant. The constant must be type compatible with the expression.

statement_list One or more VISION 4GL statements.

Description

The SWITCH statement conditionally executes one of the several statement_lists.

Each statement_list is introduced by either a CASE clause or a DEFAULT clause.
To execute the SWITCH statement, VISION Runtime Manager first evaluates
expression and compares this value to all the constant values in the CASE clauses.
Each CASE constant must be unique. The constant value can be the NULL constant
(CASE NULL:) to compare a null value. If the expression value matches one of the
CASE constants, VISION Runtime Manager executes the corresponding statement_list.
If the control expression contains a null value, it evaluates to UNKNOWN and Unify
VISION executes the CASE NULL clause.

Chapter 5: Script statements

375

If you omit the CASE NULL clause and the control expression evaluates to a null
value, the DEFAULT clause is executed, if this DEFAULT clause exists.
If there are no matching CASE constants, VISION Runtime Manager executes the
statement_list that follows the DEFAULT clause, if this clause exists. If the DEFAULT
clause does not exist, VISION Runtime Manager just skips to the next statement.
The DEFAULT clause is optional in a SWITCH statement, and a SWITCH statement
can contain only one DEFAULT clause. The DEFAULT clause can appear anywhere in
the body of the SWITCH statement.
Warning

Do not make any assumptions about the order in which the SWITCH expression
and CASE constants are compared. There is no fixed comparison order.
When you need to use a single statement list for more than one CASE value, you can
use more than one CASE clause at the beginning of the statement list. This SWITCH
statement has the following form:
SWITCH expression
BEGIN
...
CASE constant:
CASE constant:
statement_list
END

Restrictions This statement can be used in all VISION 4GL methods.

376

Unify VISION: 4GL Reference

Example

This SWITCH statement tests an abbreviated shipping code (ship_code) and sets the
variable exp_ship_code to an appropriate expanded shipping code. If ship_code has a
null value, the shipping code is initialized to None. If ship_code has a value other
than U, P, A, or the null value, the DEFAULT clause is executed and exp_ship_code is
set to Unspecified.
SWITCH ship_code
BEGIN
CASE U:
SET exp_ship_code
CASE P:
SET exp_ship_code
CASE A:
SET exp_ship_code
CASE NULL:
SET exp_ship_code
DEFAULT:
SET exp_ship_code
END

See also

TO UPS
TO Parcel Post
TO Air Express
TO None
TO Unspecified

Script language
IF (page 279)

Chapter 5: Script statements

377

UNLOCK
Script statement: release read lock

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

UNLOCK [schema_name.]table_name [ WHERE logical_expression ] ;
Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

The UNLOCK statement has no effect.

INGRES

INGRES does not support the release of individual object locks outside
a transaction commit or abort; therefore, The UNLOCK statement has

no effect.
ODBC

The UNLOCK statement has no effect.

ORACLE

The UNLOCK statement has no effect.

SYBASE SQL

The UNLOCK statement has no effect.

Server
Unify DataServer

Supported as described.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
378

Unify VISION: 4GL Reference

schema_name The name of a database schema. If not specified, the users default
schema is used.
table_name

The name of the database table to be unlocked or of the table

containing the rows to be unlocked.

logical_expression
Any Unify VISION boolean expression. The expression is evaluated to
determine the database rows that are to be unlocked.

Description

The UNLOCK statement attempts to release a read lock held by the current transaction
on a database object. This object can be either a table or a set of database rows. Write
locks are not affected by this statement.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
The COMMIT WORK statement and the Restart Tx transaction level downgrade write
locks to read locks. After the write lock has been downgraded, you can release the
read lock with the UNLOCK statement.
The Start Tx transaction level releases all locks held by the current transaction before
it starts a new transaction. Using Start Tx is the only way to directly release a write
lock. You can use the ON CHOOSE NEXT FORM section to specify a transaction
level.
The set of rows for which to issue the lock release is determined by the WHERE
clause. UNLOCK requests a lock release for all read-lock rows that satisfy the
logical_expression in the WHERE clause. This logical_expression must include a test
on at least one column name from the table table_name.
If the logical_expression evaluates to TRUE for a selected row, UNLOCK issues a lock
release request for the row. If the logical_expression evaluates to FALSE or to a null
value for a selected row, UNLOCK does not issue a lock release request for the row.
If the WHERE clause is omitted, UNLOCK requests a lock release on the entire
read-locked table, table_name.
Unlocking rows that are already unlocked is not an error. It is good programming
practice to unlock any rows or tables no longer required. After the object is unlocked,
other users and applications can access it.

Chapter 5: Script statements

379

Use Unify VISION locking statements (SLOCK, XLOCK, UNLOCK) in a multiuser

application to protect selected rows and tables from modification. A transaction has
read access on any object it has read-locked and both read and write access on any
object it has write-locked.
Use the UNLOCK statement to unlock rows and tables locked by previous statements
in the current transaction.
If the DBMS does not provide a method for unlocking rows, the UNLOCK statement
has no effect.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This UNLOCK statement unlocks the entire table employee. All read-lock rows in
employee owned by your transaction are unlocked. Write-locked rows remain
write-locked.
UNLOCK employee ;

This UNLOCK statement unlocks the rows in the employee table that have an
employee job code (emp_job_code) equal to REP. The COMMIT WORK statement
before the UNLOCK statement downgrades the write locks held by the current
transaction to read locks.
COMMIT WORK
UNLOCK employee
WHERE emp_job_code = REP ;

See also

Script language
COMMIT WORK (page 184)
ROLLBACK WORK (page 348)

SLOCK (page 369)

XLOCK (page 398)

For information about transaction locking, see Managing transactions and locks in
Related
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

See Unify VISION: Class Reference for information about related methods:
Methods
ON CHOOSE NEXT FORM

380

Unify VISION: 4GL Reference

UPDATE
SQL DML statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

UPDATE SQL_clause ;
Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
SQL_clause

Description

Any of the keywords of statements permitted by the DBMS within an

UPDATE command.

When VISION Runtime Manager encounters an UPDATE statement, it prepares the

statement for processing by the database. Because this statement is executed by the
DBMS, it must conform to the syntax requirements of the DBMS; extensions provided
by the DBMS can also be included.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.

Chapter 5: Script statements

381

The set of rows to be updated is determined by a WHERE clause.

Before updating a row, a write lock is obtained. If UPDATE encounters a locked row
or some other error condition, the update operation on the row fails, the UPDATE
statement terminates, and no rows are updated.
If no WHERE clause is specified, UPDATE attempts to update all rows in the specified
table. These rows are updated if no error is encountered (such as a locked row) during
the update operation.
Use the Unify VISION status$( ) system function to test the success of a database
update. If the user does not have update privilege, the status$( ) system function
returns a status code of SS_WRACS after an update operation. If the record to be
updated is not found, status$( ) returns SS_NOREC.
Warning

Using a non-interactive database statement to update rows that have records in

the forms selected set does not update the selected set records. The selected set
records remain unaffected by the update although their associated rows have been
updated.
INFORMIX

A WHERE clause cannot include a column having the TEXT or BYTE column type.
INGRES

The UPDATE statement allows columns of one table to be updated using columns
from another table or tables, if this form of the UPDATE statement is used:
UPDATE table_name [FROM table_name [, table_name ]*] SET . . .
ORACLE

A WHERE clause cannot include a column having the LONG or LONG RAW data type.
SYBASE SQL Server

Before you lock a query result by executing an UPDATE statement, make sure that you
consider the effects of triggers that are fired by the UPDATE statement. Otherwise, the
UPDATE statement can produce unanticipated results.
382

Unify VISION: 4GL Reference

Unify DataServer
The maximum number of updated columns is set by the SQLFLDCNT preference.

Restrictions This statement can be used in all VISION 4GL methods.

See also the documentation provided by the DBMS vendor.

Related
information
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 5: Script statements

383

UPDATE CURRENT RECORD

Script statement: interactive add or update operation

Syntax

UPDATE CURRENT RECORD

Description

The UPDATE CURRENT RECORD statement initiates an add or update operation on

the current record. If the current record is not yet in the selected set, UPDATE
CURRENT RECORD performs an interactive add operation to add a new record to the
selected set and insert a new row in the target table. If the current record already exists
in the selected set, UPDATE CURRENT RECORD performs an interactive update
operation to update the forms current record and the associated target table row.
When used in the ON FIND section, UPDATE CURRENT RECORD updates the
current record in the target table and stores the updated record in the selected set.
The current record remains current after the target table row is inserted or updated.
UPDATE CURRENT RECORD does not cause the execution of any add or update
sections (BEFORE ADD, AFTER ADD, BEFORE UPDATE, or AFTER UPDATE).

This statement requests a write lock on the current records target table row. If this
write lock request is successful, UPDATE CURRENT RECORD performs the
interactive update operation.
To test the success of an UPDATE CURRENT RECORD statement, use the status$( )
system function in the same section that contains the UPDATE CURRENT RECORD
statement. If a write lock cannot be obtained, an error message is displayed, and
status$( ) returns a value of SS_LMOUT.
If UPDATE CURRENT RECORD is used on a form that does not have a target table, it
updates only the current record in the selected set.

Restrictions This statement can be used in all VISION 4GL methods except FUNCTION.
384

Unify VISION: 4GL Reference

Example

This UPDATE CURRENT RECORD statement updates the database record if the
description field has changed.
FIELD description
METHOD BEFORE FIELD
IF (is_current_record_stored$()) = FALSE THEN
BEGIN
UPDATE CURRENT RECORD
DISPLAY This record has been added. FOR FYI_MESSAGE WAIT
END

See also

Script language
CLEAR TO ADD (page 180)
DELETE (page 215)
DELETE CURRENT RECORD (page 217)
DELETE SELECTED ROW (page 221)
INSERT (page 283)
UPDATE (page 381)
UPDATE SELECTED ROW (page 386)

See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
ON FIND

Chapter 5: Script statements

385

UPDATE SELECTED ROW

Script statement: update operation

Syntax

DBMS dependent

EXECUTING_block
UPDATE SELECTED ROW
SET column_name = { NULL | value_exp | (query_expr) } [ , . . . ] ;

Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

Supported.

INGRES

Supported.

ORACLE

The UPDATE SELECTED ROW statement has no effect for ORACLE.

SYBASE SQL

The UPDATE SELECTED ROW statement has no effect.

Server
Unify DataServer

Supported.

Arguments

EXECUTING_block

An EXECUTING clause in an SQL SELECT statement.

column_name The name of the database column to be updated.

Description

value_expr

Specifies a value expression to be inserted into the database column.

query_expr

Any SELECT statement with only one database column in the

selection list.

The UPDATE SELECTED ROW statement initiates a non-interactive update operation

to update a row retrieved by a SELECT statement.
The UPDATE SELECTED ROW statement does not cause execution of the BEFORE
UPDATE or AFTER UPDATE sections.

386

Unify VISION: 4GL Reference

This statement can be used only from within an EXECUTING block. If the
EXECUTING block is nested within other EXECUTING blocks, the updated row is the
row associated with the innermost block.
This statement can be used only when the table of the associated SELECT statement is
updateable. The SELECT statement can contain no more than one table in the FROM
clause and cannot contain a GROUP BY, ORDER BY, or HAVING clause.
Warning

Using an UPDATE SELECTED ROW statement to update rows that are in the
forms selected set does not update the selected set records. The selected set
records remain unaffected by the update although their associated rows in the target
table have been updated.
If UPDATE SELECTED ROW cannot lock the selected row or if any other error
occurs, the update operation fails.
Use the Unify VISION status$( ) system function to test the success of a database
update. If the user does not have update privilege, the status$( ) system function
returns a status code of SS_WRACS after an unsuccessful update operation.
INGRES

Because INGRES requires that any column to be updated must be specified, Unify
VISION appends a FOR UPDATE OF clause that lists every column in the table to the
DECLARE CURSOR statement for the SELECT. For large tables with long column
names this can cause the maximum statement length to exceed the current limit.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This UPDATE SELECTED ROW statement retrieves each row in the employee table
to update each employees salary based on a percentage rate. The date of last salary
increase is then changed to the current date.
SET emp_last TO
SELECT emp_last_name FROM employee
EXECUTING
BEGIN
IF yes_no$(Does employee + emp_last + receive a raise?, 1)
THEN
UPDATE SELECTED ROW
SET sal = (1 + $raise) * sal,
last_raise = current_date$();
END

Chapter 5: Script statements

387

See also

Script language
DELETE CURRENT RECORD (page 217)
DELETE SELECTED ROW (page 221)
EXECUTING (page 259)
SELECT (page 351)
UPDATE CURRENT RECORD (page 384)

System functions
status$( ) (page 551)

See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
AFTER ADD
AFTER UPDATE
ON FIND

388

Unify VISION: 4GL Reference

VALUES TO RETURN ARE

Script statement: specify variables retrieved from child form

Syntax

VALUES TO RETURN ARE var1[, var2, . . . , varn ]

Arguments

var

Description

The VALUES TO RETURN ARE statement specifies the names of the variables from
which the values are to be obtained when execution returns from the current form to
the parent form. Values are returned when the user executes the uv_return_values or
uv_dismiss_form commands or when the NEXT ACTION IS RETURN_VALUES or
NEXT ACTION IS DISMISS statement is executed. This statement can be used in a
form script to specify return fields or variables when the DBMS does not provide
primary keys in the database.

The name of the local variable or field that contains a value that is to
be returned from a form. References to object attributes that do not
yield a VALUE are prohibited.

The number of variables specified must be equal to the number of variables specified
in the RETURN clause of the CREATE FORM or CHOOSE FORM statements for the
parent form.

Restrictions The VALUES TO RETURN ARE statement can be used in all VISION 4GL sections.

Example

In this example, the detail form defines a command named update_current_state.

The update_current_state command returns values from the detail form to the parent
form.
FORM CLASS detail
PUBLIC $a, $b
METHOD ON CREATE
VALUES TO RETURN ARE $a, $b,field_3
DEFINE COMMAND update_current_state
$a = field_1 + field_2
$b = field_1 = field_2
NEXT ACTION IS RETURN_VALUES

Chapter 5: Script statements

389

See also

Predefined commands
uv_dismiss_form see Unify VISION: Application Reference.
uv_return_values see Unify VISION: Application Reference.
Script language
CHOOSE FORM USING (page 174)
CREATE FORM (page 191)
ENABLE ZOOM TO (page 245)

See Unify VISION: Class Reference for information about related methods:
Related
information
Methods
ON RETURN VALUES

Runtime operations
Return values

390

Unify VISION: 4GL Reference

WAIT FOR
Script statement: suspend partition execution

Syntax

WAIT FOR message_handle

Arguments

message_handle
A message handle identifying the asynchronous message to wait for.

Description

The WAIT FOR statement suspends execution of a partition until the processing of the
asynchronous message identified by message_handle has completed.
The execution of the WAIT FOR statement also performs the assignment of result
parameters and the method return value into the variables specified in the SEND
MESSAGE statement which initiated the message.
Use the status$( ) system function to determine the success of WAIT FOR statement.
In failure cases, use the dap_ti_errcode$( ), dap_td_errcode_i$( ),
dap_td_errcnt$( ), and dap_4gl_errcode$( ) system functions to determine the exact
cause of a failure.
While the application is suspended, the following operations will continue to be
processed:
GUI events

incoming messages
BUSINESS_EVENT handlers

The exception is when a WAIT FOR statement is invoked from within a WHEN
FIELD CHANGES method. In this case, the partition will not process other incoming
message requests while waiting for the response from the specified message.
A WAIT FOR statement can be specified only once for any given message handle. A
WAIT FOR statement which specifies a message handle which has already been used
previously in a WAIT FOR statement will return an error.
Chapter 5: Script statements

391

See also

Script language
SEND MESSAGE (page 354)

System functions
dap_4gl_errcode$( ) (page 433)
dap_td_count$( ) (page 434)
dap_td_errcode_i$( ) (page 435)
dap_ti_errcode$( ) (page 438)
status$( ) (page 551)

Related
See Unify VISION: Class Reference for information about related classes:
information
MSG_HANDLE

392

Unify VISION: 4GL Reference

WHILE
Script statement: execute loop until condition is false

Syntax

WHILE logical_expression

statement_body

Arguments

logical_expression
Any Unify VISION BOOL expression. The expression is evaluated at
the beginning of each loop iteration. The statement_body is executed
as long as this expression is TRUE.
statement_body
Any valid VISION 4GL statement: either a single statement or a
statement block (statements surrounded by BEGIN and END).

Description

The WHILE statement executes statement_body until logical_expression is FALSE.

To execute the WHILE statement, the VISION Runtime Manager first evaluates
logical_expression. This expression determines the number of times that the statement
body is executed.
If logical_expression evaluates to TRUE, VISION Runtime Manager re-executes
statement_body. If logical_expression initially evaluates to FALSE, the statement_body
is not executed. If logical_expression contains a null value, it evaluates to FALSE.
If logical_expression contains a variable, this variable must have an initial value
assigned before the WHILE statement so the logical_expression can be evaluated the
first time.
VISION Runtime Manager continues the process of testing the logical_expression and
executing the statement_body until logical_expression is FALSE. When the
logical_expression is FALSE, the WHILE loop ends.

Because VISION Runtime Manager evaluates the logical_expression in a WHILE

statement before each execution of the statement_body, it is possible that the WHILE
statement_body might not be executed at all (if logical_expression initially evaluates
to FALSE).

Restrictions This statement can be used in all VISION 4GL methods.

Chapter 5: Script statements

393

Example

This WHILE statement displays the numbers 1 to 99 as values in the current field
and then leaves the WHILE loop.
SET index TO 1
WHILE index < 100
BEGIN
DISPLAY index
SET index TO index + 1
END

See also

394

Script language
BREAK (page 168)
CONTINUE (page 187)

FOR (page 267)

REPEAT (page 337)

Unify VISION: 4GL Reference

WRITE PIPELINE
Script statement: send data across pipeline

Syntax

WRITE PIPELINE pipe_name expression_list

Arguments

pipe_name

A standard Unify VISION variable identifying the file descriptor of the

open pipeline.

expression_list A list of Unify VISION expressions separated by commas. Each

expression is evaluated and the resulting value is sent across the
pipeline pipe_name.

Description

The WRITE PIPELINE statement sends data across an open pipeline, pipe_name. A
pipeline sends information from the application to other programs. When VISION
Runtime Manager executes the statement, it writes the elements of expression_list to
the pipeline identified by the variable pipe_name.
To send data across a pipeline, you must first create the pipeline with the CREATE
PIPELINE statement. CREATE PIPELINE creates an operating system pipeline and
puts the pipelines file descriptor in pipe_name.
VISION Runtime Manager writes the information as a stream of ASCII characters.
Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string
containing the number. BOOL values are converted to the strings YES or NO.
DATE and TIME values are converted to their string equivalents. For each line of a
TEXT value, a backslash (\) is inserted as an escape character before each newline

character. Binary values are truncated at the first newline or other control character or
at the first unprintable character.
VISION Runtime Manager automatically inserts separator characters between the

expressions in expression_list. By default, the field separator character is a vertical bar

(|). You can change the field separator by assigning a different character to the Unify
VISION SEPARATOR preference.
VISION Runtime Manager also automatically inserts a newline character (\n) at the

end of expression_list.
Chapter 5: Script statements

395

You must build the items in expression_list so that the information is in the correct
format for the external programs in the pipeline. WRITE PIPELINE inserts only field
separators between fields and a newline at the end of the data record. To format data
for formatting programs, you can include the newline, carriage return, backspace or
tab characters in the pipeline data.
Writing data in the correct format for formatting programs often involves using many
WRITE PIPELINE statements. For sending non-printing characters with the WRITE
PIPELINE statement, you can use the following escape sequences:

\b

Backspace

\n

Newline

\r

Return (ASCII 13)

\t

Tab

You can send non-printing characters that are not listed by using the Unify VISION
char_code_to_str$( ) system function.
The Unify VISION Report Writer, RPT, expects input in the form of records. Each
record is made up of fields of data. By default, RPT expects the standard field
separator (|) between fields. Each record must be terminated by a newline character
(\n).

Restrictions This statement can be used in all VISION 4GL methods.

Example

This WRITE PIPELINE statement sends a numeric constant (50), a string constant
(Standard Terms), and a form variable (form:variable) to the pipeline identified by
$pipe_one.
WRITE PIPELINE $pipe_one
50, Standard Terms, form:variable

The information is sent over pipe_one in the standard RPT format with fields
separated by vertical bars and a newline marking the end of the record. If
form:variable contained the string Region 4, the output to the pipeline would be:
50|Standard Terms|Region 4\n

396

Unify VISION: 4GL Reference

This WRITE PIPELINE statement sends the stock number, description and unit price
from all selected rows in the stock table to the pipeline identified by $pipe_two.
SET stock_num, stock_desc, stock_uprice TO
SELECT st_number, st_description, st_unit_price
FROM stock
WHERE st_number > 0 AND st_number < 5000
EXECUTING
BEGIN
WRITE PIPELINE $pipe_two
stock_num, stock_desc, stock_uprice
END

See also

Script language
CLOSE PIPELINE (page 183)
CREATE PIPELINE (page 196)

Related
information

For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
SEPARATOR

Chapter 5: Script statements

397

XLOCK
Script statement: request write lock

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ]

XLOCK [schema_name.]table_name [ WHERE logical_expression ] ;
Shaded portions of the syntax are DBMS dependent.

Support

Support for this feature is DBMS dependent.

INFORMIX

Supported with the restrictions described in the following paragraphs.

ODBC

The XLOCK statement has no effect.

ORACLE

Supported with the restrictions described in the following paragraphs.

SYBASE SQL

Supported with the restrictions described in the following

paragraphs.

Server

Unify DataServer

Supported as described.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name

of a database connection, for example:
USING CONNECTION DEFAULT

or
USING CONNECTION emps

The keyword DEFAULT specifies the default connection that was

specified for the application. A string expression must match one of
the entries in the database connection map (DCM) file.
398

Unify VISION: 4GL Reference

schema_name The name of a database schema. If not specified, the users default
schema is used.
table_name

The name of the database table to be write-locked or of the table

containing the rows to be write-locked.

logical_expression
A DBMS boolean expression. The expression is evaluated to determine
which database rows are issued a write lock request.

Description

An XLOCK statement issues a write lock request on a database object. This object can
be either a table or a set of database rows. A write lock grants a transaction both read
and write access. When a table or row has a write lock, the transaction can read and
modify the object. Unless the application or DBMS allow reading of dirty data, other
transactions can neither read nor write an write-locked object.
The optional USING clause specifies the name of a database connection for this
statement only. The optional keyword CONNECTION can be used to enhance
readability of the clause. If no connection is specified, the connection of the current
form is used.
Use Unify VISION locking statements (SLOCK, XLOCK, UNLOCK) in a multiuser
application to protect selected rows and tables from modification. A transaction has
read access on any object it has read-locked and both read and write access on any
object it has write-locked.
Using the WHERE Clause
The set of rows for which to issue the lock request is determined by the WHERE
clause. XLOCK requests a write lock for all rows that satisfy the logical_expression in
the WHERE clause. This logical_expression must include a test on at least one column
name from the table table_name.
If the logical_expression evaluates to TRUE for a row, a write lock is requested. If the
logical_expression evaluates to FALSE or to a null value for a row, no lock is
requested.
If the WHERE clause is omitted, a write lock is requested for the entire table.
INFORMIX

If the WHERE clause is specified, read locks are obtained on the rows that satisfy the
WHERE clause condition. If the WHERE clause is omitted, a read lock is obtained on
the table.
The WHERE clause cannot include a column having the TEXT or BYTE column type.
Chapter 5: Script statements

399

ORACLE

The XLOCK statement with a WHERE clause obtains share update locks on the rows
that satisfy the WHERE clause condition.
The XLOCK statement without a WHERE clause obtains a write lock on the target
table. After a write lock is obtained on a table, a request for a read lock fails.
The WHERE clause cannot include a column having the LONG or LONG RAW
column type.
SYBASE SQL Server

When you use the XLOCK statement or clause to request a write lock, the request is
translated to a request for a read lock. Explicit requests for write locks are not
supported by SYBASE SQL Server.
If an add, update, or delete operation is subsequently applied, a write lock is obtained.
You can exclusively lock a query result by executing a SYBASE SQL Server UPDATE
statement, as shown in this example:
UPDATE mytable
SET column1 = column2
. . .

Executing XLOCK has the same result as executing the Transact-SQL HOLDLOCK
clause. The HOLDLOCK clause indicates that SYBASE SQL Server is to hold the read
lock until the transaction is committed.
If the WHERE clause is included in the XLOCK statement, the lock is obtained on the
specified rows. If the WHERE clause is omitted, the lock is obtained on the table.
Controlling locks
Execution of an XLOCK statement does not guarantee that the row or table is
write-locked. The statement generates a request for a write lock on the object. If the
request cannot be granted, another transaction is probably holding a conflicting lock.
You can use the status$( ) system function to test the success of an XLOCK statement.
Any time an XLOCK requests a write lock on a set of rows, the lock request fails if
any one of the rows cannot be write-locked. In this case, the status$( ) system
function returns an SS_LMOUT status code.
You can write your application so that it attempts a lock several times if an XLOCK
fails. If, after repeated attempts, the XLOCK request still fails, it is best to restart the
transaction and release all locks.
400

Unify VISION: 4GL Reference

The Start Tx transaction level releases all locks held by the current transaction before
it starts a new transaction. Using Start Tx is the only way to directly release a write
lock. You can use the ON CHOOSE NEXT FORM section to specify a transaction
level.

Restrictions This statement can be used in all VISION 4GL methods.

Example

This XLOCK statement requests a write lock on the entire stock table.
XLOCK stock ;

This XLOCK statement requests a write lock on all rows in the stock table with a
stock number greater than 5000.
XLOCK stock
WHERE st_number > 5000 ;

See also

Script language
COMMIT WORK (page 184)
EXECUTING (page 259)
INSERT (page 283)
SELECT (page 351)
SLOCK (page 369)
UNLOCK (page 378)

System functions
status$( ) (page 551)

For information about transaction locking, see Managing transactions and locks in
Related
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.
See Unify VISION: Class Reference for information about the following related
method:
Methods
ON CHOOSE NEXT FORM

Chapter 5: Script statements

401

402

Unify VISION: 4GL Reference

6
System functions
This chapter provides complete descriptions of all VISION 4GL and system functions.
The descriptions appear in alphabetical order. Each description includes several parts:

Syntax

Presents the syntax for the system function. BOLDFACE words are
keywords. Shaded areas indicate features that are restricted to a
particular user interface, operating system, or DBMS. Italicized words
within the syntax are described under Arguments.

Support

Describes restrictions or dependencies, if any.

Arguments

Describes the italicized arguments shown in the syntax. Only system

functions have arguments.

Return values
Describes the values returned by the system function.
Description

Describes usage and any special conditions and notes.

Example

Gives a sample that shows how the function or variable might be

used.

See also

Lists other subjects in this manual that are related to the function or
variable.

Related information
Lists subjects in other manuals that provide additional information
related to this function or variable.
403

abort_ams_tx$( )
System function: abort AMS transaction

UNIX only

Unify AppMan only

Syntax

abort_ams_tx$( handle )

Support

The abort_ams_tx$( ) system function is supported only for applications that are
configured for use with a Unify AppMan transaction tracking agent. If used in an
application that is not configured for Unify AppMan, this system function has no
effect.

Arguments

handle

Return
values

(BOOLEAN)

(NUMERIC) The parameter that was returned from a

begin_ams_tx$( ) system function.

TRUE

The AMS transaction has been successfully aborted.

FALSE

The attempt to abort an AMS transaction has failed. The failure is

logged in the file specified by the AMGR_ERFL external preference.

Description

The abort_ams_tx$( ) system function aborts an AMS transaction. The AMS

transaction is terminated without reporting data to the transaction tracking application.
After executing the abort_ams_tx$( ) system function, the handle parameter is NULL.

See also

System functions
begin_ams_tx$( ) (page 412)
end_ams_tx$( ) (page 480)

For information about application management, see Unify AppMan: Managing

Related
information Applications.

404

Unify VISION: 4GL Reference

acquire_global_uvns$( )
System function: return global name service reference

Syntax

acquire_global_uvns$( [ 'transport:hostname:port_ID' ] )

Arguments

transport

Identifies the network transport type. Specify T for TCP/IP.

hostname

Identifies the name of the host machine that the name service resides
on.

port_ID

Identifies either the exact port number that the service is listening on,
or a name entry in /etc/services on hostname that specifies the port
number for the service.

Return
values

(OBJECT_REF)

Description

The system function acquire_global_uvns$( ) provides a mechanism for constructing

an object reference to a global name service. The object reference can then be used for
communicating with the name service for performing operations such as locating and
registering objects on the network.

The object reference of the global name service object.

'transport:hostname:port_ID' specifies the location of the name service to which you

want an object reference. If no location is specified or is specified as an empty string,
acquire_global_uvns$( ) returns an object reference to the default global name
service for that partition.

See also

Script language

System functions

CREATE SERVICE (page 200)

SEND MESSAGE (page 354)

acquire_local_uvns$( ) (page 406)

See Unify VISION: Class Reference for information about related classes and methods:
Related
information
UONameService class
UONameService::resolve( )
UONameService::bind( )
UOPartitionGroup class

Chapter 6: System functions

405

acquire_local_uvns$( )
System function:return local reference

Syntax

[ #include uvns_xfc.h ]
acquire_local_uvns$( )

Return
values

(OBJECT_REF)

Description

The acquire_local_uvns$( ) system function returns an object reference for the local
name service object.

See also

Script language

The object reference of the local name service object.

SEND MESSAGE (page 354)

System functions
acquire_global_uvns$( ) (page 405)

See Unify VISION: Class Reference for information about related classes and methods:
Related
information
UONameService class
UONameService::resolve( )
UONameService::bind( )

406

Unify VISION: 4GL Reference

acquire_uohost$( )
System function: identify host service

Syntax

acquire_uohost$( [ 'transport:hostname:port_ID' ] )

Arguments

transport

Identifies the network transport type. Specify T for TCP/IP.

hostname

Identifies the name of the host machine that the name service resides
on.

port_ID

Identifies either the exact port number that the service is listening on,
or a name entry in /etc/services on hostname that specifies the port
number for the service.

Return
values

(OBJECT_REF)

Description

The system function acquire_uohost$( ) returns an object reference that identifies the
host service running on a particular host in the network.

The object reference of the UOHost object.

This object reference can then be used for communication with that host service for
performing operations such as starting and stopping partitions and partition groups on
that host.
'transport:hostname:port_ID' specifies the location of the host service to which you
want an object reference. If no location is specified or is specified as an empty string,
acquire_uohost$( ) returns an object reference to the default host name service for
that partition.

See Unify VISION: Class Reference for information about related classes:
Related
information
UOHost class

Chapter 6: System functions

407

aud_mode$( )
System function: determine current form mode

Syntax

aud_mode$( )

Return
values

(BOOLEAN)

Description

TRUE

The current form mode is add/update/delete mode.

FALSE

The current form mode is find mode.

The aud_mode$( ) system function determines whether the current form mode is
add/update/delete mode. Use this function in an ON NEXT FORM or ON DISMISS
FORM section to determine the current mode of operation from which the user
executed the uv_next_form command or uv_dismiss_form.
This function is also useful in the COMMAND section when a function key has an
action defined in both form modes. The aud_mode$( ) function can be used to
separate the definition for the add/update/delete mode action from the definition for
the find mode action.

Example

In this example, the search range for the account numbers is set to 100 only if the
current form mode is find mode. If VISION Runtime Manager located records and was
in add/update/delete mode, the application moves to the next form.
METHOD ON NEXT FORM
IF ( aud_mode$() = FALSE ) THEN
BEGIN
SET acct:$acctno:SEARCH_RANGES TO 100
NEXT ACTION IS FIND
END

408

Unify VISION: 4GL Reference

background$( )
System function: execute an operating system command in the background

Syntax

UNIX:

background$( shell, command_string )

Windows:
background$( , command_string )

Arguments

shell

(STRING) (UNIX only) The directory search path and file name of the
shell to be used for executing the command. If shell is null or a
zero-length stringtwo apostrophes (), the shell is determined by
following the normal search hierarchy:
1. the command line
2. the SHELL preference
3. (Unify DataServer only) the SHELL preference set in dbname.cf
4. the SHELL preference set in the application preferences file
(vision.uvp)

command_string
(STRING) The string containing the command or application to be
executed.

Return
values

The command specified by command_string was executed

successfully.

UNDEFINED

The command_string is not a valid operating system command.

system_value

(UNIX) The operating system could not execute the command_string,

so the background$( ) system function returned the value from the
operating system function system( ).
(Windows) The operating system could not execute the
command_string, so the background$( ) system function returned the
value from the operating system function WinExec( ).

Chapter 6: System functions

409

Description

Execution of background processes is dependent on the operating system, as described

in the following paragraphs.
UNIX

For UNIX, the background$( ) system function executes an operating system

command so that its progress and results are not displayed on the screen. The
command can be any command that you can execute from the operating system
prompt.
Windows NT
For Windows NT, this function runs a program in the background and attaches a
console window to main( ). The system_value returns the value from the operating
system function CreateProcess( ).

Example

The following example uses the background$( ) system function to format and print a
report if the user answers yes in the print_report field. The report is executed by the
operating system without altering the application display.
FIELD print_report
METHOD AFTER FIELD
IF (print_report = TRUE) THEN
background$(/bin/sh,nroff ms report1 | lpr)

Windows NT

See also

background$(, c:\\winnt\\system32\\cmd.exe /c dir > c:\\tmp.txt);

System functions
push_shell$( ) (page 516)
system$( ) (page 574)

For information about the application preferences file, see Deploying the application
Related
information in Unify VISION: Developing an Application.

410

Unify VISION: 4GL Reference

beep$( )
System function: sound the bell on the workstation

Syntax

beep$ ( beep_count )

Arguments

beep_count

Return
values

None.

Description

The beep$( ) system function sounds a beep on the users workstation. Use this
function to alert the user to some special event such as an error message, invalid
action, or important task.

(NUMERIC) The number of bell characters to send to the terminal.

This system function has no effect if the user has disabled the bell on the workstation.

Example

This example causes three beeps when the items quantity-on-hand in inventory
reaches zero.
IF ( finventory:$nv_q_on_hand = 0 ) THEN
BEGIN
beep$(3)
DISPLAY No more items in inventory Time to reorder!
FOR FYI_MESSAGE WAIT
END

See also

Script language
DISPLAY (page 229)

Chapter 6: System functions

411

begin_ams_tx$( )
System function: begin AMS transaction

UNIX only

Unify AppMan only

Syntax

begin_ams_tx$( AMS_tx_name, RESULT handle )

Support

The begin_ams_tx$( ) system function is supported only for applications that are
configured for use with a Unify AppMan transaction tracking agent. If used in an
application that is not configured for Unify AppMan, this system function has no
effect.

Arguments

AMS_tx_name (STRING) The name of the AMS transaction to be started. This name

is reported to the transaction tracking agent.

handle

Return
values

Description

(NUMERIC) RESULT parameter that uniquely identifies this AMS

transaction. This handle must be used to end or abort the transaction.

(BOOLEAN)
TRUE

The AMS transaction has been successfully started.

FALSE

The attempt to start an AMS transaction has failed. The failure is

logged in the file specified by the AMGR_ERFL external preference.

The begin_ams_tx$( ) system function starts an AMS transaction. An AMS transaction

handle can be declared in a global function or script. The handle is valid only for the
current application process.
To complete an AMS transaction, it must be terminated by using the end_ams_tx$( )
system function.
To abort an AMS transaction, use the abort_ams_tx$( ) system function.

412

Unify VISION: 4GL Reference

g Tip

Example

To ensure that a transaction is uniquely identified when displayed by the transaction

management tool, AMS_tx_name must be a unique identifier. To ensure that
applications are uniquely identified, use the instance_name argument of the vision
utility.

In this example an AMS transaction is used to report sending a message to a service

object.
begin_ams_tx$(message_tx, message_tx_handle)
SEND MESSAGE resolve TO $nmsrv_objectref USING (invoice_srv, $inv_objref);
end_ams_tx$(message_tx_handle)

See also

System functions
abort_ams_tx$( ) (page 404)
end_ams_tx$( ) (page 480)

Related
For a description of the vision utility, see Unify VISION: Application Reference.
information
For information about application management, see Unify AppMan: Managing
Applications.

Chapter 6: System functions

413

binarylen$( )
System function: determine the length of a binary value

Syntax

binarylen$( binary_value )

Arguments

binary_value

(BINARY) A binary value.

Return
values

(NUMERIC)

A NUMERIC value for the length of the binary_value in bytes is

returned. If the BINARY value has a NULL value, a NULL NUMERIC
value is returned.

Description

The binarylen$( ) system function determines the length in bytes of a BINARY value.

Example

This example extracts a set of integers from a list of 4-byte integers.

FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1)
BEGIN
SET $start TO $idx * 4;
SET $end TO $start + 4;
SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end));
END;

See also

414

Script language
subbinary$( ) (page 569)

Unify VISION: 4GL Reference

char_code_to_str$( )
System function: convert an integer into a character string

Syntax

char_code_to_str$ ( ascii_value )

Arguments

ascii_value

(NUMERIC) The decimal ASCII value to be translated into a character.

Return
values

(STRING)

The single character representation of the ASCII value ascii_value.

Description

The char_code_to_str$( ) system function translates an integer ascii_value into a

single character string. The ascii_value must be an integer in the range 0 to 255 (valid
ASCII values).
This function is used primarily to include non-printing characters in strings.

Example

This SET statement uses char_code_to_str$( ) to assign the ASCII representation of

^c (CTRL c) to the variable ctrlC.
SET ctrlC TO char_code_to_str$(3)

See also

System functions
str_to_char_code$( ) (page 560)

Chapter 6: System functions

415

check_dirty$( )
System function: determines status of dirty data

Syntax

check_dirty$( )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The application is always allowed to access dirty data; therefore,

check_dirty$( ) always returns TRUE.

INGRES

The check_dirty$( ) function always returns the current value of the

show_dirty$( ) flag. check_dirty$( ) returns TRUE if dirty data reads
are enabled; the function returns FALSE if dirty data reads are
disabled.

ODBC

The application is not allowed to access dirty data; therefore,

check_dirty$( ) always returns FALSE.

ORACLE

check_dirty$( ) always returns TRUE.

SYBASE SQL

The application is not allowed to access dirty data; therefore,

check_dirty$( ) always returns FALSE.

Server

Unify DataServer

Fully supported. The check_dirty$( ) system functions returns TRUE

if the selected set or the current record contains locked records and
FALSE if the selected set contains no dirty data.

Return
values

416

(BOOLEAN)
TRUE

Where check_dirty$( ) is fully supported, TRUE indicates that the

selected set or the current record contains dirty data.

FALSE

The selected data does not contain dirty data.

Unify VISION: 4GL Reference

Description

If fully supported by the underlying DBMS, the check_dirty$( ) system function

determines whether the results of a database access encountered dirty data. Dirty data
is data in a database row that was write-locked by another transaction when the current
transaction tried to access it.
If a row is write-locked, it is usually because some other transaction is updating,
deleting, or adding the row. The data in this write-locked row might be in the process
of being updated or deleted by another transaction. The write-locked row might not
have the same column values in the database when the exclusive lock is released. If
the row has been deleted, the values might not even exist.
If the DBMS supports the show_dirty_data option, you can use the Unify VISION
system function show_dirty$( ) to specify whether dirty data is brought into the
application.
If the application allows dirty data, column values for write-locked rows are brought
into the application.
If the application does not allow dirty data, column values for write-locked rows are
not brought into the application.
The check_dirty$( ) system function returns the results of the connection defined for
the current form, not for the last executed connection.
Unify DataServer
You can use check_dirty$( ) to determine whether dirty data was accessed:
If the application allows dirty data and if the database accessed write-locked
rows, check_dirty$( ) returns TRUE. If no dirty data was encountered,
check_dirty$( ) returns FALSE.
If the application does not allow dirty data, column values for write-locked
rows are not brought into the application. You can use check_dirty$( ) to
determine whether any write-locked rows were accessed, even though their
column values are not available.
If the application does not show dirty data, UNDEFINED values can occur for
write-locked rows in two possible ways:
an interactive find operation: if the current transaction is running at record
consistency
a non-interactive find: if the SELECT statement does not include a locking
clause

Chapter 6: System functions

417

You can use check_dirty$( ) with either of these find operations to determine whether
a selected row is write-locked.
For an interactive find operation, you can call check_dirty$( ) in the ON FIND section
to check each selected row for dirty data. If you do not want to include the dirty data,
use the REJECT RECORD statement. You could also use check_dirty$( ) in the
AFTER FIND section to determine whether any rows have dirty data.
For a non-interactive find operation, you can use the check_dirty$( ) function in the
EXECUTING clause of SELECT to check each selected row for dirty data or after the
SELECT statement to check whether any selected rows have dirty data.

Example

In this example, check_dirty$( ) checks the results of a database search on a target

table. If the selected set contains dirty data, the application asks whether the user
wants to continue using the selected set. If the end user answers NO, the application
clears the selected set.
METHOD AFTER FIND
IF check_dirty$() THEN
BEGIN
IF ( NOT yesno$(Set contains dirty data. Continue?, 0) )
THEN NEXT ACTION IS CLEAR_TO_FIND
END

See also

System functions
show_dirty$( ) (page 532)

For information about dirty data and transaction control, see Managing transactions
Related
information and locks in Unify VISION: Developing an Application.

418

Unify VISION: 4GL Reference

child_forms$( )
System function: return a list of child form references

Syntax

LOCAL_declaration

...
child_forms$( parent_form_ref, child_form_refs, num_child_forms )

Arguments

PRIVATE_declaration
A PRIVATE or PUBLIC declaration that specifies an unbounded list,
for example, PRIVATE LIST child_form_ref [1 TO UNKNOWN
ESTIMATING 10].

parent_form_ref
An expression that identifies the object reference of the parent form.
child_form_refs
The unbounded list for receiving the object references for child form
instances.
num_child_forms
The number of child form instances found.

Return
values

None.

Description

The child_forms$( ) system function returns a list of references and a count of all
child forms for a given parent form. The list of references begins with 1.

Related
See Unify VISION: Class Reference for information about related methods:
information
ON NEW CHILD

Chapter 6: System functions

419

clip_str$( )
System function: remove leading and trailing blanks

Syntax

clip_str$ ( value )

Arguments

value

(STRING/TEXT) The string or text from which to remove leading and

trailing blanks.

Return
values

(STRING)

The clipped string or text (with leading and trailing blanks removed).

Description

The clip_str$( ) system function removes leading and trailing blanks from a string or
text value. For text values, leading and trailing newline characters are also removed. If
value is a null or a zero-length value, clip_str$( ) returns value. This function does not
remove embedded blanks. This function is useful for removing extra blanks from a
database string column.

Example

This example extracts a menu item from mnu_table and stores the clipped menu item
in mnu_item.
SET mnu_item TO SELECT mnu_item_name FROM mnu_table WHERE mnu_id = $id;
SET mnu_item TO clip_str$(mnu_item)

See also

420

System functions
strlen$( ) (page 567)
substr$( ) (page 571)

Unify VISION: 4GL Reference

close_message_file$( )
System function: close message file

Syntax

close_message_file$( )

Return
values

None.

Description

The close_message_file$( ) system function closes a previously opened message file.

Only one message file can be open at a time.
Messages are stored in a message file in a special format. For a complete description
of the message file format, see the description for the Unify VISION system function
get_message$( ).

Example

In this example, open_message_file$( ) opens the message file /usr/apps/messages. If

this message file can be opened, the code sample retrieves a message from it using
get_message$( ). After the message is retrieved, the message file is closed by
close_message_file$( ).
IF ( open_message_file$(/usr/apps/messages) = 0 ) THEN
BEGIN
DISPLAY get_message$(100) FOR FYI_MESSAGE WAIT
close_message_file$()
END

See also

System functions
get_message$( ) (page 486)
open_message_file$( ) (page 510)

Chapter 6: System functions

421

convert_timezone$( )
System function: convert a datetime value from one time zone value to another time zone

Syntax

convert_timezone$( value, TZ1, TZ2 )

Arguments

value

(DATETIME) The value to be converted.

TZ1

(STRING or keyword) A string expression for a time zone

specification; must be in POSIX standard machine-independent format
or the LOCAL keyword.

TZ2

(STRING or keyword) A string expression for a time zone

specification; must be in POSIX standard machine-independent format
or the LOCAL keyword.

Return
values

(DATETIME)

The datetime value of the value argument converted from the TZ1 to
the TZ2 time zone specification.

Description

The convert_timezone$( ) function converts the specified value (using the TZ1 time
zone specification) to a datetime value with the TZ2 time zone specification.
If the LOCAL keyword is specified for either time zone specification (TZ1 or TZ2), it is
translated to be the local time zone.

See also

System functions

current_timezone$( ) (page 432)

Example

This example uses the convert_timezone$( ) function to convert a datetime value

from the UTZ+3 time zone to the VTZ + 2WTZ time zone; the value
12/25/99 17:15:00.000 is returned:
SET d2 to convert_timezone$(12/25/99 16:15:00.000, UTZ+3, VTZ+2WTZ)

TZ_CONVERSION
Related
information

422

Unify VISION: 4GL Reference

copy_in$( )
System function: string building

Syntax

copy_in$ ( RESULT buffer, start_offset, end_offset, in_value )

Arguments

buffer

(STRING/TEXT/BINARY) Specifies the variable to copy characters

into. Returns with contents changed.

start_offset

(NUMERIC) Specifies offset for first character of destination field.

end_offset

(NUMERIC) Specifies offset for last character of destination field.

in_value

(STRING/TEXT/BINARY/NUMERIC) Specifies the variable to move

characters from.

Return
values

None.

Description

This routine is used to copy characters from a variable (in_value) into a portion of
another variable (buffer). This is a copy of some number of characters into a logical
destination field within the buffer.
The start_offset in the destination buffer indicates the first character of the logical field
within the destination buffer where the characters will be copied to. The first character
of the destination field is indicated by a value of 1.
Although the description of this routine is mostly character-oriented, when the
destination buffer is of type BINARY, this routine is byte-oriented instead of
character-oriented. That is, a start_offset value of 2 indicates the second byte instead
of the second character. This distinction is only apparent when characters are encoded
into a multi-byte character set such as Unicode.

Chapter 6: System functions

423

The end_offset in the destination buffer indicates the last character of the logical field
within the destination variable where the characters are copied to. This is used to
protect the destination buffer from being overwritten. It marks the right edge of the
destination field.
The start_offset and end_offset must be greater than 0. The start_offset must be less
than or equal to the end_offset. The end_offset must be less than or equal to the size of
the buffer.
If the start_offset and end_offset are equal, that means that one character only is
copied from the in_value. Because of the limits on the values of start_offset and
end_offset, a request for a copy is always a request to copy at least one character.
The characters moved from the in_value always start with the first character.
The destination field size can be larger than the size of in_value. The characters that
are not overwritten by the in_value remain the same as before the call.
If the size of in_value is greater than the destination field size indicated by the
start_offset and end_offset parameters, then the copy moves only characters from the
in_value to the destination up to the size of the destination field.
If the buffer is type BINARY, then the in_value can only be of type BINARY or
NUMERIC. If the buffer is type TEXT or STRING, then the in_value can only be of
type TEXT or STRING.
If in_value is type NUMERIC, then it is assumed to be the decimal value of a single
byte to copy into the destination buffer. The value must be from 0 to 255 inclusive.

See also

System functions

pad_str_right$( ) (page 514)

trim_bytes$ ( ) (page 592)

424

Unify VISION: 4GL Reference

Example

This example uses the copy_in$( ) function to create three string fields within a
100-character buffer:
BUTTON PutMsg
METHOD ON CLICK(thebutton)
BEGIN
if ( fOpen ) then
BEGIN
set seedMsg to to_binary$( );
set Message to pad_str_right$( $seedMsg,
str_to_char_code$( ), 100 );
copy_in$( Message, 1, 5,
to_binary$(to_string$(current_time$( ))) );
copy_in$( Message, 7, 18,
to_binary$(to_string_using$(
current_date$( ), AAA DD, YYYY ) ) );
copy_in$ ( Message, 20, 100,
to_binary$($sFreeFormString ) );

Related
For more information about MQSeries, see Unify VISION:Interconnecting Applications
information with Enterprise Integrator.

Chapter 6: System functions

425

current_date$( )
System function: retrieve current date

Syntax

current_date$( )

Return
values

(DATE )

Description

The current_date$( ) system function obtains the current date from the operating
system. This date is in the same format as the Unify VISION data type DATE.

Example

In this example, current_date$( ) assigns the current date to the ld_date_found

variable if this variable was undefined.

The DATE value of the current date as retrieved from the operating
system.

FIELD ld_date_found
METHOD AFTER FIELD
IF ( fleads:ld_date_found IS UNDEFINED ) THEN
SET fleads:ld_date_found TO current_date$()

See also

426

System functions
current_time$( ) (page 431)
date_to_mdy$( ) (page 440)

Unify VISION: 4GL Reference

current_datetime$( )
System function: return current local system datetime

Syntax

current_datetime$( )

Return
values

(DATETIME)

Description

The current_datetime$( ) function returns the current local system time as a datetime
value.

See also

System functions

The value of type DATETIME equal to the current datetime as

retrieved from the operating system.

current_date$( ) (page 426)

current_time$( ) (page 431)

Example

This example uses the current_datetime$( ) function to return a datetime value; for
instance, 11/04/97 15:04:26.125:
SET logon_time to current_datetime$()

Chapter 6: System functions

427

current_form$( )
System function: retrieve current form ID

Syntax

current_form$( )

Return
values

(OBJECT_ID)

Description

The current_form$( ) system function obtains the object ID of the current form. If
there is no current form, current_form$( ) returns UNDEFINED.

428

The object ID of the current form as retrieved from the operating

system.

Unify VISION: 4GL Reference

current_record_count$( )
System function: return the number of records in selected set

Syntax

current_record_count$( )

Return
values

(NUMERIC)
>0

The number of records in the selected set.

The form is in find mode, or no records have been selected.

Description

The current_record_count$( ) system function determines the number of records in

the selected set. While the form is in find mode, this function always returns zero (0).
After completing a successful find, the function returns the number of records selected
from the database. This record count is adjusted if records are added to or deleted from
the selected set.

Example

In this example, current_record_count$( ) determines whether a database search has

successfully located matching records. If no records have been found, the user is asked
to reenter the search criteria.
METHOD AFTER FIND
IF ( current_record_count$() = 0 ) THEN
BEGIN
DISPLAY
Search found no records, please reenter search criteria
FOR FYI_MESSAGE WAIT
NEXT ACTION IS CLEAR_TO_FIND
END

See also

Script language
CHANGE CURRENT RECORD TO (page 173)

System functions
current_record_num$( ) (page 430)
record_is_current$( ) (page 521)

Chapter 6: System functions

429

current_record_num$( )
System function: return current record number

Syntax

current_record_num$( )

Return
values

(NUMERIC)

Description

>0

The relative number of the current record within the selected set.

The form is in find mode, or no records have been selected.

The current_record_num$( ) system function determines the relative number of the

current record within the selected set. For example, if the selected set contains five
records and the third record in this set is displayed on the form,
current_record_num$( ) returns the value 3.
When the uv_clear_to_add command is executed, the current record number is one
greater than the current record count.

Example

In this example, current_record_num$( ) and current_record_count$( ) determine

whether the current record is the last record of the selected set. If the current record is
the last record, this code puts the form in add/update/delete mode.
METHOD ON NEXT RECORD
IF ( current_record_num$() = current_record_count$() ) THEN
NEXT ACTION IS CLEAR_TO_ADD

See also

430

System functions
current_record_count$( ) (page 429)
record_is_current$( ) (page 521)

Unify VISION: 4GL Reference

current_time$( )
System function: retrieve the current time

Syntax

current_time$( )

Return
values

(TIME)

Description

The current_time$( ) system function obtains the current time from the operating
system. This time is in the same format as the Unify VISION data type TIME.

Example

In this example, current_time$( ) assigns the current time to the time_entered

variable if time_entered is undefined.

The TIME value of the current time as retrieved from the operating
system.

FIELD time_entered
METHOD AFTER FIELD
IF ( time_entered IS UNDEFINED ) THEN
SET time_entered TO current_time$()

See also

System functions
current_date$( ) (page 426)

Chapter 6: System functions

431

current_timezone$( )
System function: return current time zone

Syntax

current_timezone$( )

Return
values

(STRING)

Description

The current_timezone$( ) function returns the current time zone in a POSIX standard
format. The time zone specification can then be used with the convert_timezone$( )
system function or the TZ_CONVERSION attribute.

The current time zone in POSIX standard format.

If a POSIX-compliant time zone specification cannot be obtained from the operating

system, a null STRING value is returned.

See also

System functions

convert_timezone$( ) (page 422)

Example

This example uses the current_timezone$( ) function to return a POSIX standard time
zone, for instance, PST8PDT:
SET tz to current_timezone$()
IF tz IS NOT NULL THEN
SET newDate to convert_timezone$($oldDate, PST8PDT, $tz)

TZ_CONVERSION
Related
information

432

Unify VISION: 4GL Reference

dap_4gl_errcode$( )
System function: service object runtime errors

Partitioned applications only

Syntax

dap_4gl_errcode$( object_ref )

Support

This system function is available for Partitioned applications implementations only.

Arguments

object_ref

An expression that specifies the object reference of a service object.

Return
values

(NUMERIC)

Error message number that occurred during the last method invocation
on the specified service object.

Description

The dap_4gl_errcode$( ) system function returns the VISION Runtime Manager error
code that occurred after a method was invoked on a service object. Use this system
function in your client application to determine what errors occurred in your service
objects.

Building and managing a partitioned application in Unify VISION: Developing an

Related
information Application

Chapter 6: System functions

433

dap_td_count$( )
System function: transport-dependent errors

Partitioned applications only

Syntax

dap_td_count$( object_ref )

Support

This system function is available for Partitioned applications implementations only.

Arguments

object_ref

An expression that specifies the object reference of a service object.

Return
values

(NUMERIC)

The number of a transport-dependent errors that occurred during the

last method invocation for object_ref.

Description

The dap_td_count$( ) system function returns the number of transport-dependent

errors that occurred for the last method invocation on the service object identified by
object_ref. If the status$( ) system function returns SS_DAP_TD, use this system
function to receive more detailed information.

See also

System functions
dap_4gl_errcode$( ) (page 433)
dap_td_errcode_i$( ) (page 435)
dap_ti_errcode$( ) (page 438)

Building and managing a partitioned application in Unify VISION: Developing an

Related
information Application

434

Unify VISION: 4GL Reference

dap_td_errcode_i$( )
System function: transport-dependent errors

Partitioned applications only

Syntax

#include <include/dapcodes.h>
dap_td_errcode_i$( VALUE object_ref, VALUE index )

Support

The dap_td_errcode_i$( ) system function is available for Partitioned applications

implementations only.

Arguments

object_ref

An expression that specifies an object reference.

index

One of the following values:

Return
values

(NUMERIC)

Specifies the transport that was being used when the

error occurred.

For the URPC transport, specifies a URPC error.

For the URPC transport, specifies an unmapped

Netwise error.

Transport-dependent status code that occurred during the last method

invocation on the specified service object.

For index value of 0:

1

DAP_T_LOCAL

A local transport was used for the last SEND

MESSAGE statement identified by this object
reference.
2

DAP_T_URPC
A URPC transport was used for the last SEND
MESSAGE statement identified by this object

reference.
Chapter 6: System functions

435

For index value of 1:

1

URPC_MAX_CONN

The maximum number of supported connections was

exceeded.
2

URPC_CONN_DEAD

The connection was closed by the server. The server

exited normally as a result of the last method
invocation.
3

URPC_UNMAPPED
An unmapped URPC error occurred.

URPC_CONN_REFUSED

The attempt to connect to the server for this object

reference was refused.
5

URPC_NOMEM

The transport layer was unable to allocate sufficient

memory for the operation.

Description

The dap_td_errcode_i$( ) system function returns information about the

transport-specific error that occurred for the last method. If the status$( ) system
function returns SS_DAP_TD, use the dap_td_errcode_i$( ) system function to
receive more detailed information.

Example

In this function, the status returned by the last method determines the error-checking
system function used to display an error message. If the status$( ) system function
returns SS_DAP_INT, the dap_td_errcode_i$( ) system function returns the
transport-dependent error numbers.
#include <sscodes.h>
#include <dapcodes.h>
VOID FUNCTION checkDAPerror( REF dapObj, VALUE objStat )
PRIVATE msg, inx;
BEGIN
IF $objStat != SS_NORM THEN
BEGIN

436

Unify VISION: 4GL Reference

SET msg TO A DAP error has occurred.\nObject Info:\n\n

+ Class Name:
+ $dapObj>CLASS_NAME + \n
+ Instance Name:
+ $dapObj>OBJECT_NAME + \n
+ Transport:
+ $dapObj>TRANSPORT + \n\n;
SWITCH $objStat
BEGIN
CASE SS_DAP_4GL:
SET msg TO msg
+ Server 4gl Error:
+ to_string$(dap_4gl_errcode$($dapObj));
CASE SS_DAP_TI:
SET msg TO msg
+ TransportIndependent Error:
+ to_string$(dap_ti_errcode$($dapObj));
IF dap_ti_errcode$($dapObj) = DAP_SERVER_FATAL THEN
BEGIN
SET msg TO msg
+ \nFatal Server 4gl Error:
+ to_string$(dap_4gl_errcode$($dapObj));
END
CASE SS_DAP_INT:
SET msg TO msg
+ TransportDependent Error:\nError Count:
+ to_string$(dap_td_count$($dapObj))
+ \nError Codes: ;
FOR ( SET inx to 0;
inx < dap_td_count$($dapObj);
SET inx TO inx + 1 )
BEGIN
SET msg TO msg
+ to_string$(dap_td_errcode_i$($dapObj, inx))
+ ;
END
DEFAULT:
SET msg TO msg
+ Unknown Error: + to_string$($objStat);
END
DISPLAY msg FOR FYI_MESSAGE WAIT;
END
END; /* checkDAPerror() */

See also

System functions
dap_td_count$( ) (page 435)

Building and managing a partitioned application in Unify VISION: Developing an

Related
information Application.

Chapter 6: System functions

437

dap_ti_errcode$( )
System function: transport-independent error code

Partitioned applications only

Syntax

#include <include/dapcodes.h>
dap_ti_errcode$( object_ref )

Support

This system function is available for Partitioned applications implementations only.

Arguments

object_ref

An expression that specifies the object reference of the name service

object.

Return
values

(NUMERIC)

Transport-independent status code that occurred during the last

method invocation for object_ref:

DAP_NOERROR

No error message was received.

1

DAP_SERVER_EXIT

The server exited normally as a result of the last method invocation.

2

DAP_SERVER_FATAL

A fatal runtime error occurred on the server during the last method
invocation. Use the dap_4gl_errcode$( ) system function to return
the runtime error that occurred.
3

DAP_SERVER_KILL

The server was killed during the last method invocation.

4

DAP_NOMEM

The server was unable to allocate sufficient memory to invoke the

specified method; however, the server is still available.

Description

438

The dap_ti_errcode$( ) system function returns the transport-independent status code

for the last method invocation for object_ref. Use this system function if the status$( )
system function returns SS_DAP_TI to receive more detailed information.
Unify VISION: 4GL Reference

See also

System functions
dap_4gl_errcode$( ) (page 433)
dap_td_errcode_i$( ) (page 435)
status$( ) (page 551)

Building and managing a partitioned application in Unify VISION: Developing an

Related
information Application.

Chapter 6: System functions

439

date_to_mdy$( )
System function: convert the date or datetime value to numeric values

Syntax

date_to_mdy$( date, month, day, year )

Arguments

date

(DATE/DATETIME) The DATE or DATETIME value to be converted.

month

(NUMERIC) A variable to receive the month of the converted date.

This parameter is an Unify VISION result parameter.

day

(NUMERIC) A variable to receive the day of the converted date. This

parameter is an Unify VISION result parameter.

year

(NUMERIC) A variable to receive the year of the converted date. This

parameter is an Unify VISION result parameter.

Return
values

Description

The return values for this function are returned through the arguments
month, day, and year. The actual return value for this function is
undefined.

The date_to_mdy$( ) system function converts date to three NUMERIC values: month,
day, year. These three values correspond to the month, day, and year of the DATE
value in date. The year is returned as a four-digit number.
For DATETIME arguments, the month, day, and year of the date portion of the datetime
argument are returned. If the argument has an undefined date portion, then all returned
arguments are undefined.

440

Unify VISION: 4GL Reference

Example

In this example, date_to_mdy$( ), mdy_to_date$( ), and current_date$( ) are used

to create a DATE variable with a date of five years from the current date.
SET today_date TO current_date$()
date_to_mdy$(today_date, month, day, year)
SET year TO year + 5
SET five_years TO mdy_to_date$(month, day, year)

See also

System functions
current_date$( ) (page 426)
mdy_to_date$( ) (page 506)
str_to_date$( ) (page 561)
to_date$( ) (page 579)

Chapter 6: System functions

441

datetime_adjust$( )
System function: modifies a date, time, or datetime value by an interval amount

Syntax

datetime_adjust$( dt, interval, value )

Arguments

dt

(DATE, DATETIME, TIME) An expression to be modified by the value

and interval arguments.

interval

(STRING) The type of interval to use in the adjustment; must be one

of the following strings (case insensitive):
Year
Month
Day
Hour
Minute
Second
Millisecond

value

(NUMERIC) An integer that determines the number of interval units

by which to adjust the dt argument. The integer can be negative in
which case the interval is subtracted from the dt argument.

Return
values

(DATE, DATETIME, TIME)

The adjusted date, datetime, or time value. The data type of the
returned value is the same as the data type of the dt argument.

Description

The datetime_adjust$( ) function returns a datetime value equal to the dt argument

plus value number of the interval argument. For instance, a dt argument of 1/31/97
with a value argument of 2 with an interval argument of Year returns 1/31/99.
The value of the interval argument must be appropriate for the data type of dt. For
example, you cannot give a date expression and an interval of Second, because the
date value contains no seconds.

442

Unify VISION: 4GL Reference

If the resulting date is invalid, it is decreased until a valid date is reached. For
instance:
1/31/97 +1 month returns 2/28/97
1/31/96 +1 month returns 2/29/96
2/29/96 + 1 year returns 2/28/97

Example

This example uses the datetime_adjust$( ) function to return a new datetime value,
02/04/98 15:04:26.125:
SET dt to 11/04/97 15:04:26:125
SET dt to datetime_adjust$($dt, month, 3) /* add a quarter to
the date */

Chapter 6: System functions

443

datetime_diff$( )
System function: return the difference between two date, time, or datetime values

Syntax

datetime_diff$( dt1, dt2, interval )

Arguments

dt1

(DATE, DATETIME, TIME) An expression that is compared with the

dt2 expression.

dt2

(DATE, DATETIME, TIME) An expression that is compared with the

dt1 expression.

interval

(STRING) The type of interval to return; must be one of the following

strings (case insensitive):
Year
Month
Day
Hour
Minute
Second
Millisecond

Return
values

(NUMERIC)

Description

The datetime_diff$( ) function returns a NUMERIC result of the difference between

the two dt1 and dt2 arguments based on the interval value. The absolute value of the
difference is returned, so the order of dt1 and dt2 does not matter.

The difference between the two expressions based on the interval

argument value.

The difference is the amount of that interval difference between the two expressions,
truncated to the lowest integer value. The data type of the expressions must be
applicable to that interval (for instance, neither expression can be of type time if the
interval is Day).
444

Unify VISION: 4GL Reference

When you compare datetime values with any interval except milliseconds, partial
intervals are truncated to the nearest whole integer value. For instance, the following
example returns a value of 1 because the difference is 36 hours or 1.5 days and the
remaining hours are truncated, leaving a result of 1:
datetime_diff$(11/1/97 12:00, 11/3/97 00:00, day)

Time values always default to 00:00 (midnight). If a time interval is requested and
either expression is of type DATE, the time value for that expression is assumed to be
00:00. If a time interval is requested and either expression is of type TIME (so there is
no date), then the date portions are considered identical and the difference is based on
the time values only.

See also

System functions

to_datetime$( ) (page 580)

Example

This example uses the datetime_diff$( ) function to return intervals:

SET days to datetime_diff$($dt1, $dt2, $interval)

The following table shows the results for a few example cases:
dt1

dt2

interval

returned value

11/1/97 00:00
1/3/98 00:00
year
11/1/97 00:00
1/3/98 00:00
month
11/1/97 00:00
1/3/98 00:00
day 63
11/3/97 00:00
1/1/98 00:00
year
11/3/97 00:00
1/1/98 00:00
month
11/3/97 00:00
1/1/98 00:00
day 59
1/1/97
2/2/97 12:14
Day 32
1/1/97
1/1/97 12:14
Hour
12
12/31/97
12/31/97
Second
12:00
1/1/96
Hour
12
2/28/97 12:22
1/1/97
Month
1
11/1/97
1/3/98
Year
0
11/1/97
1/3/98
Monyh
2
11/1/97
1/3/98
Day 63
11/1/97
1/1/99
Year
1
12:00
1:30
Hour
1
11/1/97 12:10:00
11/1/97 12:20:50

Chapter 6: System functions

0
2
0
1

Minute 10

445

db_type$( )
System function: determine current database type

Syntax

db_type$( )

Return
values

(STRING)

The name of the current DBMS type.

INFORMIX Specifies that INFORMIX is the data source.
INGRES

(UNIX) Specifies that INGRES is the data source.

ODBC_ACCESS

Specifies that MS Access is the data source.

ODBC_DBASE

(Windows) Specifies that dBASE is the data source.

ODBC_DBASE3

(Windows) Specifies that dBASE III is the data source.

ODBC_Ingres(Windows) Specifies that INGRES is the data source.
ODBC_DBASE4

(Windows) Specifies that dBASE IV is the data source.

ODBC_WATCOM SQL

(Windows) Specifies that Watcom SQL is the data

source.
ODBC_Watcom SQL

(Windows) Specifies that Watcom SQL is the data

source.

446

ORACLE

Specifies that ORACLE is the data source.

SYBASE

Specifies that SYBASE SQL Server is the data source.

U2000

Specifies that Unify DataServer is the data source.

Unify VISION: 4GL Reference

Description

The db_type$( ) system function enables you to write statements specific to a

particular DBMS. db_type$( ) takes no arguments and returns the name of the current
DBMS type as a string.
The db_type$( ) system function returns the database type of the current form, not the
database type of the last executed connection.
If used within a service class script, the db_type$( ) system function returns the
database type of the current services database connection, not the database connection
of the calling form.
INFORMIX
The db_type$( ) system function returns INFORMIX but does not indicate the
version or mode (OnLine, SE, or MODE ANSI).

Example

This example causes an error message to appear if the user enters the [ metacharacter
while using the ORACLE DBMS.
IF db_type$() = ORACLE THEN
DISPLAY [ metacharacter not supported FOR FYI_MESSAGE WAIT

See also

System functions
os_type$( ) (page 511)
ui_type$( ) (page 597)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.
For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
DBTYPE

Chapter 6: System functions

447

dbms_status$( )
System function: return DBMS status code

Syntax

dbms_status$( )

Return
values

(NUMERIC)

Description

The dbms_status$( ) system function returns a specific status code from the DBMS.
The values returned are specific to each DBMS.

A return code supplied by the database.

The dbms_status$( ) system function returns the value returned by the most recently
executed SQL statement, regardless of the current database connection.

Example

In this example, dbms_status$( ) determines whether any records were found in a

non-interactive find operation. If no records were found, the emp_name variable is set
to a string of spaces.
SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id;
IF (NOT_FOUND_STAT = dbms_status$())
THEN
SET emp_name TO
;

See also

System functions
sql_code$( ) (page 544)
sql_errmsg$( ) (page 545)

sql_state$( ) (page 550)

status$( ) (page 551)

For information about DBMS status codes, see the documentation provided by the
Related
information DBMS vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

448

Unify VISION: 4GL Reference

dbms_status_i$( )
System function: error message handling

Syntax

dbms_status_i$(index)

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The dbms_status_i$( ) system function is not supported for

INFORMIX. The function always returns NULL.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

The dbms_status_i$( ) system function is not supported for Unify

DataServer. The function always returns NULL.

Arguments

index

Index, ranging from 1 to n, that indicates the message in the list of

error messages that was generated by the last call to the database.

Return
values

error_code

(NUMERIC) The ORACLE-specific error code that corresponds to the

index-indicated error message in the error message string that was
generated by the last call to the database.

NULL

The index value is out of range, or the underlying DBMS is not

supported.

Description

The dbms_status_i$( ) system function returns the DBMS error code that corresponds
to the index-indicated error message in the error message string that was generated by
the last database operation that generated a call to the server. The database operation
can be initiated by either VISION Runtime Manager or a developer-defined C function.

Chapter 6: System functions

449

Example

This example displays the last error code received from the DBMS.
FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1)
BEGIN
DISPLAY dbms_status_i$(inx)
FOR FYI_MESSAGE WAIT
END

See also

450

System functions
sql_errmsg_count$( ) (page 546)
sql_errmsg_i$( ) (page 548)

Unify VISION: 4GL Reference

dde_get_data$( )
System function: DDE

Windows only

Syntax

dde_get_data$(handle, RESULT result_data, time_out)

Support

The dde_get_data$( ) system function is supported for Windows only.

Arguments

handle

(NUMERIC) The result parameter that was returned from the

dde_request_data$( ) system function. The value of this variable
uniquely identifies a request. After the request is retrieved by the
dde_get_data$( ) system function, the handle is invalid.

result_data

(TEXT RESULT) This result parameter must be a variable name. If the

server sends the value for the requested item, the value is placed in
this variable.

time_out

(NUMERIC) Number of milliseconds that VISION Runtime Manager

should wait for a reply from the server.

Description

The dde_get_data$( ) system function is used to retrieve the data that was requested
by the dde_request_data$( ) system function. If the data is sent successfully, the
function returns DDE_SUCCESS and places the data in the result_data variable.
If the dde_get_data$( ) system function times out, it cannot be called again until the
response is retrieved.

Return
values

DDE_SUCCESS

(NUMERIC) The data was successfully received and placed in

result_data.
DDE_NEGACK (NUMERIC) The server cannot carry out the DDE request.

Chapter 6: System functions

451

DDE_TIMEOUT

(NUMERIC) The server did not reply by the end of the specified
number of milliseconds (time_out).
DDE_NOLINK (NUMERIC) The handle that was passed to this system function is not

valid.
For a complete list of values that can be returned by the DDE system functions, see the
dde_codes.h file in the include directory.

Example

In this example, the call to dde_get_data$( ) is in a global event handler function,

handleRequest, that handles request data events for a DDE client.
/********************************************************************
*
hndlreq.fs
********************************************************************/

#include <ddecodes.h>
#include <ddestuff.h>
EXTERN SCRIPT STRING FUNCTION strCat(val, val, val, val, val)
EXTERN SCRIPT VOID FUNCTION dispErr(val, val, val)
BOOL FUNCTION handleRequest( handle, funcstat, timeout, REFERENCE data )
PRIVATE errstr,
/* error string */
timeoutstr, /* error message for timeout */
nolinkstr,
/* error message for DDE_NOLINK */
poststr,
/* error message for DDE_POSTFAIL */
getResp,
/* if TRUE, get the response again */
status
/* status return from dde_get_data$ */
BEGIN
. . .
SET $getResp TO TRUE
While ($getResp = TRUE)
BEGIN
/*
* get the data that was requested by dde_request_data$()
*/
SET $status TO dde_get_data$($handle, $data, $timeout)
. . .

See also

452

System functions
dde_get_response$( ) (page 457)
dde_request_data$( ) (page 465)

Unify VISION: 4GL Reference

dde_get_hot_links$( )
System function: DDE

Windows only

Syntax

dde_get_hot_links$(hot_links_array)

Support

The dde_get_hot_links$( ) system function is supported for Windows only.

Arguments

hot_links_array (MATRIX) A developer-defined two-dimensional, unbounded array of

four columns.

Description

The dde_get_hot_links$( ) system function fills the hot_links_array with the

information about the active DDE hot links and returns the number of active hot links.
The array contains one row for each active hot link and contains this information:
link_type

(STRING) Keyword that indicates whether the application is acting as

a DDE server (server) or a DDE client (client).

server_link_ID (NUMERIC) Server identifier that was returned by the

dde_initiate_link$( ) system function.
client_link_ID (NUMERIC) Client identifier that was passed to the application
through an initiate_link DDE event handler global function installed
by the INSTALL statement.
item

(STRING) Name of the data item whose value is being passed through
the hot link.

The information in the hot_links_array array can help you to track the applications
active DDE hot links.

Return
values

(NUMERIC)

Chapter 6: System functions

The number of active hot links.

453

Example

In this example, the LOCAL clause is used to define a general array variable named
hot_links and a general variable named numlinks. The hot_links array is used to
store the hot link information obtained by the dde_get_hot_links$( ) system function.
The dde_get_hot_links$( ) function also returns the number of active hot links, which
is stored in the numlinks variable by the SET statement. The call to the
dde_get_hot_links$( ) system function is in a developer-defined function named
showHotLinks.
/**********************************************************************
*
showhot.fs
**********************************************************************/
EXTERN SCRIPT VOID FUNCTION updStatus(val)
VOID FUNCTION showHotLinks( )
PRIVATE idx,
/* loop index */
numlinks,
/* number of active DDE links */
matrix hot_links[1 TO unknown, 1 TO 4] /* DDE hot link info */
BEGIN
/*
* fill the array $hot_links with the information about all of the
* currently active links
*/
SET $numlinks TO dde_get_hot_links$($hot_links)
updStatus(*********** Active DDE Hot Links ***********)
/* search the array $hot_links for a link which is a DDE client */
FOR (SET $idx TO 1 ; $idx <= $numlinks ; SET $idx TO $idx + 1)
BEGIN
If ($hot_links[$idx,1] = client) THEN
BEGIN
updStatus(Item: + $hot_links[$idx,4] )
END /* IF */
END /* FOR loop */
END

See also

454

System functions
dde_get_links( ) (page 455)

Unify VISION: 4GL Reference

dde_get_links$( )
System function: DDE

Windows only

Syntax

dde_get_links$(links_array)

Support

The dde_get_links$( ) system function is supported for Windows only.

Arguments

links_array

Description

The dde_get_links$( ) system function fills the links_array with the information
about the active DDE links and returns the number of active links. The array contains
one row for each active link and contains this information:
link_type

(MATRIX) A developer-defined two-dimensional, unbounded array of

five columns.

(STRING) Keyword that indicates whether the application is acting as

a DDE server (server) or a DDE client (client).

server_link_ID (NUMERIC) Server identifier that was returned by the

dde_initiate_link$( ) system function.
client_link_ID (NUMERIC) Client identifier that was passed to the application
through an initiate_link DDE event handler global function installed
by the INSTALL statement.
application

(STRING) Name of the application that the client wants to address as a

DDE server. Example application names include Excel, Word, or
Server.

topic

(STRING) Name of a set of related items for which a link has been
established. The topic can be a table name or a form name.

The information in the links_array array can help you to track the applications active
DDE links.
Chapter 6: System functions

455

Return
values

(NUMERIC)

Example

In this example, the LOCAL clause is used to define a general array variable named
dde_links and a general variable named numlinks. The dde_links array is used to
store the link information obtained by the dde_get_links$( ) system function. The
dde_get_links$( ) function also returns the number of active links, which is stored in
the numlinks variable by the SET statement. The call to the dde_get_hot_links$( )
system function is in a developer-defined function named showLinks.

The number of active links.

/********************************************************************
*
showlnk.fs
********************************************************************/
EXTERN SCRIPT VOID FUNCTION updStatus(val)

LOCAL FUNCTION showLinks( )

PRIVATE jnx,
/* loop index */
numlinks,
/* number of active DDE links */
matrix dde_links[1 TO unknown, 1 TO 5] /* DDE link info */
BEGIN

/*
* fill the array $dde_links with the information about all of the
* currently active links
*/
SET $numlinks TO dde_get_links$($dde_links)

updStatus(*********** Active DDE Conversations ***********)

/* search the array $dde_links for a link which is a DDE server */

FOR (SET $jnx TO 1 ; $jnx <= $numlinks ; SET $jnx TO $jnx + 1)
BEGIN
If ($dde_links[$jnx,1] = client ) THEN
BEGIN
updStatus(Application: + $dde_links[$jnx,4] +
Topic: + $dde_links[$jnx, 5]) ;
END /* IF */
END /* FOR loop */
END /* FUNCTION sendData() */

See also

456

System functions
dde_get_hot_links$( ) (page 453)

Unify VISION: 4GL Reference

dde_get_response$( )
System function: DDE

Windows only

Syntax

dde_get_response$(handle, time_out)

Support

The dde_get_response$( ) system function is supported for Windows only.

Arguments

handle

(NUMERIC) The result parameter that was returned from the

dde_initiate_hot_link$( ), dde_send_data$( ), or
dde_send_command$( ) system functions. The value in this variable
uniquely identifies a request. After the request is retrieved by the
dde_get_response$( ) system function, the handle is invalid.

time_out

(NUMERIC) Number of milliseconds that VISION Runtime Manager

should wait for a reply from the server.

Description

The dde_get_response$( ) system function is used to retrieve the response for DDE
requests that were made through the dde_initiate_hot_link$( ), dde_send_data$( ),
and dde_send_command$( ) system functions.
If the previous calls return DDE_TIMEOUT, the dde_get_response$( ) system
function can be called multiple times with the same handle.

Return
values

DDE_SUCCESS

(NUMERIC) The DDE request was received successfully and can be

carried out.
DDE_NEGACK (NUMERIC) The server cannot carry out the DDE request or does not

need the data.

DDE_TIMEOUT

(NUMERIC) The server did not reply by the end of the specified
number of milliseconds (time_out).
Chapter 6: System functions

457

DDE_NOLINK (NUMERIC) The handle that was passed to this system function is not

valid.
For a complete list of values that can be returned by the DDE system functions, see the
dde_codes.h file in the include directory.

Example

In this example, the call to dde_get_response$( ) is in a global function,

handleResponse, that handles values returned by dde_get_response$( ). The entire
handleResponse function is not shown because it is quite long, but the first part of the
function is included for context.
/********************************************************************
*
response.fs
********************************************************************/
#include <ddecodes.h>
#include <ddestuff.h>
EXTERN SCRIPT STRING FUNCTION strCat(val, val, val, val, val)
EXTERN SCRIPT VOID FUNCTION dispErr(val, val, val)
BOOL FUNCTION handleResponse( handle, funcstat, timeout, func_type )
PRIVATE errstr,
/* error string */
timeoutstr,
/* error message for timeout */
nolinkstr,
/* error message for DDE_NOLINK */
poststr,
/* error message for DDE_POSTFAIL */
getResp,
/* if TRUE, get the response again */
status
/* status return from dde_get_response$ */
BEGIN
. . .
SET $getResp TO TRUE
While ($getResp = TRUE)
BEGIN
/*
* get the response from the request specified by
* $handle
*/
SET $status TO dde_get_response$($handle, $timeout)
. . .

See also

458

System functions
dde_get_data$( ) (page 451)
dde_initiate_hot_link$( ) (page 459)
dde_send_command$( ) (page 468)
dde_send_data$( ) (page 470)

Unify VISION: 4GL Reference

dde_initiate_hot_link$( )
System function: DDE

Windows only

Syntax

dde_initiate_hot_link$(server_link_ID, item, RESULT handle)

Support

The dde_initiate_link $( ) system function is supported for Windows only.

Arguments

server_link_ID (NUMERIC) Server identifier that was returned by the

dde_initiate_link$( ) system function.
item

(STRING) Name of the data item needed by the client. The item value
is received through a receive_data DDE event handler global function
installed by the INSTALL statement.
The server sends the item value to the client whenever the value
changes.

handle

Description

(NUMERIC) A RESULT parameter that uniquely identifies this

request. The handle is passed to the dde_get_response$( ) system
function.

The dde_initiate_hot_link$( ) function posts the message to the DDE server. This
function can be called only after a link has been established through the
dde_initiate_link$( ) system function. The dde_initiate_hot_link$( ) function
requests that a hot link be established between the specified DDE server application
and the Unify VISION application that is acting as the DDE client.
You must use the dde_get_response$( ) system function to retrieve the result of the
dde_initiate_hot_link$( ) function.
After the hot link is established, the DDE server application sends the value of the
specified data item to the Unify VISION application whenever the value changes, but
only if a receive_data DDE event handler function has been installed. If a receive_data
DDE event handler function has not been installed, the data cannot be received.

Chapter 6: System functions

459

The application must be acting as a DDE client to call the dde_initiate_hot_link$( )

function.

Return
values

DDE_SUCCESS

(NUMERIC) The initiate_hot_link message was successfully posted to

the DDE server.
DDE_HOTEXISTS
(NUMERIC) A hot link already exists for the requested item.
DDE_HOTPENDING
(NUMERIC) A request for a hot link for this item is currently pending

acknowledgement.
DDE_OUTOFMEM
(NUMERIC) VISION Runtime Manager had insufficient memory to

complete this request.

DDE_POSTFAIL

(NUMERIC) The initiate hot link message could not be posted to the
DDE server.
DDE_NOLINK (NUMERIC) The link ID that was passed to this system function is not

valid.

Example

In this example, a global function named initHotLnk is used to initiate a hot link by
calling the dde_initiate_hot_link$( ) system function and handling any errors that
may occur.
/********************************************************************
*
inithot.fs
********************************************************************/
#include <ddecodes.h>
#include <ddestuff.h>
EXTERN ACCELL VOID FUNCTION
EXTERN ACCELL VOID FUNCTION
EXTERN ACCELL BOOL FUNCTION

dispErr(val, val, val)

updStatus(val)
handleResponse(val, val, val, val)

VOID FUNCTION initHotLnk(linkInx, app, top, item)

PRIVATE lnkid, /* server link id that identifies DDE conversation */
status, /* return status from dde_initiate_link$() */
handle, /* handle */
matrix dde_links[1 TO unknown, 1 TO 5] /* DDE link info */

460

Unify VISION: 4GL Reference

BEGIN
IF ($linkInx IS UNDEFINED OR
$linkInx IS NULL OR
$linkInx < 1 ) THEN
BEGIN
dispErr(DDE Error,
Invalid application/topic names,
$nullstr)
RETURN ()
END
IF ($item IS UNDEFINED OR
$item IS NULL OR
$item = ) THEN
BEGIN
dispErr( DDE Error,
Invalid item name.,
$nullstr)
RETURN ()
END
/* get a list of all the active DDE links */
dde_get_links$( $dde_links )
/* initiate the hot link for the item specified by the user */
SET $status TO dde_initiate_hot_link$( $dde_links[$linkInx,2],
$item,$handle)
IF (handleResponse($handle, $status, 5000, DDEINITHOT) = TRUE )
THEN
BEGIN
updStatus( Hot Link Initiated with: + $app + + $top +
on: + $item )
END
END

See also

System functions
dde_get_response$( ) (page 457)
dde_initiate_link$( ) (page 462)

Chapter 6: System functions

461

dde_initiate_link$( )
System function: DDE

Windows only

Syntax

dde_initiate_link$(application, topic, RESULT server_link_ID)

Support

The dde_initiate_link$( ) system function is supported for Windows only.

Arguments

application

(STRING) Name of the application that the client wants to address as a

DDE server. Example application names include Excel, Word,
Server, or AMGR.

topic

(STRING) Name of a set of related items from which the client will
eventually request an item. For example, Unify VISION topics include
table names and form names.

server_link_ID (RESULT parameter) This argument must be a variable name. If

VISION Runtime Manager successfully establishes a link with another
application, this variable receives the servers link identifier.

Description

The dde_initiate_link$( ) function broadcasts a message to all active windows that a

DDE link is needed with the specified application for the specified topic. If a DDE link
is established, the server_link_ID result parameter receives the server applications
link ID.
The server_link_ID value will be passed to other system functions, such as
dde_initiate_hot_link$( ) and dde_request_data$( ).
The Unify VISION application must be acting as a DDE client application to call the
dde_initiate_link$( ) function.

Return
values
462

DDE_SUCCESS (NUMERIC) The link was established successfully.

Unify VISION: 4GL Reference

DDE_NEGACK

(NUMERIC) No DDE server exists for this request.

DDE_OUTOFMEM
(NUMERIC) VISION Runtime Manager had insufficient memory to

complete this request.

Example

In this example, a global function named initLink is used to initiate a link by calling
the dde_initiate_link$( ) system function and handling return values.
/********************************************************************
*
initlink.fs
********************************************************************/
#include <ddecodes.h>
EXTERN SCRIPT VOID FUNCTION
EXTERN SCRIPT VOID FUNCTION

dispErr(val, val, val)

updStatus(val)

VOID FUNCTION initLink( app, top )

PRIVATE lnkid, /* server link id that identifies DDE conversation */
errstr, /* error message */
status /* return status from dde_initiate_link$( ) */
BEGIN
IF ($app IS UNDEFINED OR $app IS NULL) THEN
BEGIN
SET $app TO
END
IF ($top IS UNDEFINED OR $top IS NULL) THEN
BEGIN
SET $top TO
END
IF ($app = AND $top = ) THEN
BEGIN
RETURN ( )
END
/* Broadcast the initiate link message to all windows */
SET $status TO dde_initiate_link$($app, $top, $lnkid)
SWITCH $status
BEGIN
CASE DDE_SUCCESS:
updStatus(Link Initiated with: + $app + + $top)

Chapter 6: System functions

463

CASE DDE_NEGACK:
dispErr(DDE Error,
Could not initiate a DDE link with: + $app + + $top,
$nullstr)
CASE DDE_OUTOFMEM:
dispErr( DDE Error,
Ran out of memory initiating link with: + $app + + $top,
$nullstr)
END
END

See also

464

System functions
dde_initiate_hot_link$( ) (page 459)
dde_request_data$( ) (page 465)

Unify VISION: 4GL Reference

dde_request_data$( )
System function: DDE

Windows only

Syntax

dde_request_data$(server_link_ID, item, RESULT handle)

Support

The dde_request_data$( ) system function is supported for Windows only.

Arguments

server_link_ID
(NUMERIC) Server identifier that was returned by the
dde_initiate_link$( ) system function.

Description

item

(STRING) Name of the data item needed by the client. If the server
sends the value for the data item the value is placed in the result_data
variable.

handle

(NUMERIC) Numeric RESULT parameter that uniquely identifies this

request. The handle is passed to the dde_get_data$( ) system function
to retrieve the result of this request.

This function can be called only after a link has been established with a DDE server
through the dde_initiate_link$( ) function. The dde_request_data$( ) function
merely requests the value of specified data item.
The dde_get_data$( ) system function must be used to retrieve the data that is sent by
the DDE server. If the server application sends the value of the data item, places the
value is placed in the dde_get_data$( ) result_data variable.
The application must be acting as a DDE client to call the dde_request_data$( )
function.

Return
values

DDE_SUCCESS

Chapter 6: System functions

(NUMERIC) The request for data was posted successfully.

465

DDE_OUTOFMEM
(NUMERIC) VISION Runtime Manager had insufficient memory to

complete this request.

DDE_POSTFAIL

(NUMERIC) The request data message could not be posted to the DDE
server.
DDE_NOLINK (NUMERIC) The server link ID that was passed to this system function

is not valid.

Example

In this example, a global function named requestItem is used to request data from a
link by calling the dde_request_data$( ) system function and handling return values.
/********************************************************************
*
reqitem.fs
********************************************************************/
#include <ddecodes.h>
#include <ddestuff.h>
EXTERN SCRIPT VOID FUNCTION
EXTERN SCRIPT VOID FUNCTION
EXTERN SCRIPT BOOL FUNCTION

dispErr(val, val, val)

updStatus(val)
handleRequest(val, val, val, REFERENCE val)

VOID FUNCTION requestItem( linkInx, app, top, item )

PRIVATE lnkid, /* server link id which identifies DDE conversation */
status, /* return status from dde_request_data$( ) */
handle, /* handle */
data, /* variable to hold data requested */
matrix dde_links[ 1 TO unknown, 1 TO 5] /* DDE link info */
BEGIN
IF ($linkInx IS UNDEFINED OR
$linkInx IS NULL OR
$linkInx < 1) THEN
BEGIN
dispErr(DDE Error,
Invalid application/topic names,
$nullstr)
RETURN ( )
END
IF ($item IS UNDEFINED OR
$item IS NULL OR
$item = ) THEN
BEGIN
dispErr(DDE Error,
Invalid item name.,
$nullstr)
RETURN ( )
END

466

Unify VISION: 4GL Reference

/* get a list of all the active DDE links */

dde_get_links$($dde_link )
/* request data for the item specified by the user */
SET $status TO
dde_request_data$($dde_links[$linkInx,2], $item, $handle)
IF (handleRequest($handle, $status, 5000, $data) = TRUE) THEN
BEGIN
updStatus(Received data from: + $app + for: +
$item + : + $data)
END
END

See also

System functions
dde_get_data$( ) (page 451)
dde_initiate_link$( ) (page 462)

Chapter 6: System functions

467

dde_send_command$( )
System function: DDE

Windows only

Syntax

dde_send_command$(server_link_ID, command, RESULT handle)

Support

The dde_send_command$( ) system function is supported for Windows only.

Arguments

server_link_ID (NUMERIC) Server identifier that was returned by the

dde_initiate_link$( ) system function.

Description

command

(STRING) Name of the command to be executed by the DDE server

application.

handle

(NUMERIC) Numeric RESULT parameter that uniquely identifies this

request. This handle is passed to the dde_get_response$( ) system
function to retrieve the result of this request.

The dde_send_command$( ) system function requests that the specified DDE server
execute the specified command. The functions return status indicates whether the
command was successfully executed.
The Unify VISION application must be acting as a DDE client to call the
dde_send_command$( ) system function.

Return
values

DDE_SUCCESS

(NUMERIC) The command was posted successfully.

DDE_OUTOFMEM
(NUMERIC) VISION Runtime Manager had insufficient memory to

complete this request.

DDE_POSTFAIL

(NUMERIC) The send command message could not be posted to the

DDE server.
468

Unify VISION: 4GL Reference

DDE_NOLINK (NUMERIC) The link ID that was passed to this system function is not

valid.
DDE_CMDPENDING
(NUMERIC) A send command message is already waiting for a

command receipt response. Before a new command can be sent, the

response must be cleared by running the dde_get_response$( )
system function.

See also

System functions
dde_get_response$( ) (page 457)
dde_initiate_link$( ) (page 462)

Chapter 6: System functions

469

dde_send_data$( )
System function: DDE

Windows only

Syntax

dde_send_data$( { client_link_ID | server_link_ID }, item, data, RESULT handle)

Support

The dde_send_data$( ) system function is supported for Windows only.

Arguments

client_link_ID (NUMERIC) Client identifier that was passed to the Unify VISION
application through an initiate_hot_link DDE event handler global
function installed by the INSTALL statement or returned from the
dde_initiate_link$( ) system function. If the Unify VISION
application is acting as a DDE server, it can send data only to clients
that have established a hot link with the current application.
server_link_ID (NUMERIC) Server identifier that was returned by the
dde_initiate_link$( ) system function. In this case, the Unify VISION
application is acting as a DDE client.

Description

470

item

(STRING) Name of the data item that is being passed in the data
parameter.

data

(STRING) The data to be passed to the client application. This data

can be of any data type but will be converted to TEXT before it is
passed to the receiving DDE application.

handle

(NUMERIC) Numeric RESULT parameter that uniquely identifies this

request. The handle is passed to the dde_get_response$( ) system
function to retrieve the result of this request.

If the Unify VISION application is acting as a DDE server, the dde_send_data$( )

system function sends a data item value to a client application that has established a
hot link with the application. If the Unify VISION application is acting as a DDE client,
the dde_get_response$( ) system function retrieves the value of the specified data
item.
Unify VISION: 4GL Reference

When data is sent to a DDE client or DDE server, the receiver of the data must respond
that the data was received and accepted. The function cannot send more data before
the receiver responds that the data has been received. Use the dde_get_response$( )
system function to obtain the data receipt response from the receiving application.
The Unify VISION application can be either a client or a server.

Return
values

DDE_SUCCESS

(NUMERIC) The data was sent.

DDE_OUTOFMEM
(NUMERIC) VISION Runtime Manager had insufficient memory to

complete this request.

DDE_POSTFAIL

(NUMERIC) The send data message could not be posted to the DDE
server.
DDE_NOLINK (NUMERIC) The link ID that was passed to this system function is not

valid.
DDE_SNDPENDING
(NUMERIC) A send data message is already waiting for a data receipt

response. Before new data can be sent, the response must be cleared
by running the dde_get_response$( ) system function.

Example

In this example, the call to dde_send_data$( ) is in a global function named

sendData. The sendData finds all the active hot links and determines whether a hot
link is active for the item specified. If a hot link is active for the item, the function
sends the items value to the DDE client. The sendData function should be called from
the WHEN FIELD CHANGES methods of the fields on which you will support hot
links.
/********************************************************************
*
senddata.fs
********************************************************************/
#include <ddecodes.h>
#include <ddestuff.h>

Chapter 6: System functions

471

EXTERN SCRIPT BOOL FUNCTION

handleResponse(val, val, val, val)

VOID FUNCTION sendData(itemMask, data)

PRIVATE jnx, /* loop index */
handle, /* response handle */
status, /* status returned from dde_send_data$( ) */
numhotlinks, /* number of active DDE hot links */
matrix dde_hot_links[1 TO unknown, 1 TO 4] /* hot link info */
BEGIN
/*
* fill the array $dde_hot_links with the information about all
* of the currently active hot links
*/
SET $numhotlinks TO dde_get_hot_links$($dde_hot_links)
/*
* search the array $dde_hot_links for a link that is a DDE server
* and has a hot link on $item
*/
FOR (SET $jnx TO 1 ; $jnx <= $numhotlinks ; SET $jnx TO $jnx + 1)
BEGIN
IF ($dde_hot_links[$jnx,4] SHLIKE $itemMask AND
$dde_hot_links[$jnx,1] = server) THEN
BEGIN
/* Send the data to the DDE client */
SET $status TO dde_send_data$( $dde_hot_links[$jnx, 3],
$dde_hot_links[$jnx,4],
$data,
$handle )
/*
* pop the response returned from the DDE client off
* the queue
*/
handleResponse($handle, $status, 5000, DDESENDDATA)
END /* IF */
END /* FOR loop */
END /* FUNCTION sendData( ) */

See also

472

System functions
dde_get_response$( ) (page 457)
dde_initiate_link$( ) (page 462)

Unify VISION: 4GL Reference

dde_terminate_hot_links$( )
System function: DDE

Windows only

Syntax

dde_terminate_hot_links$( { client_link_ID | server_link_ID }, item, RESULT

handle)

Support

The dde_terminate_hot_links$( ) system function is supported for Windows only.

Arguments

client_link_ID (NUMERIC) Client identifier that was passed to Unify VISION through
an initiate_link DDE event handler global function installed by the
INSTALL statement. In this case, the Unify VISION application is
acting as a DDE server.
server_link_ID (NUMERIC) Server identifier that was returned by the
dde_initiate_link$( ) system function. In this case, the Unify VISION
application is acting as a DDE client.

Description

item

(STRING) Name of the data item that is being received by the client
whenever the value changes.

handle

(NUMERIC) A RESULT parameter that uniquely identifies this

request. The handle is passed to the dde_get_response$( ) system
function.

This function can be called only after a link has been established by the
dde_initiate_link$( ) function and a hot link has been established by the
dde_initiate_hot_link$( ) function. The dde_terminate_hot_link$( ) function
requests that a hot link be terminated.
After the dde_terminate_hot_link$( ) function is called and the link is terminated,
Unify VISION ignores all subsequent values received from the server for the specified
data item.
The Unify VISION application can be acting as either a client or server to call the
dde_terminate_hot_link$( ) function.

Chapter 6: System functions

473

Return
values

DDE_SUCCESS

(NUMERIC) The hot link was terminated successfully.

DDE_POSTFAIL

(NUMERIC) The terminate hot link message could not be posted to the
DDE server.
DDE_NOLINK (NUMERIC) The server link ID that was passed to this system function

is not valid.

See also

474

System functions
dde_initiate_hot_link$( ) (page 459)
dde_initiate_link$( ) (page 462)

Unify VISION: 4GL Reference

dde_terminate_link$( )
System function: DDE

Windows only

Syntax

dde_terminate_link$( { client_link_ID | server_link_ID } )

Support

The dde_terminate_link$( ) system function is supported for Windows only.

Arguments

client_link_ID (NUMERIC) Client identifier that was passed to the Unify VISION
application through an initiate_link DDE event handler global function
installed by the INSTALL statement.
server_link_ID (NUMERIC) Server identifier that was returned by the
dde_initiate_link$( ) system function.

Description

The dde_terminate_link$( ) system terminates a DDE link with a client or server

application. After this function is executed, all subsequent messages received from the
specified client or server application are ignored.
The Unify VISION application can be acting as either a DDE client or server to call the
dde_terminate_link$( ) function.

Return
values

DDE_SUCCESS

(NUMERIC) The link was terminated successfully.

DDE_POSTFAIL

(NUMERIC) The terminate link message could not be posted to the

DDE server or client.
DDE_NOLINK (NUMERIC) The link ID that was passed to this system function is not

valid.

Example

In this example, a global function named termLink terminates a link by calling the
dde_terminate_link$( ) system function and handling errors that may occur.

Chapter 6: System functions

475

/********************************************************************
*
termlink.fs
********************************************************************/
#include <ddecodes.h>
EXTERN SCRIPT VOID FUNCTION
EXTERN SCRIPT VOID FUNCTION

dispErr(val, val, val)

updStatus(val)

VOID FUNCTION termLink(linkInx, app, top)

PRIVATE lnkid, /* server link id that identifies DDE conversation */
errstr, /* error message */
status, /* return status from dde_initiate_link$( ) */
matrix dde_links[1 TO unknown, 1 TO 5] /* DDE link info */
BEGIN
IF (linkInx IS UNDEFINED OR
$linkInx IS NULL OR
$linkInx < 1) THEN
BEGIN
dispErr(DDE Error,
Invalid application/topic names,
$nullstr)
RETURN ( )
END
/* get a list of all the active DDE links */
dde_get_links$($dde_links)
/* terminate the link specified by the user */
SET $status TO dde_terminate_link$($dde_links[$linkInx,2])
IF ($app IS UNDEFINED OR
$app IS NULL) THEN
BEGIN
SET $app TO
END
IF ($top IS UNDEFINED OR
$top IS NULL) THEN
BEGIN
SET $top TO
END
/* Deal with the return status from the dde_terminate_link$( )
* system function */
SWITCH $status
BEGIN
CASE DDE_SUCCESS:
updStatus(Link Terminated for: + $app + + $top)
CASE DDE_NOLINK:
dispErr(DDE Programmer Error,
The DDE link you are attempting to terminate,
no longer exists or has never existed.)

476

Unify VISION: 4GL Reference

CASE DDE_POSTFAIL:
dispErr(DDE Error,
Link termination was unsuccessful,
Windows could not post the message)
END
END

See also

System functions
dde_initiate_link$( ) (page 462)

Chapter 6: System functions

477

display_tooltips$( )
System function: specify whether tooltips display

Syntax

display_tooltips$( display_tooltip_state )

Arguments

display_tooltip_state
(BOOLEAN) Specifies whether tooltips are displayed (TRUE) or not
displayed (FALSE). The default is TRUE.

Return
values

None.

Description

The display_tooltips$( ) system function specifies whether tooltips are displayed for
the any objects in an application. By default, tooltips display for the associated object
providing that the tooltip text is defined by the TOOLTIP attribute. If the TOOLTIP
attribute is set to the empty string, no tooltip is displayed.

Example

The following example allows a user to turn tooltips on or off at runtime by pressing a
button associated with the toggleTooltips command:
COMMAND toggleTooltips
begin
set doTooltips to not $doTooltips;
display_tooltips$($doTooltips);
end

Related information

478

For information about tooltips, see VISION Development Environment

preferences in Unify VISION: Developing an Application, and Working
with form classes in Unify VISION: Designer.

Unify VISION: 4GL Reference

encrypt_db_password$( )
System function: encrypt a string

Syntax

encrypt_db_password$( password )

Arguments

password

A string that represents the user password to be encrypted.

Return
values

(STRING)

An encrypted password. A null string is returned if an error occurs in

the function execution.

Description

The encrypt_db_password$( ) system function returns an encrypted password. This

system function can be used to write a site-specific login screen for Unify DataServer
databases.

Example

This example uses the encrypt_db_password$( ) function on a form with two text
fields, one for username and one for password.
SET $encrypted TO encrypt_db_password$( $pwdField );
SET $conName TO con + to_string$($conIndex);
CREATE CONNECTION $conName of CLASS pits
DBUSER IS $userField,
DBPASSWORD IS $encrypted;
SET $conIndex TO $conIndex + 1;
CREATE FORM $conName OF CLASS bug USING CONNECTION $conName;

Chapter 6: System functions

479

end_ams_tx$( )
System function: end AMS transaction

UNIX only

Unify AppMan only

Syntax

end_ams_tx$( handle )

Support

The end_ams_tx$( ) system function is supported only for applications that are
configured for use with a Unify AppMan transaction tracking agent. If used in an
application that is not configured for Unify AppMan, this system function has no
effect.

Arguments

handle

Return
values

(BOOLEAN)

(NUMERIC) The parameter that was returned from a

begin_ams_tx$( ) system function.

TRUE

The AMS transaction has been successfully ended.

FALSE

The attempt to end an AMS transaction has failed. The failure is

logged in the file specified by the AMGR_ERFL external preference.

Description

The end_ams_tx$( ) system function ends an AMS transaction. When an AMS

transaction is ended, data is reported to the transaction tracking application. After
executing the end_ams_tx$( ) system function, the handle parameter is NULL.

See also

System functions
abort_ams_tx$( ) (page 404)
begin_ams_tx$( ) (page 412)

For information about application management, see Unify AppMan: Managing

Related
information Applications.

480

Unify VISION: 4GL Reference

explicit_mode$( )
System function: set search mode

Syntax

explicit_mode$( explicit_mode_state )

Arguments

explicit_mode_state
(BOOLEAN) Specifies whether explicit search mode is to be enabled
(TRUE) or the default search mode (FALSE).

Return
values

(BOOLEAN)

Description

TRUE

The search mode indicated by explicit_mode_state was successfully

enabled.

FALSE

The search mode indicated by explicit_mode_state was not

successfully enabled. Explicit_mode_state is not a valid BOOLEAN
value or is undefined.

The explicit_mode$( ) system function sets the search mode that VISION Runtime
Manager uses when it searches for STRING values. The initial search mode is
determined by the setting of the EXPL_MODE preference. You can use the
explicit_mode$( ) system function to change the initial setting on a form-by-form
basis.
If explicit_mode_state is TRUE, explicit search mode is used for string searches. In
explicit search mode, VISION Runtime Manager searches for strings that match the
search criteria exactly. If explicit_mode_state is FALSE, VISION Runtime Manager
uses the default search mode for string searches. In default search mode, VISION
Runtime Manager searches for all strings that begin with the string specified in the
search criteria. However, if the string is associated with a STRING database column
that is a primary key, explicit search mode is used.
You can achieve field-by-field control of the search mode by setting
explicit_mode$( ) to TRUE in the ON CLEAR TO FIND section; then append an
asterisk to the SEARCH_RANGES value of specific fields in the BEFORE FIND
section, for example:
SET co_name TO co_name:SEARCH_RANGES + *

Chapter 6: System functions

481

Example

This example tells VISION Runtime Manager to use the default search mode for all
searches on this form.
METHOD BEFORE PAGE
IF ( explicit_mode$(FALSE) ) THEN
DISPLAY Searches on this form are performed in default search mode
FOR FYI_MESSAGE WAIT
ELSE
DISPLAY Internal error: unable to set search mode
FOR FYI_MESSAGE WAIT

Related
information

See External preferences syntax descriptions in Unify VISION: Application

Reference for information about related external preferences:
EXPL_MODE

See for information about the following related attribute:

Attributes
SEARCH_RANGES

482

Unify VISION: 4GL Reference

first_visible_record_number$( )
System function: returns the first record of a selected set

Syntax

first_visible_record_number$( )

Return
values

(NUMERIC)

Description

>0

The record number of the first visible record in the selected set.

NULL

There is no current record or the form is in find mode.

The first_visible_record_number$( ) system function obtains the numerical record

number (its position within the selected set) of the first visible record in a selected set
for the current form.
Using the result of this function with the number of occurrences helps you to
determine which records are displayed at a given time.

Example

This example uses the first_visible_record_number$( ) system function to display

the record number to the FYI_MESSAGE field:
SET $tmpVar TO first_visible_record_number$();
IF ($tmpVar IS NULL ) THEN
BEGIN
DISPLAY Error: No selected set, first_visible_record_number$() is NULL
FOR FYI_MESSAGE WAIT;
END;
ELSE
BEGIN
DISPLAY First Visible Row is + to_string$($tmpVar)
FOR FYI_MESSAGE WAIT;
END;

Chapter 6: System functions

483

flush_to_disk$( )
System function: Process control

UNIX only

Syntax

flush_to_disk$( )

Support

The flush_to_disk$( ) system function is supported only for the UNIX operating
system.

Return
values

None.

Description

The flush_to_disk$( ) system function forces changed file blocks to disk.

UNIX

The flush_to_disk$( ) system function calls the sync( ) operating system function. For
information about sync( ), refer to the UNIX operating system reference manuals.

484

Unify VISION: 4GL Reference

get_line_of_text$( )
System function: retrieve text

Syntax

get_line_of_text$( text_value, line_number )

Arguments

(TEXT)
text_value

A value of type TEXT.

line_number

The number of a line within text_value. Its value for the first line of
text is 1.

Return
values

(TEXT)

A TEXT value is returned. If line_number exceeds the length of the

text, the value returned is UNDEFINED.

Description

The get_line_of_text$( ) system function retrieves the specified line of text from
text_value.

Example

This example creates a report with line numbers.

SET $inx TO 1
SET $text_line to get_line_of_text$($stats, $inx)
WHILE $text_line IS NOT UNDEFINED
BEGIN
SET $tmp_text TO Line # + to_string$($inx) + : + $text_line
WRITE PIPELINE $stats_rpt $tmp_text
SET $inx TO $inx + 1
SET $text_line TO get_line_of_text$($memo, $inx)
END

Chapter 6: System functions

485

get_message$( )
System function: retrieve message

Syntax

get_message$( message_number )

Arguments

message_number
(NUMERIC) The integer message number of the message to be
retrieved from the message file.

Return
values

(STRING)

The message string corresponding to message_number.

UNDEFINED

message_number was not numeric or was undefined.

NULL

message_number is NULL.

Description

The get_message$( ) system function retrieves a message from the current message
file. The get_message$( ) function looks for a line in the message file that begins with
the number message_number. If message_number is a null value, get_message$( )
produces a runtime error.
A message file must first be opened with the open_message_file$( ) function before
get_message$( ) can retrieve messages. To close the message file, you must use the
close_message_file$( ) system function.
Using a message file instead of embedding the messages in your code significantly
reduces memory usage at runtime as well as simplifying code maintenance. Message
files are also very useful for internationalizing your application.

Example

A message file named /usr/apps/messages includes the following lines:

98
99
100
101

486

|
|
|
|

Invalid entry, please try again!

Inventory number out of range
Record not updated!
Record updated and stored!

Unify VISION: 4GL Reference

UNIX

In the following example, if the /usr/apps/messages message file can be opened,

get_message$( ) retrieves message 100.
IF ( open_message_file$(/usr/apps/messages) = 0 ) THEN
BEGIN
DISPLAY get_message$(100) FOR FYI_MESSAGE WAIT
close_message_file$()
END

If get_message$( ) is successful, it displays message 100 in the fyi_message system

information field:
Record not updated!

See also

System functions
close_message_file$( ) (page 486)
open_message_file$( ) (page 510)

Chapter 6: System functions

487

get_password$( )
System function: retrieve password

DBMS dependent

Syntax

get_password$( )

Support

Support for this feature is DBMS dependent.

INFORMIX

Supported.

INGRES

This function returns UNDEFINED.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

This function returns UNDEFINED.

Return
values

Description

(STRING)

The current users database password.

UNDEFINED

The password cannot be determined.

The get_password$( ) function returns the password that was used to log in to the
database. The password is identified by the DBPASSWORD preference.
The get_password$( ) system function returns the password of the connection defined
for the current form, not for the last executed connection.

See also

Related
information

System functions
group_id$( ) (page 494)
group_name$( ) (page 495)

user_id$( ) (page 600)

user_name$( ) (page 601)

For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
DBPASSWORD

488

Unify VISION: 4GL Reference

getenv$( )
System function: get value of preference

Syntax

getenv$( preference )

Arguments

preference

Return
values

(STRING)

Description

(STRING) A string containing the name of the environment variable or

external preference with the value you need.

value

The value of the preference (set at the operating system command

level or in an application preference file).

UNDEFINED

preference is set neither in the operating system environment nor in an

application preference file.

The getenv$( ) system function obtains the operating system level value of the
variable specified by the preference argument.
If the preference argument is of the form $variable, the value of variable is obtained
as follows:
First, the [Environment] section of the associated preference file is searched for a
setting of variable. If variable is found, its value is returned. If variable is not found,
the operating system environment is searched for a setting of variable. If variable is
found, its value is returned. If variable is not found, getenv$( ) returns UNDEFINED.
This function is useful for checking the value of preferences in the users environment
and programming behavior based on their values.

Example

For example, the following application profile contains these entries:

[Configuration]
ACLDDBDBG=$ACLDBDBG
EXPL_MODE=$EXPLICIT_MODE
WIDTH=80

Chapter 6: System functions

489

The following environment file contains these entries:

SET ACLDBDBG=c:\db.out
SET EXPLICIT_MODE=TRUE
SET WIDTH=50
PATH=C:\WINDOWS;C:\VISION\BIN

The script contains the following method:

METHOD ON CURRENT
SET debug_mode TO getenv$(ACLDBDBG)
SET exp_mode_value TO getenv$(EXPL_MODE)
SET report_width TO getenv$(WIDTH)
SET path TO getenv$(PATH)
SET X TO getenv$(x)

At runtime, the following events occur:

The debug_mode variable is set to c:\db.out.
The exp_mode_value variable is set to TRUE.
The report_width variable is set to 80.
The path variable is set to the environment variable value
C:\WINDOWS;C:\VISION\BIN. Because PATH is not a Unify VISION external
preference, its value is obtained from the users environment.
The x variable is set to UNDEFINED because x is not a Unify VISION external
preference and it is not set in the environment.
Because there is no entry in the application preference file pointing to the
environment, the SET WIDTH entry in the environment file is ignored. The developer
could enter either of the following entries to the application preference file to get the
value of the WIDTH external preference:
[Configuration]
WIDTH=50

or
[Configuration]
WIDTH=$WIDTH

where WIDTH is set in the environment:

SET WIDTH=50

For information about application preference files, see Deploying the application in
Related
information Unify VISION: Developing an Application.

490

Unify VISION: 4GL Reference

glob_str_compare$( )
System function: compare variable with mask

Syntax

glob_str_compare$( variable, mask )

Arguments

variable

(STRING/TEXT) The string or text to be compared.

mask

(STRING) A string containing the metacharacters and characters of the

search pattern.

Return
values

Description

(BOOLEAN)
TRUE

variable value matches the mask.

FALSE

variable value does not match the mask, or variable value is a null
string, or mask is a null string.

The glob_str_compare$( ) system function compares a variable value with a special

string mask. This mask describes the strings that are valid. If variable value matches
any of the strings described by the mask, glob_str_compare$( ) returns a value of
TRUE.
With glob_str_compare$( ) you use a special string specification notation to create a
pattern mask. The mask string is made up of string metacharacters and characters.
String metacharacters have a special meaning within the search pattern. They describe
certain matching patterns.
All ordinary characters (all characters except *, ?, [, ], , and \) match themselves. To
describe a string that includes a metacharacter as an actual character, precede the
occurrence of the metacharacter with a backslash (\). This backslash overrides the
metacharacter meaning of the character that follows.

Chapter 6: System functions

491

If a search string includes a single left bracket ([) or a single right bracket (]) character,
the bracket does not not need to be preceded by a backslash. Unmatched bracket
characters are evaluated as literal characters, as shown in the following examples:
Search string

Results

*]bc

fg]bc
]bc

[ABC]]

A]
B]
C
This search string does not find a string that consists only of a single
bracket.

The following table defines the string specification metacharacters for

glob_str_compare$( ).
String specification metacharacters
Symbol

Example

Results

Any single character ABC?

Any string of four characters

that starts with ABC: ABCD,
ABCE, ABC1, and so on

A*C
Any string of
characters, including
zero length strings

Any string that begins with A

and ends with C: AC, AaC,
ABC, A123C, AaaaaC, and so
on

[]

Any character from

among the list of
characters specified
within the brackets

A[BCD]E

A range of values
(inclusive)

[58]

Any of the characters 5, 6, 7, or

8

[az]

Any lowercase character

Example

Matches

String values: ABE, ACE, and

ADE

In this example, glob_str_compare$( ) compares a_strng and the mask for a string of
three digits.
IF ( glob_str_compare$(a_strng, [09][09][09]) ) THEN
DISPLAY Matched String! FOR FYI_MESSAGE WAIT

492

Unify VISION: 4GL Reference

When the variable a_strng contains a string of three digits, the code sample displays
the following message in the fyi_message system information field.
Matched String!

See also

System functions
reg_exp_str_compare$( ) (page 522)

Chapter 6: System functions

493

group_id$( )
System function: retrieve group ID

UNIX only

Syntax

group_id$( )

Support

For Windows this function returns 0.

Return
values

(NUMERIC)

Description

The group_id$( ) system function obtains the users group ID number. This group ID
is obtained from the operating system password file. On most UNIX operating
systems, this password file is /etc/passwd. This function allows you to take advantage
of the security groups already set up by the operating system. You can take actions in
your applications based upon the operating system group to which the particular user
belongs.

Example

In this example, group_id$( ) is used to determine the group ID of the user who is
currently executing the application. If this group ID is equal to 6, the selected row is
rejected and no selected set record is created.

The operating system group ID number of the user.

METHODON FIND
IF ( group_id$() = 6 ) THEN
REJECT RECORD

See also

494

System functions
get_password$( ) (page 488)
group_name$( ) (page 495)

user_id$( ) (page 600)

user_name$( ) (page 601)

Unify VISION: 4GL Reference

group_name$( )
System function: retrieve group name

UNIX only

Syntax

group_name$( )

Support

For Windows this function returns NULL.

Return
values

(STRING)

Description

The group_name$( ) system function obtains the name of the users group. This
function enables you to take advantage of the security groups already set up by the
operating system.

The operating system group name of the user.

You can take actions in your applications based upon the operating system group to
which the particular user belongs.

Example

In this example, group_name$( ) is used to determine the group name of the user who
is currently executing the application. If the user belongs to the group payroll, the user
is allowed to update the employee salary information.
IF ( group_name$() = payroll ) THEN
UPDATE employee
SET emp_salary TO femployee:new_salary
WHERE emp_name = femployee:emp_lname;

See also

System functions
get_password$( ) (page 488)
group_id$( ) (page 494)

Chapter 6: System functions

user_id$( ) (page 600)

user_name$( ) (page 601)

495

is_current_record_stored$( )
System function: check record status

Syntax

is_current_record_stored$( )

Return
values

(BOOLEAN)

Description

TRUE

The current record has been stored; used when in add/update/delete

mode after the row has been written to the database.

FALSE

The current record has not been stored; used when in find mode or in
add/update/delete mode before the row is written to the database.

The is_current_record_stored$( ) system function determines whether the current

record has been stored in the database. It returns TRUE when the form is in
add/update/delete mode and the current record has just been written to its associated
database row.
This function reports that the add/update operation has occurred, regardless of whether
the transaction was committed or rolled back. The function merely indicates whether
the current record was updated in the database.
If this function returns TRUE, an uv_add_update command does not affect the
column values in the target table row because the current record and the target table
row are exactly the same.
If the form is in add/update/delete mode but the current record has not been written to
the database, is_current_record_stored$( ) returns FALSE.
If this function returns FALSE, an uv_add_update does affect the target table row.
After the uv_add_update, the target row is updated with the field values in the
current record or a new row is added.
This function always returns FALSE when the form is in find mode. It also returns
FALSE after the clear-to-find and clear-to-add operations are executed.
This function is useful for determining whether you need to update a database row.

496

Unify VISION: 4GL Reference

Example

In this example, is_current_record_stored$( ) is used to determine whether a

database row is associated with the current record. If there is an associated row, this
database row is updated with the field values in the current record.
METHOD ON DISMISS FORM
IF ( NOT is_current_record_stored$() ) THEN
UPDATE CURRENT RECORD

Chapter 6: System functions

497

l_allow_interrupt$( )
System function: specify interrupt enabling

DBMS dependent

Syntax

l_allow_interrupt$( interrupt_flag )

Support

Support for this feature is DBMS and platform dependent.

UNIX
INFORMIX

The l_allow_interrupt$( ) system function is not supported for

INFORMIX. Therefore, this function always returns FALSE.

INGRES

The l_allow_interrupt$( ) system function is not supported for

INGRES. Therefore, this function always returns FALSE.

ODBC

The l_allow_interrupt$( ) system function always returns FALSE.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

The l_allow_interrupt$( ) system function is not supported for Unify

DataServer. Therefore, this function always returns FALSE.
Windows NT
For Windows NT, the l_allow_interrupt$( ) system function is supported for ORACLE
and SYBASE SQL Server.

Arguments

498

interrupt_flag (BOOLEAN) A flag that indicates whether users can interrupt database
operations.
TRUE

Allow users to interrupt database operations.

FALSE

Do not allow users to interrupt database operations.

Unify VISION: 4GL Reference

Return
values

Description

(BOOLEAN)
TRUE

The function succeeded in changing user interrupt capability.

FALSE

The function failed to change user interrupt capability.

(For example, this can occur when the underlying database does not
support the feature.)

The l_allow_interrupt$( ) system function specifies whether users can interrupt

database operations. By default the interrupt key is the Escape key. If interrupt_flag is
TRUE and the l_allow_interrupt$( ) function is successfully completed, users can
press the interrupt key to halt a database operation that is in progress.
The interrupt command affects all Unify VISION database operations.
By default, the interrupt flag is TRUE. That is, unless you call this function to disable
interrupts, users can always interrupt database operations.
The l_allow_interrupt$( ) system function returns the value returned by the
connection defined for the current form, not for the last executed connection.

See also

System functions
l_wait_time$( ) (page 500)

For information about specifying a different key for the interrupt key, see the
Related
information vision.uvp file in File formats in Unify VISION: Application Reference.

Chapter 6: System functions

499

l_wait_time$( )
System function: specify wait time for locks

Syntax

l_wait_time$( seconds )

Support

Support for this feature is DBMS dependent.

UNIX only

INFORMIX

Supported.

INGRES

Supported. However, because locking depends on SET LOCKMODE,

the results of l_wait_time$( ) do not take effect until the current
transaction is committed and a new transaction is started.

ODBC

The l_wait_time$( ) system function always returns FALSE.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

The l_wait_time$( ) system function is not supported for Unify

DataServer. Therefore, this function always returns FALSE.

Arguments

seconds

Return
values

(BOOLEAN)

500

(NUMERIC) The number of seconds to wait for a lock.

TRUE

The argument passed is a valid number.

FALSE

The argument passed is not a valid number, or this feature cannot be

controlled.
Unify VISION: 4GL Reference

Description

The l_wait_time$( ) function specifies the number of seconds to wait for locks. If a
lock is not obtained before the specified time expires, VISION Runtime Manager
assumes that the object is already locked and abandons the attempt.
When a lock cannot be obtained for an interactive operation, VISION Runtime
Manager displays an error message that indicates that the record is locked. When a
lock cannot be obtained for a non-interactive operation, the status value SS_LMOUT is
returned.
If the number of seconds is zero (0), VISION Runtime Manager waits indefinitely. If
allowed by the DBMS, to escape a waiting condition, the user can press the interrupt
key (Escape). VISION Runtime Manager assumes that a lock conflict has occurred and
ceases waiting for the lock.
The l_wait_time$( ) system function returns the value returned by the connection
defined for the current form, not for the last executed connection.

See also

System functions
l_allow_interrupt$( ) (page 498)

For information about transaction control, see Managing transactions and locks in
Related
information Unify VISION: Developing an Application.
For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
OSEC2WAIT

Chapter 6: System functions

501

last_command$( )
System function: return value of last command

Syntax

#include command.h
last_command$( )

Return
values

502

(NUMERIC)

A NUMERIC value indicating the last executed command. The

following table lists commands and the equivalent return value name:
Command

Return Name

Value

Click on a field
Double click on a field
Set focus on a field
uv_add_update
uv_cancel_form
uv_clear_to_add
uv_clear_to_find
uv_delete
uv_dismiss_form
uv_exit
uv_find
uv_first_record
uv_last_record
uv_next_field
uv_next_form
uv_next_record
uv_next_set
uv_next_tab
uv_previous_field
uv_previous_record
uv_previous_set
uv_previous_tab
uv_return_values
uv_zoom
A developer-defined command

CMD_CONF
CMD_DCLK
CMD_SFCS
CMD_ADUP
CMD_CNFM
CMD_CTOA
CMD_CTOF
CMD_DLRC
CMD_DSFM
CMD_EXIT
CMD_FIND
CMD_FREC
CMD_LREC
CMD_NFLD
CMD_NFRM
CMD_NREC
CMD_NSET
CMD_NTAB
CMD_PFLD
CMD_PREC
CMD_PSET
CMD_PTAB
CMD_RTVL
CMD_ZOOM
CMD_UCMD

100
203
202
0
2
4
5
6
7
10
12
13
14
15
16
17
18
19
21
22
23
24
26
28
4
Unify VISION: 4GL Reference

Description

The last_command$( ) system function returns a numeric value indicating the last
command executed. When checking the last_command$( ) return value, use the
return value name in your script.
To use the last_command$( ) function, you must use the Unify VISION preprocessor
statement, #include, to include the header file command.h in your script. This header
file contains definitions for the last_command$( ) return value names. It is located in
the include directory of the Unify VISION release.
This function is useful within a method that can be initiated by several user
commands. You can use last_command$( ) in the section to determine which user
command has been executed and perform different actions depending on the
last_command$( ) return value.
The last_command$( ) function does not return a value for user commands initiated
with the NEXT ACTION statement.

Example

The ON NEXT RECORD section is executed when the user executes the
uv_next_record, uv_next_set, or uv_last_record commands. In this example,
REJECT OPERATION rejects the uv_last_record command. uv_next_record or
uv_next_set commands cause execution of the statements in ON NEXT RECORD.
The #include statement includes the last_command$( ) header file, command.h.
#include command.h
...
/* Reject the LAST RECORD command but allow NEXT RECORD and NEXT SET */
METHOD ON NEXT RECORD
IF ( last_command$() = CMD_LREC ) THEN
REJECT OPERATION
ELSE
DISPLAY Moving to next set of records FOR FYI_MESSAGE WAIT

See also

Script language
COMMAND
QUEUE COMMAND

Chapter 6: System functions

System functions
last_command_name$( ) (page 504)

503

last_command_name$( )
System function: return name of last command

Syntax

last_command_name$( )

Return
values

(STRING)

A STRING value indicating the last executed command. The following

table lists return values and the equivalent commands:

Return value

Equivalent
predefined command

ADD_UPDATE
CANCEL_FORM
CLEAR_TO_ADD
CLEAR_TO_FIND
DELETE
DISMISS_FORM
EXIT
FIND
FIRST_RECORD
LAST_RECORD
NEXT_FIELD
NEXT_FORM
NEXT_RECORD
NEXT_SET
NEXT_TAB
PREVIOUS_FIELD
PREVIOUS_RECORD
PREVIOUS_SET
PREVIOUS_TAB
ZOOM

uv_add_update
uv_cancel_form
uv_clear_to_add
uv_clear_to_find
uv_delete
uv_dismiss_form
uv_exit
uv_find
uv_first_record
uv_last_record
uv_next_field
uv_next_form
uv_next_record
uv_next_set
uv_next_tab
uv_previous_field
uv_previous_record
uv_previous_set
uv_previous_tab
uv_zoom

For a developer-defined command, the command_name defined in the

COMMAND method is returned.
504

Unify VISION: 4GL Reference

Description

The last_command_name$( ) system function returns a string value indicating the

last command executed.
This function is useful within a method that can be initiated by several user
commands. You can use last_command_name$( ) in the section to determine which
user command has been executed and perform different actions depending on the
last_command_name$( ) return value.
The last_command_name$( ) function does not return a value for user commands
initiated with the NEXT ACTION command.

Example

In this example, a command is defined that moves the cursor to the next field after
setting the current field to a default value. The default value is set in the ON FIELD
method.
FIELD amount
METHOD ON FIELD
BEGIN
INPUT
IF (last_command_name$() = use_default) THEN
BEGIN
SET amount TO 0
END
ELSE
BEGIN
IF (amount IS UNDEFINED) THEN
BEGIN
RESTART ON FIELD
END
END
END
COMMAND use_default
AUD_ACTION IS ENABLED
FIND_ACTION IS ENABLED
NEXT ACTION IS NEXT_FIELD

See also

Script language
COMMAND
QUEUE COMMAND (page 323)

Chapter 6: System functions

System functions
last_command$( ) (page 502)

505

mdy_to_date$( )
System function: convert values to a date

Syntax

mdy_to_date$( month, day, year )

Arguments

month

(NUMERIC) A variable containing the month to be converted to the

DATE value. Must be an integer in the range 1 to 12.

day

(NUMERIC) A variable containing the day to be converted to the

DATE value. Must be an integer in the range 1 to 31.

year

(NUMERIC) A variable containing a 2- or 4-digit year number to be

converted to the DATE value.

Return
values

Description

(DATE)
value

The DATE value corresponding to the month, day, and year values.

UNDEFINED

For undefined or invalid month, day, year.

The mdy_to_date$( ) system function converts three NUMERIC values: month, day,
and year to a DATE value.
This function causes a runtime error if any of the arguments, month, day, or year was a
undefined or invalid value. An example of an invalid day is 35. An example of an
invalid month is 14.

506

Unify VISION: 4GL Reference

Example

In this example, date_to_mdy$( ), mdy_to_date$( ), and current_date$( ) create a

DATE variable with a date of five years from the current date.
SET today_date TO current_date$()
date_to_mdy$(today_date, month, day, year)
SET year TO year + 5
SET five_years TO mdy_to_date$(month, day, year)

See also

System functions
date_to_mdy$( ) (page 440)
str_to_date$( ) (page 561)
to_date$( ) (page 579)

Chapter 6: System functions

507

null_convert$( )
System function: convert null value to default value

Syntax

null_convert$( value, default_value )

Arguments

value

(Any valid type) The expression to be converted to the default_value.

This expression can be of any Unify VISION data type.

default_value

(Any valid type) The default value to be assigned to value if value

currently has a null value.

Return
values

For a null valued value

The value indicated by default_value.
For a non-null valued value
The value indicated by value.

Description

The null_convert$( ) system function converts a null value to a default value. This
function allows you to substitute a non-null value for a null value in an expression.
If the current value of value is the null value, null_convert$( ) returns the value listed
in default_value. If value is a non-null value, this function just returns value.
For a text value, the default value can be either of type STRING or TEXT.

508

Unify VISION: 4GL Reference

Example

In this example, null_convert$( ) ensures that the grade_total variable is never

assigned the null value in the grade calculation. If student_grade is the null value,
null_convert$( ) returns the integer zero (0) and the value zero is added to
grade_total. If student_grade is not the null value, null_convert$( ) just returns the
student_grade value and this value is added to grade_total.
SET $grade_total TO
$grade_total + null_convert$($student_grade, 0)

See also

System functions
str_to_date$( ) (page 561)
str_to_time$( ) (page 564)
str_to_val$( ) (page 565)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)

Chapter 6: System functions

to_date$( ) (page 579)

to_float$( ) (page 581)
to_num$( ) (page 583)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

509

open_message_file$( )
System function: open message file

Syntax

open_message_file$( filename )

Arguments

filename

Return
values

(NUMERIC)

Description

(STRING) A string that contains the directory search path and file
name of the message file to be opened.

The message file is successfully opened.

errno

The value of the operating system status code errno if the message
file is not successfully opened.

The open_message_file$( ) system function opens the message file filename. If

filename is a null string, open_message$( ) produces a runtime error.
Multiple message files can exist. However, only one message file can be open at a
time. If another message file is already open, open_message_file closes this message
file before opening the message file filename.
Messages are stored, one per line, in a special format. For a complete description of
the message file format, see the description for the get_message$( ) system function.

Example

In this example, open_message_file$( ) opens the message file /usr/apps/messages. If

this message file can be opened, the code sample retrieves a message from it using
get_message$( ). After the message is retrieved, the message file is closed by
close_message_file$( ).
IF ( open_message_file$(/usr/apps/messages) = 0 ) THEN
BEGIN
DISPLAY get_message$(100) FOR FYI_MESSAGE WAIT
close_message_file$()
END

See also

510

System functions
close_message_file$( ) (page 421)
get_message$( ) (page 486)

Unify VISION: 4GL Reference

os_type$( )
System function: return operating system name

Syntax

os_type$( )

Return
values

(STRING)

The name of the operating system on which VISION Runtime

Manager is being executed. The return value is one of the following
strings:
UNIX

The UNIX operating system

WINDOWSNT Windows NT

Description

The os_type$( ) system function enables you to write statements specific to a

particular operating system. os_type$( ) takes no arguments and returns the name of
the current operating system type as a string.

Example

In this example, the system command that is executed is dependent upon the operating
system type.
IF os_type$() = WINDOWSNT THEN
system$(edit vision.tmp)
ELSE
system$(vi /temp/vision_file)

See also

System functions
db_type$( ) (page 446)
ui_type$( ) (page 597)

Chapter 6: System functions

511

pad_str_left$( )
System function: pad variable to the left

Syntax

pad_str_left$( variable, pad_str, str_length )

Arguments

variable

(STRING or TEXT) The string or text value to pad.

pad_str

(STRING) The string containing a character with which to pad the

variable value on the left. If more than one character is specified, only
the first character is used.

str_length

(NUMERIC) The requested length of the padded variable value.

Return
values

Description

(STRING)
A padded string of length
str_length

For non-null variable or non-null pad_str, and if

str_length is greater than variable length.

A null string or text

For null variable or null pad_str, or if str_length is

less than variable length.

The pad_str_left$( ) function pads the left side of a variable value with the pad
character in pad_str. If the pad_str contains more than one character, the first
character of the pad_str is used as the pad character.
The variable value is padded on the left until the length of variable value is equal to
str_length. If the str_length is less than the length of the variable argument or if
pad_str is a zero-length string, variable remains unchanged.

512

Unify VISION: 4GL Reference

Example

In this example, pad_str_left$( ) pads the string in str on the left with the pad
character x. The final padded string is xxxxxxfour.
SET str TO four
IF ( pad_str_left$(str, x, 10) = xxxxxxfour ) THEN
DISPLAY Left padded string with length of 10
FOR FYI_MESSAGE

See also

System functions
pad_str_right$( ) (page 514)

Chapter 6: System functions

513

pad_str_right$( )
System function: pad variable to the right

Syntax

pad_str_right$( variable, pad_str, str_length )

Arguments

variable

(STRING/TEXT/BINARY) The string to be padded.

pad_str

(NUMERIC/STRING) The string containing a character with which to

pad the string on the right.

str_length

(NUMERIC) The requested length of the padded string.

Return
values

Description

(STRING/TEXT/BINARY)
The same type as the variable argument.
The padded string of length
str_length

For non-null variable and non-null pad_str and if

str_length is greater than variable length.

A null string or text

For null string or null pad_str, or str_length is less

than variable length.

The pad_str_right$( ) function pads the right side of a variable with the pad character
in pad_str. If a STRING type pad_str contains more than one character, the first
character only of the pad_str is used as the pad character. The variable is padded on
the right until the length of variable is equal to str_length. If str_length length is less
than or equal to the length of the variable argument or if pad_str is a zero-length
string, variable remains unchanged.
Although the description of this routine is mostly character-oriented, when the
variable parameter is of type BINARY, this routine is byte-oriented instead of character
oriented. This distinction is only apparent when characters are encoded into a
multi-byte character set such as Unicode.
The str_length argument is in character units when the variable parameter is of type
STRING or TEXT. The str_length is in byte units when the variable parameter is of
type BINARY.

514

Unify VISION: 4GL Reference

If variable is of type BINARY, then pad_str must be type NUMERIC. If variable is of

type STRING or TEXT, then pad_str must be type STRING.
A NUMERIC type pad_str must have a value between 0 and 255 inclusive. It
represents the decimal value of the byte to use for padding.
If any of the parameters are NULL, then NULL is returned.
The str_length argument can be any numeric value including zero and negative
integers.

Example

In this example, pad_str_right$( ) pads the string in str on the right with the pad
character x. The final padded string is fourxxxxxx.
SET str TO four
IF ( pad_str_right$(str, x, 10) = fourxxxxxx ) THEN
DISPLAY Right padded string with length of 10
FOR FYI_MESSAGE

This example uses the pad_str_right$( ) function to create a 100-byte binary variable
where each byte holds the character code of a blank character:
BUTTON PutMsg
METHOD ON CLICK(thebutton)
BEGIN
if ( fOpen ) then
BEGIN
set seedMsg to to_binary$( );
set Message to pad_str_right$( $seedMsg,
str_to_char_code$( ), 100 );
copy_in$( Message, 1, 5,
to_binary$(to_string$(current_time$( ))) );
copy_in$( Message, 7, 18,
to_binary$(to_string_using$(
current_date$( ), AAA DD, YYYY ) ) );
copy_in$ ( Message, 20, 100,
to_binary$($sFreeFormString ) );

See also

System functions
pad_str_left$( ) (page 512)
copy_in$( ) (page 423)
trim_bytes$ ( ) (page 592)

Chapter 6: System functions

515

push_shell$( )
System function: access operating system command line

Syntax

push_shell$( )

Support

Support for this feature is platform dependent.

UNIX

Supported.

Windows

Supported.

Return
values

None.

Description

The push_shell$( ) system function allows the user to access the operating system
command line from within a Unify VISION application.
UNIX

The type of shell that is executed is determined by the setting of the UXPUSHSHELL
external preference.
To exit this shell, the user types in the shell termination command. This command
varies depending upon the type of operating system shell.

Example

In this sample, if the user answers Y, push_shell$( ) starts an operating system

process.
IF (user_response = Y ) THEN
push_shell$()

See also

516

System functions
system$( ) (page 574)
Unify VISION: 4GL Reference

Related
For the description of the UXPUSHSHELL external preference, see Unify VISION:
information Application Reference.

Chapter 6: System functions

517

raise_ams_event$( )
System function: report application management event

UNIX only

Unify AppMan only

Syntax

raise_ams_event$( class, severity, event_ID, msg, slot_values )

Support

The raise_ams_event$( ) system function is supported only for UNIX-based

applications that are configured for use with a Unify AppMan event agent. If used in
an application that is not configured for Unify AppMan, this system function has no
effect.

Arguments

class

(STRING) Identifies the name of an event class. For the predefined

Unify AppMan application event class, specify appman.

severity

(STRING) Specifies the value of the severity slot for the event class
information structure. Use one of the following values:
UNKNOWN
HARMLESS
WARNING
MINOR
CRITICAL
FATAL

event_ID

(NUMERIC) Specifies a value for the event_id slot of the appman

event class information structure. This argument has no effect in a
developer-defined application event class.

msg

(STRING) Specifies the message text inserted into the msg slot of the
event class information structure.

slot_values

(STRING) Specifies the values of optional slots for the event class
information structure. You can specify any of the slots defined for the
specified class. Each slot and its value must be separated by a
semicolon (;). To assign values, use the following syntax:

attribute1 = \value1\ [ ; attribute2 = \value2\ ] . . .

518

Unify VISION: 4GL Reference

Return
values

Description

(BOOLEAN)
TRUE

The event agent has successfully reported the event information to the
event server.

FALSE

The attempt to report the application management event failed. The

failure is logged in the file specified by the AMGR_ERFL external
preference, and application execution continues normally.

The raise_ams_event$( ) system function reports an application management event to

Unify AppMan. You can report an occurrence of an appman event class or any
developer-defined event class. The event class must have been defined and registered
with the event server.
You can use the slot_values argument to specify the values of developer-defined event
class slots. You can use slot_values to override the default values of an event class.
For example, by default, the source slot is assigned a value of vision_app; however,
you can use the slot_values argument to assign a different value.
Applications can use the following numbers as AppMan events:
Error number ranges for AppMan events
Error number range

Type error allowed for range

8800 - 9049

Generic manager errors

9100 - 9177

User interaction errors

9200 - 9281

Manager errors

9300 - 9325

Lower level errors

11200 - 20140

New errors for Unify VISION

release 3.x

The text for these error messages is in the following files:

$VISION_HOME/lib/vision.msg
$VISION/lib/vishlp.msg.
Chapter 6: System functions

519

Example

In this example, application management event values for the appman class are
assigned by using SET statements. When the event is reported to Unify AppMan, the
source slot displays Inventory rather than the default value of vision_app.
SET event_class_name TO appman
SET severity to WARNING
SET event_id TO 2001
SET event_msg TO Ambiguous values
SET opt_fields to source = \Inventory\
raise_ams_event$(event_class_name, severity, event_id, event_msg, opt_fields)

The next example is based on a developer-defined event class from this Tivoli BAROC
file:
TEC_CLASS:
developer_event_class
DEFINES
{
developer_field1:
developer_field2:
developer_field3:
developer_field4:
developer_field5:
};
END

ISA EVENT

STRING;
INTEGER;
INTEGER;
STRING;
STRING;

For the slot_values argument (opt_fields), the source slot is assigned a value that
overrides the default value. When sending an event to a Tivoli Event Console, you can
override the value of any slot in the root event class by using this technique.
SET event_class_name TO developer_event_class
SET severity TO WARNING
SET event_id TO UNDEFINED
SET event_msg TO Developer 4GL Event Message
SET opt_fields TO
developer_field1=\developer_text\;developer_field5=\1234\;source=\develop
er_source\
raise_ams_event$(event_class_name, severity, event_id, event_msg, opt_fields)

For information about application management and the appman event information
Related
information structure, see Unify AppMan: Managing Applications.

520

Unify VISION: 4GL Reference

record_is_current$( )
System function: determine whether any record is current

Syntax

record_is_current$( )

Return
values

(BOOLEAN)

Description

TRUE

There is a current record in the selected set.

FALSE

There is no current record (and no selected set).

The record_is_current$( ) system function determines whether there is a current

record in the application. On single-occurrence forms, the current record is the target
table row displayed on the form. On multi-occurrence forms, the current record is the
target table row highlighted by the cursor.
This function returns TRUE as long as the current record has an associated target table
row in the database. If values in the current record have been modified but these
values have not yet been stored in the database, record_is_current$( ) still returns
TRUE.
The record_is_current$( ) function returns FALSE after an unsuccessful database
search, immediately after a uv_clear_to_add command, or when there is a set on a
form with no target table.

Example

In this example, the record_is_current$( ) system function is used to determine

whether the form has a current record. If there is no current record, the user is not
allowed to continue to the next form in the application.
METHOD ON NEXT FORM
IF NOT record_is_current$() THEN
REJECT OPERATION

See also

System functions
current_record_count$( ) (page 429)
current_record_num$( ) (page 430)
is_current_record_stored$( ) (page 496)

Chapter 6: System functions

521

reg_exp_str_compare$( )
System function: compare value with mask

Syntax

reg_exp_str_compare$( variable, mask )

Arguments

variable

(STRING/TEXT) The string to be compared.

mask

(STRING) A mask containing the regular expression.

Return
values

Description

(BOOLEAN)
TRUE

variable value contains the segment specified by the mask.

FALSE

variable value does not contain the segment specified by the mask; or
the mask or the variable value is a null string.

The reg_exp_str_compare$( ) system function compares a variable value with a

special string mask that specifies valid string segments. If variable value contains a
string that matches any of the segments described by the mask,
reg_exp_str_compare$( ) returns a BOOLEAN value of TRUE.

Dependencies The reg_exp_str_compare$( ) system function requires the regexp.h file. To see if
you have the regexp.h file in UNIX, type this command: find / name regexp.h
print. Because Unify VISION automatically includes this file, you do not need to
specify #include regexp.h in your script.
Pattern masks
With reg_exp_str_compare$( ) you use regular expression notation to create a pattern
mask. The mask contains a regular expression that defines valid segment patterns.
The mask string contains regular expression metacharacters and characters. The
metacharacters are characters that have a special meaning within the mask.
522

Unify VISION: 4GL Reference

All ordinary characters (except ., *, [, ], {, }, and \) match themselves. Because the

backslash (\) character is a VISION 4GL escape character, a backslash within a regular
expression must be preceded by a backslash.
If a search string includes a single left bracket ([) or a single right bracket (]) character,
the bracket does not not need to be preceded by a backslash. Unmatched bracket
characters are evaluated as literal characters, as shown in the following examples:
Search string

Results

*]bc

fg]bc
]bc

[ABC]]

A]
B]
C
This search string does not find a string that consists only of a single
bracket.

Metacharacters
The following table defines the regular expression metacharacters.
Regular expression metacharacters
Symbol

Specifies

Example

Specifies a segment

Any single character

ABC.

Four characters long and

starting with ABC: for
example, ABCD, ABCE,
ABC1, and so on.

The previous regular

expression zero or more
times

A*C

Containing zero or more

occurrences of A
followed by C: for
example, C, AC, AAC,
AAAAAAC, and so on.

Literal character (except

digits)

\\

Containing the character

\.

Beginning of the string

^The

Containing the word The

occurring at the
beginning of the string.
(continued on next page)

Chapter 6: System functions

523

Regular expression metacharacters (continued)

Symbol

Specifies

Example

Specifies a segment

End of the string

end$

Containing the word end

at the end of the string.

[]

Any character specified

[ABCD]
within the brackets
^ As first character within [^abc]
the brackets, negates the
character class.
(Elsewhere the
character ^ represents
itself.)
Specifies a range of
[az]
characters

\{m,n\}

The previous regular

expression occurring at
least m times but no more
than n times contained
anywhere in the string.
{m} Matches the previous a\\{3\\}
regular expression
exactly m times
{m,} Matches the previous a\\{3,\\}
regular expression m
or more times
{m,n} Matches the previous a\\{3,5\\}
regular expression at
least m times but not
more than n times

\(r\) . . .\n The regular expression that \\(A\\)B\\(C\\)

is the nth grouped regular D\\2
expression enclosed in \(
and \).

524

Containing one of the

values: A, B, C, or D.
Containing any character
except a, b, or c.

Containing any lower

case letter.

Containing aaa

Containing aaa, aaaa, or

aaaaaa, and so on
Containing aaa, aaaa, or
aaaaa

Containing ABCDC

Unify VISION: 4GL Reference

Example

In this example, the reg_exp_str_compare$( ) system function is used to check the

format of a telephone number. The mask verifies that the number has three digits,
followed by a dash (), followed by four more digits. This mask is the second
argument of reg_exp_str_compare$( ).
FIELD phone
METHOD ON FIELD
BEGIN
INPUT
IF ( reg_exp_str_compare$(phone, [19]\\{3\\}[09]\\{4\\}) )
THEN
DISPLAY Valid phone number format!
FOR FYI_MESSAGE WAIT
ELSE
BEGIN
DISPLAY Invalid phone number format! Try Again.
FOR FYI_MESSAGE WAIT
RESTART ON FIELD
END
END

If the phone variable has a valid format, a message appears:

Valid phone number format!

If the phone variable does not have a valid telephone number format, the user is
notified of the error, and input is restarted.

See also

System functions
glob_str_compare$( ) (page 491)

Chapter 6: System functions

525

set_cursor_mem_limit$( )
System function: override default memory limit

Syntax

set_cursor_mem_limit$( maxbytes )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The set_cursor_mem_limit$( ) system function is not supported for

INFORMIX. Therefore, this function returns FALSE.

ORACLE

The set_cursor_mem_limit$( ) system function is not supported for

ORACLE. Therefore, this function returns FALSE.

SYBASE SQL

Supported.

Server
Unify DataServer
The set_cursor_mem_limit$( ) system function is not supported for
Unify DataServer. Therefore, this function returns FALSE.

Arguments

maxbytes

(NUMERIC) Maximum number of bytes stored in memory for each

selected set created by a nested query.
If maxbytes is 0 or less than the number specified by the
ACLVARMEMLIM preference, then the amount of memory that is
used for each selected set is set to the value of ACLVARMEMLIM.

If maxbytes is greater than the value of ACLVARMEMLIM, then the

amount of memory that is used for each selected set is set to
maxbytes.

Return
values

526

(BOOLEAN)
TRUE

The memory limit was successfully set.

FALSE

The maxbytes argument is invalid or the database system supports

multiple cursors.
Unify VISION: 4GL Reference

Description

The set_cursor_mem_limit$( ) system function overrides the default memory limit

specified by the DFLTVCMEM preference for selected sets created by nested queries.
The ACLVARMEMLIM preference specifies the number of bytes to be used to store
variable-length data (TEXT and BINARY) in memory. When the limit would be
exceeded, the rest of the rows are placed on disk. If this function is not called, the
default limit is specified by the DFLTVCMEM preference.

For information about the following related external preferences, see External
Related
information preferences syntax descriptions in Unify VISION: Application Reference:
ACLVARMEMLIM
DFLTVCMEM

Chapter 6: System functions

527

set_image$( )
System function: display an image

Syntax

set_image$( canvas, image )

Arguments

canvas

(STRING) Specifies the name of a canvas or button object on the

current form.

image

(STRING) Specifies the name of an image in the current object search

path.

Return
values

None.

Description

The set_image$( ) system function displays an image on the current form.

The image must have been imported to Unify VISION format.

Example

This example displays MyImage in the canvas1 field of the current form.
set_image$(canvas1, MyImage)

This example shows an alternate method for displaying the same image.
SET $canvas_name TO canvas1
SET $image_name TO MyImage
set_image$($canvas_name, $image_name)

For information about how to import images into Unify VISION format, see Getting
Related
information started in Unify VISION: Developing an Application.

528

Unify VISION: 4GL Reference

set_interrupt$( )
System function: enables or disables the interrupt key

User interface dependent

Syntax

set_interrupt$( interrupt_flag )

Support

For Windows, the set_interrupt$( ) system function is supported for ORACLE and
SYBASE SQL Server.

Arguments

interrupt_flag (BOOLEAN) A flag to enable or disable the keyboard interrupt key.

TRUE

(Default) The keyboard interrupt is enabled.

FALSE

The keyboard interrupt is disabled.

Return
values

None.

Description

The set_interrupt$( ) system function enables or disables the keyboard interrupt. The
effect of the keyboard interrupt key on the database is dependent upon the DBMS.

Example

This SET statement uses set_interrupt$( ) to disable the interrupt key.

SET interrupt_key TO set_interrupt$(FALSE)

Chapter 6: System functions

529

set_scrolling_list$( )
System function: display list box items

Syntax

set_scrolling_list$( list_box, labels, values )

Arguments

list_box

(STRING or OBJECT_REF) Specifies the name or object reference of a

list box on the current form.

labels

(STRING) Specifies the name of an array that contains labels for the
list box. If the array is zero length or uninitialized, the list values are
UNDEFINED. NULL or UNDEFINED elements in the list are not
displayed. If all elements in the array are NULL or UNDEFINED, the
list box is empty and cannot gain focus.

values

(AMOUNT/BOOL/DATE/DATETIME/FLOAT/NUMERIC/OBJECT_REF/
STRING/TEXT/TIME) Specifies the name of an array that contains the
values that correspond to each of the labels. The values can be of any
data type except BINARY.

Return
values

Description

(BOOLEAN)
TRUE

The list box was successfully updated.

FALSE

The list box was not updated.

The set_scrolling_list$( ) system function displays a list of values in the specified list
box, combo box, dropdown list box, or dropdown combo box on the current form.
The number of items specified in labels and values must be equal.
If the specified list box is not found, the function returns a value of FALSE.
The set_scrolling_list$( ) system function is also used with combo boxes, dropdown
list boxes, and dropdown combo boxes.

530

Unify VISION: 4GL Reference

Example

This example displays labels and values in the Menu list box of the current form.
PRIVATE LIST box_labels[1 to 100],
PRIVATE LIST box_values[1 to 100]
...
SET box_labels[1] TO Salad
SET box_labels[2] TO Dessert
SET box_values[1] TO Spinach
SET box_values[2] TO Pie
set_scrolling_list$($menu, box labels, box values)

For information about boxes, see Working with other graphical classes in Unify
Related
information VISION: Designer.

Chapter 6: System functions

531

show_dirty$( )
System function: specify whether dirty data is readable

Syntax

show_dirty$( show_dirty_flag )

Support

Support for this feature is DBMS dependent.

INFORMIX

DBMS dependent
ODBC dependent

INFORMIX allows you to choose whether or not to allow dirty data,

but if you choose to allow dirty data, you cannot determine when an
individual record is locked. If reading dirty data is enabled,
check_dirty$( ) always returns TRUE.
INGRES

Supported.

ODBC

The application is not allowed to access dirty data; therefore,

show_dirty$( ) always returns FALSE.

ORACLE

The show_dirty$( ) system function always returns TRUE.

SYBASE SQL

The show_dirty$( ) system function always returns

FALSE.

Server

Unify DataServer

The Unify DataServer DBMS allows or disallows dirty data to be read

on the basis of the show_dirty_flag setting.

Arguments

show_dirty_flag
(BOOLEAN) A flag you can set to specify whether dirty data is to be
read.

Return
values

532

(BOOLEAN)
TRUE

If the DBMS supports this option, TRUE indicates that the attempt to
set the show_dirty_data flag successful.

FALSE

If the DBMS supports this option, FALSE indicates that the attempt to
set the show_dirty_data flag failed.
Unify VISION: 4GL Reference

Description

The show_dirty$( ) system function is used to specify whether the application can
read dirty data. Dirty data is data taken from a database row that is write-locked by
another transaction.
If a row is write-locked, it is usually because some other transaction is updating,
deleting, or adding the row. The data in this write-locked row may be in the process of
being updated or deleted by another transaction. The write-locked row may not have
the same column values in the database when the exclusive lock is released. If the row
has been deleted, the values may not even exist.
To allow dirty data within your application, set show_dirty_flag to TRUE. The
database can then access dirty data.
To prevent dirty data from being used in your application, set show_dirty_flag to
FALSE. The show_dirty$( ) function prohibits the database from sending dirty data to

the application. If the application is not allowed to read dirty data, no column values
for write-locked rows are selected from the database.
If the application is not allowed to read dirty data, no write-locked rows will be read
by the database. During a database search, write-locked rows will not be selected.
If the DBMS provides support for the Unify VISION system function check_dirty$( ),
you can determine whether any write-locked rows were accessed during a search, even
though these rows are not selected.
If the underlying DBMS does not enable you to specify when to allow dirty data to be
read, these values are returned:
FALSE if the DBMS does not allow an application to read dirty data.
TRUE if the underlying DBMS does allow an application to read dirty data.

The show_dirty$( ) system function has no effect in set consistency; no locked

records are read. In record consistency if show_dirty$( ) is set to FALSE,
UNDEFINED records are created.

Chapter 6: System functions

533

Unify DataServer
If the application is not allowed to access dirty data (that is, the show_dirty_data flag
is set to FALSE), the following conditions occur:
The column values in the write-locked rows are not to be selected from the
database. These values are UNDEFINED in the application.
The status$( ) system function returns a status:
SS_NORM (0): No write-locked rows were encountered.
SS_LMOUT: Write-locked rows were encountered.

If the application can access dirty data (the show_dirty_data flag is TRUE), these
conditions occur:
The column values in the write-locked rows are selected from the database.
The status$( ) system function returns a status:
SS_NORM (0): No write-locked rows were encountered.
SS_NORM (0): Write-locked rows were encountered.

Example

This SET statement uses show_dirty$( ) to allow the current application to read dirty
data. If the database can access dirty data, the BOOLEAN flag ck_data is TRUE and
the application will show dirty data. If the database cannot access dirty data, ck_data
is FALSE.
SET ck_data TO show_dirty$(TRUE)

See also

System functions
check_dirty$( ) (page 416)

For information about dirty data and transaction control, see Managing transactions
Related
information and locks in Unify VISION: Developing an Application.

534

Unify VISION: 4GL Reference

sleep$( )
System function: call C library sleep( ) function

Syntax

sleep$( seconds )

Arguments

seconds

Return
values

None.

Description

The sleep$( ) system function suspends the application execution for the number of
seconds in seconds. This function calls the C library function sleep( ).

Example

This example uses sleep$( ) to pause execution of the application after displaying an
initial message Welcome to the Online Customer Application.

(NUMERIC) The number of seconds to suspend execution of VISION

Runtime Manager (and the application).

DISPLAY Welcome to the Online Customer Application

FOR FYI_MESSAGE
sleep$(10)

This usage of the sleep$( ) function performs almost the same task as the WAIT clause
of the DISPLAY statement. In this case, however, the user does not need to press a
button on a dialog box to continue execution.

For more information about sleep( ), refer to your operating system reference manuals.
Related
information
Chapter 6: System functions

535

sp_compute$( )
System function: find COMPUTE clause

Syntax

sp_compute$( )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The sp_compute$( ) system function is not supported for INFORMIX.

Therefore, this function returns FALSE.

INGRES

INGRES database procedures do not contain a COMPUTE clause;

therefore, this function returns FALSE.

ORACLE

The sp_compute$( ) system function is not supported for ORACLE.

Therefore, this function returns FALSE.

SYBASE SQL

Supported.

Server
Unify DataServer

The sp_compute$( ) system function is not supported for Unify

DataServer. Therefore, this function returns FALSE.

Arguments

None.

Return
values

(BOOLEAN)

536

TRUE

The retrieved row is the result of a COMPUTE clause.

FALSE

The retrieved row is not the result of a COMPUTE clause.

Unify VISION: 4GL Reference

Description

The sp_compute$( ) system function determines whether the recently returned row is
the result of a COMPUTE clause in a SYBASE SQL Server SELECT statement.
The sp_compute$( ) system function returns the value returned by the most recently
executed stored procedure, regardless of the current database connection.

Example

The following example determines whether $var1 and $var2 are set to results
returned by a COMPUTE clause in a SELECT statement.
SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()
EXECUTING
SWITCH sp_select$()
BEGIN
CASE 1:
/* $var1 contains value returned by SELECT #1 */
. . .
CASE 2:
IF (sp_compute$()) THEN
/* $var1 and $var2 contain values returned by COMPUTE clause
*/
. . .
ELSE
/* $var1, $var2, and $var3 contain values returned by SELECT #2 */
. . .
CASE 3:
/* $var1, $var2, $var3, $var4, and $var5 contain values
*/
/* returned by SELECT #3
*/
. . .
END

See also

Script language
EXTERN (page 263)
SET (page 359)

System functions
sp_return$( ) (page 538)
sp_select$( ) (page 541)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.

Chapter 6: System functions

537

sp_return$( )
System function: retrieve status of stored procedure

Syntax

sp_return$( )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

Because INFORMIX stored procedures always return a fixed number

of elements, the sp_return$( ) system function always returns 0.

INGRES

Supported.

ORACLE

The sp_return$( ) system function is not supported for ORACLE.

Therefore, this function returns 0.

SYBASE SQL

Supported.

Server
Unify DataServer

The sp_return$( ) system function is not supported for Unify

DataServer. Therefore, this function returns 0.

Arguments

None.

Return
values

(NUMERIC)

538

The stored procedure was successfully completed and did not

contain the RETURN statement, or the stored procedure contained
the RETURN statement and returned a value of 0.

1 through
99

(SYBASE SQL Server only) Error codes that are reserved by SYBASE
SQL Server to indicate why the stored procedure was not
successfully completed.

return value

The value returned by a NUMERIC or ROW_VALUED stored

procedure when execution has been completed for a stored
procedure that contains the RETURN statement.
Unify VISION: 4GL Reference

Description

The sp_return$( ) system function obtains the return status of the last call to a stored
procedure or INGRES database procedure. sp_return$( ) can be used after execution of
the stored procedure is completed.
Unless the stored procedure is called within an EXECUTING block, sp_return$( )
returns 0 until procedure execution is completed. When execution is completed, the
return status is set to the return status of the stored procedure.
To obtain the value of a NUMERIC stored procedure, use the SET statement to assign
the value that is returned by the stored procedure to a variable.
The sp_return$( ) system function returns the value returned by the most recently
executed stored procedure, regardless of the current database connection.

Example

In the following example, a NUMERIC stored procedure named sp_limit( ) returns 1

when a customers charge is greater than the account limit and returns 0 when the
charge is less than the limit.
SET $acct_stat TO sp_limit($cust_ID,$charges);

The same results are also returned by the following statements:

sp_limit($cust_ID,$charges);
SET $acct_stat TO sp_return$();

In the following example, a ROW_VALUED stored procedure named sp_items is used

in place of a SET . . . SELECT statement. The sp_items stored procedure selects data
from a table named items, where each selected row has an item cost greater than the
argument passed to sp_items. When execution of the stored procedure is completed,
the number of rows found is returned in the return value.

Chapter 6: System functions

539

The stored procedure definition for sp_items( ) contains these SYBASE SQL Server
statements:
CREATE PROC sp_items @cost money
AS
DECLARE @cnt int
SELECT item_key, item_cost
FROM items
WHERE item_cost > @cost
SELECT @cnt = count(*)
FROM items
WHERE item_cost > @cost
RETURN @cnt

First the sp_items stored procedure is declared in an EXTERN statement:

EXTERN STORED ROW_VALUED
FUNCTION sp_items(ge_value) ;

Then sp_items( ) is called in the VISION 4GL script by using the following statements:
SET $cnt TO 0 ;
SET $key, $item_cost TO sp_items(100.00)
EXECUTING
BEGIN
/* Process $key and $item_cost here */
END
SET $cnt TO sp_return$()

See also

Script language
EXTERN (page 263)
SET (page 359)

System functions
sp_compute$( ) (page 536)
sp_select$( ) (page 541)

Related
For information about multiple database connections, see Getting started in Unify
information VISION: Developing an Application.

540

Unify VISION: 4GL Reference

sp_select$( )
System function: determine index of SELECT statement

Syntax

sp_select$( )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

Because INFORMIX stored procedures always return a fixed number

of elements, the sp_select$( ) system function always returns 0.

INGRES

The sp_select$( ) system function always returns 1.

ORACLE

The sp_select$( ) system function is not supported for ORACLE.

Therefore, this function returns 0.

SYBASE SQL

Supported.

Server
Unify DataServer

The sp_select$( ) system function is not supported for Unify

DataServer. Therefore, this function returns 0.

Return
values

(NUMERIC)
1 or higher

Chapter 6: System functions

The index of the current SELECT in the stored procedure. The first
SELECT returns 1; the second SELECT returns 2; and so on.

541

Description

The sp_select$( ) system function determines which of a stored procedures SELECT

statements is currently being executed. You can use this function when your stored
procedure contains multiple SELECT statements, and you want to perform specific
tasks based on the SELECT statement executed. You can use the sp_select$( ) system
function anywhere you would use an expression.
The sp_select$( ) system function returns the value returned by the most recently
executed stored procedure, regardless of the current database connection.

Example

The following example uses the sp_select$( ) system function to determine which
SELECT statement generated the last values returned from the stored procedure
stored_proc( ).
SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()
EXECUTING
BEGIN
SWITCH sp_select$()
BEGIN
CASE 1:
/* Values in $var1 through $var5 are returned by SELECT #1 */
. . .
CASE 2:
/* Values in $var1 through $var5 are returned by SELECT #2 */
. . .
CASE 3:
/* Values in $var1 through $var5 are returned by SELECT #3 */
. . .
END
END

See also

Script language
EXTERN (page 263)
SET (page 359)

System functions
sp_compute$( ) (page 536)
sp_return$( ) (page 538)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.

542

Unify VISION: 4GL Reference

sql_clear$( )
System function: close and clear buffered commands

Syntax

sql_clear$( )

Return
values

(BOOLEAN)

Description

TRUE

All commands have been cleared from the buffer.

FALSE

The buffer could not be cleared or closed.

The sql_clear$( ) system function closes and clears all buffered commands. Use this
function whenever database objects, such as a schema or table, are changed by DDL
statements, or to free memory after commands that will not be executed again.
You need not use this statement with DDL statements that cause automatic clearing:
ALTER, CREATE, GRANT, and REVOKE.

Example

This example uses the sql_clear$( ) function to clear all buffered commands after a
table view has been dropped.
DROP VIEW high_salary;
sql_clear$()

Chapter 6: System functions

543

sql_code$( )
System function: return DBMS status code

Syntax

sql_code$( )

Return
values

(NUMERIC)

Description

The sql_code$( ) system function returns an integer status field. The values returned
are specific to each DBMS.

Value of the sqlcode return field for embedded SQL.

If the DBMS does not provide an SQL code value, the function returns NULL.
The sql_code$( ) function is provided for compatibility with existing DBMS products
only and is not recommended for use with new applications. For new applications, use
the sql_state$( ) function instead.
The sql_code$( ) system function returns the value returned by the most recently
executed SQL statement, regardless of the current database connection.

Example

In this example, an error message is displayed if the UPDATE operation is not

successful.
UPDATE emp SET salary = salary * 1.1
IF (sql_code$()<> UENOERR)
THEN DISPLAY Update failed FOR FYI MESSAGE WAIT

See also

System functions
dbms_status$( ) (page 448)
sql_errmsg$( ) (page 545)

sql_state$( ) (page 550)

status$( ) (page 551)

For information about SQL codes, see the documentation supplied by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

544

Unify VISION: 4GL Reference

sql_errmsg$( )
System function: retrieve SQL error message

Syntax

sql_errmsg$( )

Return
values

(STRING)

Description

The sql_errmsg$( ) system function returns the error message that corresponds to the
last SQL statement executed. The messages returned are specific to each DBMS.

The error message returned as a result of execution of the last SQL

command, up to a maximum of 2048 characters.

The sql_errmsg$( ) system function returns the value returned by the most recently
executed SQL statement, regardless of the current database connection.

Example

This example displays the DBMS message when any error occurs in the database.
SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id;
IF dbms_status$() <> NORM
THEN
DISPLAY DBMS Message: + sql_errmsg$()
FOR FYI_MESSAGE WAIT

See also

System functions
dbms_status$( ) (page 448)
sql_code$( ) (page 544)

sql_state$( ) (page 550)

status$( ) (page 551)

Related
For information about error messages, see the documentation supplied by the DBMS
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 6: System functions

545

sql_errmsg_count$( )
System function: error message handling

Syntax

sql_errmsg_count$( )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The sql_errmsg_count$( ) system function is not supported for

INFORMIX. The function always returns NULL.

INGRES

The sql_errmsg_count$( ) system function is not supported for

INGRES. The function always returns NULL.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

The sql_errmsg_count$( ) system function is not supported for Unify

DataServer. The function always returns NULL.

Arguments

None

Return
values

num_msgs

546

(NUMERIC) The number of messages that are contained in the list of

error messages that was generated by the last call to the database.

Unify VISION: 4GL Reference

Description

The sql_errmsg_count$( ) system function returns the number of error messages that
were generated by the last database operation that generated a call to the server. Such a
database operation is initiated by either VISION Runtime Manager or a
developer-defined C function.

Example

This example displays the last error message received from the DBMS.
FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1)
BEGIN
DISPLAY sql_errmsg_i$(inx)
FOR FYI_MESSAGE WAIT
END

See also

System functions
dbms_status_i$( ) (page 449)
sql_errmsg_i$( ) (page 548)

Chapter 6: System functions

547

sql_errmsg_i$( )
System function: error message handling

Syntax

sql_errmsg_i$(index)

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

The sql_errmsg_i$( ) system function is not supported for

INFORMIX. The function always returns NULL.

INGRES

The sql_errmsg_i$( ) system function is not supported for INGRES.

ORACLE

Supported.

SYBASE SQL

Supported.

Server
Unify DataServer

The sql_errmsg_i$( ) system function is not supported for Unify

DataServer. The function always returns NULL.

Arguments

index

Return
values

err_msg_string (STRING) The text of the index-indicated error message in the list of
error messages that was generated by the last call to the database.
NULL

548

Index, ranging from 1 to n, that indicates the message in the error

message string that was generated by the last call to the database.

The index value is out of range, or the underlying DBMS is not

supported.

Unify VISION: 4GL Reference

Description

The sql_errmsg_i$( ) system function returns the text of the index-indicated error
message in the error message string that was generated by the last database operation
that generated a call to the server. The database operation can be initiated by either
VISION Runtime Manager or a developer-defined C function.
Call the sql_errmsg_i$( ) function immediately after calling sql_errmsg_count$( ).
Make sure that you do not generate any additional calls to the server between the calls
to sql_errmsg_count$( ) and sql_errmsg_i$( ).

Example

This example displays the last error message received from the DBMS.
FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1)
BEGIN
DISPLAY sql_errmsg_i$(inx)
FOR FYI_MESSAGE WAIT
END

See also

System functions
dbms_status_i$( ) (page 449)
sql_errmsg_count$( ) (page 546)

Chapter 6: System functions

549

sql_state$( )
System function: retrieve SQL status field

Syntax

sql_state$( )

Return
values

(STRING)

Description

The sql_state$( ) system function returns a five-character SQL status field. The first
two characters are the character class code, as defined by the ANSI standard for SQL.
The next three characters are the character subclass. The values returned are specific
to each DBMS.

Value of the sqlstate field of the SQL communications area.

If the DBMS does not provide an sqlstate value, the function returns NULL.
The sql_state$( ) system function returns the value returned by the most recently
executed SQL statement, regardless of the current database connection.

Example

In this example, the fyi_message system information field displays a message if the
emp table no longer exists in the database.
UPDATE emp SET vacation = vacation + 1
IF ( sql_state$() = 30500 )
DISPLAY emp table not found
FOR FYI_MESSAGE WAIT

See also

System functions
dbms_status$( ) (page 448)
sql_code$( ) (page 544)

sql_errmsg$( ) (page 545)

status$( ) (page 551)

For information about SQL status codes, see the documentation supplied by the DBMS
Related
information vendor.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

550

Unify VISION: 4GL Reference

status$( )
System function: determine success or failure of last operation

Syntax

[ #include sscodes.h ]
status$( )

Return
values

(NUMERIC)
<>0

An error has occurred, and the operation was not successful.

SS_NORM

The database operation was successful (SS_NORM is 0).

For a complete list of status$( ) return values, see the table following the function
description.

Description

The status$( ) system function obtains the success of certain Unify VISION
operations: SQL statements, database operations, CREATE PIPELINE, RETRIEVE,
and STORE statements. When checking the status$( ) return value, use the return
value names from the sscodes.h file in your script.
To use the status$( ) return value names, you must use the Unify VISION preprocessor
statement #include to include the sscodes.h header file in your script. This header file
contains definitions for the status$( ) return value names. It is located in the include
directory of the Unify VISION release.
Use this function to verify the success or failure of the most recent operation. With
status$( ) you can check the status of database statements such as INSERT, SELECT,
DELETE, UPDATE, SLOCK, and XLOCK.
The status$( ) system function returns the value returned by the most recently
executed statement, regardless of the current database connection.
The status return numbers correspond to the following status return values:
Positive integers
1
2
3

Chapter 6: System functions

SS_BDENV
SS_NOCRF
SS_DFCNV

4
5

SS_FINAC
SS_NOCUR

6
7

SS_NOENV
SS_PROMO

551

Negative integers

1
2
3
4
5
6
7
8
9
11
12
14
15
16
18
19
20
21
22
23
24
25
26
27
28
29
35
37
38
39
40
43
44
45
46
47
48
49
50
52
53
54
55
552

SS_AFLST
SS_BDDOM
SS_DUPBT
SS_DUPK
SS_FLCR
SS_FLOPN
SS_KEYRQ
SS_INTS
SS_MXSCN
SS_NOREF
SS_NOTUP
SS_RDACS
SS_REF
SS_RMEM
SS_STFUL
SS_WRACS
SS_SYSER
SS_FINNA
SS_UPDNA
SS_DELNA
SS_ADDNA
SS_NOMEM
SS_DIRT
SS_NOFIL
SS_FLACS
SS_FLSK
SS_NOREC
SS_NOUP
SS_NODEL
SS_SMUP
SS_SMDEL
SS_NOLCK
SS_SMLCK
SS_LMOUT
SS_USSER
SS_UDFDB
SS_S2U
SS_BDSCN
SS_NIMP
SS_BDSEL
SS_DBTYP
SS_DBLEN
SS_CMBF

56
57
58
59
60
61
69
70
71
74
75
76
77
78
79
80
82
83
84
85
86
87
89
90
91
92
93
94
95
96
97
98
99
100
101
103
104
105
106
107
108
109
110

SS_FUNIP
SS_CONV
SS_EOSCN
SS_NOTID
SS_NORID
SS_BDNAM
SS_PART
SS_ILLA
SS_NODB
SS_NODF
SS_DFERR
SS_NOVAL
SS_ILTST
SS_NOCMB
SS_NONUL
SS_NTLCK
SS_TXIL
SS_FLCL
SS_BTOPN
SS_BTERR
SS_HKERR
SS_NODEM
SS_LMINT
SS_NOSHM
SS_SHMV
SS_NOAT
SS_VRSION
SS_DBCLS
SS_NOLOG
SS_RFLD
SS_DBMOD
SS_UNVIEW
SS_DBINT
SS_OVRFLW
SS_DDMLFL
SS_DBRES
SS_NETER
SS_DEADLCK
SS_LOGOFF
SS_SLOGFUL
SS_COLSPEC
SS_SETSMM
SS_DB2A
Unify VISION: 4GL Reference

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
-150
-151
-152
-153

SS_RDONLY
SS_UDE
SS_UDERB
SS_AROVR
SS_DIVZ
SS_NLEXP
SS_HPMEM
SS_UNDACL
SS_NRIDCOL
SS_NOCON
SS_RMOD
SS_PARNTMCH
SS_MDNTMCH
SS_UNDBTP
SS_UNSPTP
SS_DUPNUL
SS_NOTHNDL
SS_NOTSTR
SS_INVHNDL
SS_HNDLNTAL
SS_SYNEXEC
SS_NUMUSING

SS_NOTSELECT
SS_BADTYPE
SS_NUMROWS
SS_NUMCOLS
SS_ONECON
SS_INVLSP
SS_INVLSPTYP
SS_INVOBJREF
SS_NO_LICENSE
SS_NO_METHOD
SS_PARM_COUNT
SS_PARM_MODE
SS_PARM_TYPE
SS_DAP_4GL
SS_DAP_TI
SS_DAP_TD
SS_INV_ASYNC
SS_APPMAN_ERR
SS_ORB_ERROR
SS_SERV_TERM
SS_DATA_SOURCE_COMM_ERROR

The following list describes the meaning of each return value.

Return Status

Description

SS_ADDNA

Add operation not allowed on form.

SS_AFLST

Bad DIS list found performing an add/update operation.

SS_APPMAN_ERR
SS_AROVR

An AppMan error has occurred.

An arithmetic overflow has occurred.

SS_BADTYPE Destination variables do not have an allowable type.

SS_BDDOM

Domain check failed.

SS_BDENV

Bad format in preference.

SS_BDNAM

Match item has wrong selection file name.

SS_BDSCN

Scan identifier is not found.

SS_BDSEL

Attempt to enter search item in selection table failed.

SS_BTERR

Fatal error in B-tree access; rebuild B-tree.

SS_BTOPN

Error opening B-tree.

SS_CMBF

Column group not allowed.

Chapter 6: System functions

553

SS_COLSPEC

Invalid column specification.

SS_CONV

Internal type conversion error.

SS_DAP_4GL

A runtime error occurred within a service object. Check

dap_4gl_errcode$( ) for the error code.

SS_DAP_TD

A transport specific internal error occurred. Check dap_td_errcode_i$( ).

SS_DAP_TI

A transport-independent partitioned application error occurred. Check

dap_ti_errcode$( ) for the specific code.

SS_DATA_SOURCE_COMM_ERROR
SS_DB2A

/* Data source communication error */

Invalid database column type to Unify VISION type.

SS_DBCLS

Could not close the database.

SS_DBINT

DBMS error. Check dbms_status$( ) and sql_errmsg$( ).

SS_DBLEN

Bad DBMS length.

SS_DBMOD

Database has been modified.

SS_DBRES

Out of some database resource.

SS_DBTYP

Unknown DBMS type.

SS_DDMLFL

Deferred DML failure.

SS_DEADLCK Deadlock encountered; transaction aborted.

SS_DELNA

Delete operation not allowed on form.

SS_DFCNV

Default value conversion error.

SS_DFERR

Error in retrieving default value for a column on insert for column with a
value that is not specified.

SS_DIRT

Returned data may be dirty. It was read without first obtaining a lock.

SS_DIVZ

Attempted division by zero.

SS_DUPBT

Duplicate found in NODUPS B-tree while adding a row.

SS_DUPK

Attempt to store a duplicate key.

SS_DUPNUL

Duplicate key or NOT NULL violation.

SS_EOSCN

End of scan (rows not found).

SS_FINAC

Column inaccessible.

SS_FINNA

Find operation not allowed on form.

SS_FLACS

Denied access to file.

SS_FLCL

Failed to close a file.

SS_FLCR

Error creating file.

SS_FLOPN

Unable to open sort/merge file.

SS_FLSK

File seek error.

SS_FUNIP

Tried to free a NIL pointer to a database value.

SS_HKERR

Hand table entry error.

SS_HNDLNTAL SQL handle is not allowed.

554

Unify VISION: 4GL Reference

SS_HPMEM

No heap memory is available.

SS_ILLA

Illegal argument encountered.

SS_ILTST

Illegal test specified in scan.

SS_INTS

Interrupted search.

SS_INV_ASYNC
Invalid use of SEND ASYNC MESSAGE.
SS_INVHNDL

Specified SQL handle is not currently valid.

SS_INVLSP

The stored procedure was declared as a procedure but was defined as a

function or was declared as a function but was defined as a stored
procedure.

SS_INVLSPTYP An invalid stored procedure type was declared.

SS_INVOBJREF The object reference on method invocation was not valid.
SS_KEYRQ

Key column is required.

SS_LMINT

Lock manager initialization failed.

SS_LMOUT

Unable to acquire lock due to exclusive lock conflict.

SS_LOGOFF

Transaction logging is not enabled.

SS_MDNTMCH The parameter mode specified in the stored procedure declaration doesnt
match the parameter mode in the stored procedure definition.
SS_MXSCN

Too many active scans.

SS_NETER

Network error encountered.

SS_NIMP

Feature not implemented.

SS_NLEXP

A null value was used in an expression.

SS_NO_LICENSE
The feature or message transport required for the operation is not licensed.
SS_NO_METHOD
The interface for the specified object does not include the method specified.
SS_NOAT

Could not attach shared memory at the appropriate address: usually caused
by another shared memory attach occurring before Lock Manager. Call
opendb( ) first in your program to ensure correct attach address.

SS_NOCMB

Column Group not allowed.

SS_NOCON

No connection specified for query.

SS_NOCRF

No row current for column.

SS_NOCUR

No row current for default value.

SS_NODB

Could not get the inode of the database.

SS_NODEL

None of the rows were deleted.

SS_NODEM

Request was not a demotion request.

SS_NODF

There is no default value for this column.

SS_NOENV

Configuration variable not found.

Chapter 6: System functions

555

SS_NOFIL

File does not exist.

SS_NOLCK

None of the rows were locked.

SS_NOLOG

There is no transaction log file (for rollback).

SS_NOMEM

Out of memory.

SS_NONUL

Attempt to use a null in a column where null is not allowed.

SS_NOREC

No rows selected.

SS_NOREF

Attempt to reference nonexistent row.

SS_NORID

Invalid row ID.

SS_NORM

SUCCESS.

SS_NOSHM

Out of shared memory.

SS_NOTHNDL Variable is not an SQL handle.

SS_NOTID

Invalid table ID.

SS_NOTSELCT Statement must be a SELECT statement.

SS_NOTSTR

Expression or variable is not of type STRING.

SS_NOTUP

Row already deleted.

SS_NOUP

None of the rows were updated.

SS_NOVAL

There is no value associated with this column.

SS_NRIDCOL

No row ID for update, insert, or delete operation.

SS_NTLCK

Transaction being committed has no locks.

SS_NUMCOLS Not enough columns in the destination variable list.

SS_NUMROWS Not enough rows in the destination matrix.
SS_NUMUSING Number of actual parameters in USING clause is too small.
SS_ONECON

Only one database connection can be open at one time.

SS_ORB_ERROR
SS_OVRFLW

Unify Object Request Broker Error.

Conversion overflow.

SS_PARM_COUNT
The number of parameters supplied does not match the number of
parameters in the interface.
SS_PARM_MODE
The mode of a supplied parameter does not match the mode specified in the
interface.
SS_PARM_TYPE
The type of a supplied parameter does not match the type specified in the
interface.
SS_PARNTMCH The number of parameters in the stored procedure declaration doesnt match
the number of parameters in the stored procedure definition.

556

SS_PART

Partial success in DBMS operation.

SS_PROMO

Lock granted, promotion occurred.

Unify VISION: 4GL Reference

SS_RDACS

No read permission on row or table.

SS_RDONLY

A prohibited operation was attempted on a read-only database table.

SS_REF

Key cannot be changed because references to it exist.

SS_RFLD

Add rejected: not all required columns were entered.

SS_RMEM

No more space in database to add row.

SS_RMOD

The record was modified by another user.

SS_S2U

An illegal Unify VISION to DBMS data type conversion.

SS_SETSMM

The number of columns in the SELECT statement does not correspond to

the number of variables in the SET statement.

SS_SERV_TERM

DAP Server Terminated.

SS_SHMV

Mismatch between the lock manager code and the shared memory data
structures (incompatible version): reload with new code and/or remove
shared memory segment.

SS_SLOGFUL

(Sybase SQL Server only) Syslogs is full; dump transaction log.

SS_SMDEL

Partial delete, some rows were not deleted.

SS_SMLCK

Partial lock; some rows not locked.

SS_SMUP

Partial update, some rows were not updated.

SS_STFUL

Selection table full.

SS_SYNEXEC EXECUTING clause is not allowed.

SS_SYSER

Internal system error.

SS_TXIL

Invalid transaction ID.

SS_UDE

A developer-defined error has occurred.

SS_UDERB

A developer-defined rollback error has occurred.

SS_UDFDB

There was an undefined database column value in an INSERT, UPDATE,

or SELECT statement.

SS_UNDACL

An undefined variable was used in an SQL statement or stored procedure.

SS_UNDBTP

An attempt was made to call a stored procedure that expects a boolean

value.

SS_UNSPTP

An attempt was made to pass an unsupported data type to a stored

procedure, or an attempt was made to use a variable with an unsupported
data type for an OUT parameter.

SS_UNVIEW

Attempt to use an unusable view.

SS_UPDNA

Update operation not allowed on form.

SS_USSER

Internal error. Call Customer Support.

SS_VRSION

Incompatible lock manager version.

SS_WRACS

No write permission on row or table.

Chapter 6: System functions

557

Example

In this example, status$( ) tests the success of the INSERT statement. If the insert
operation was not successful, the user is notified by a message in the fyi_message
system information field.
#include sscodes.h
...
INSERT INTO EMPLOYEE
IF ( status$() <> SS_NORM ) THEN
DISPLAY Cannot Insert the Record FOR FYI_MESSAGE WAIT

See also

Script language
CREATE PIPELINE (page 196)
DEINSTALL (page 213)
INSERT (page 283)
INSTALL (page 285)
SLOCK (page 369)
UPDATE SELECTED ROW (page 386)

System functions
dbms_status$( ) (page 448)
sql_code$( ) (page 544)
sql_errmsg$( ) (page 545)
sql_state$( ) (page 550)

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.

558

Unify VISION: 4GL Reference

str_search$( )
System function:

NUMERIC

Syntax

str_search$( sourceString, searchString )

Arguments

sourceString

(STRING | TEXT) The string value to search; must be a defined,

non-NULL, non-empty STRING value. The searchString argument
cannot contain metacharacters or new line characters.

searchString

(STRING) The character pattern searched for.

Return
values

NUMERIC

The position in sourceString of the first character of searchString or

NULL if searchString was not found.

Description

The str_search$() system function returns the position of the beginning of

searchString within sourceString. The first character of sourceString has a position of
1. If searchString occurs more than once in sourceString then the position of the first
occurrence only is returned. If searchString does not occur in sourceString then NULL
will be returned. sourceString must be a defined, non-NULL STRING or TEXT value.

Chapter 6: System functions

559

str_to_char_code$( )
System function: convert string or text character

Syntax

str_to_char_code$( character )

Arguments

character

Return
values

(NUMERIC)

(STRING/TEXT) The string or text containing the character to be

translated.

For valid character:

An integer ASCII value in the range 0 to 255.
For null character:
A null NUMERIC value.

Description

The str_to_char_code$( ) system function converts a single character string or text

into its decimal ASCII value.

Example

This SET statement sets the digit variable to the numeric value of the character.
IF ( char >= 0 AND char <= 9 ) THEN
SET digit TO
str_to_char_code$(char) str_to_char_code$(0)

See also

560

System functions
char_code_to_str$( ) (page 415)

Unify VISION: 4GL Reference

str_to_date$( )
System function: convert string or text value to date value

Syntax

str_to_date$( value )

Arguments

value

(STRING or TEXT) The string or text containing the date to be

translated.

Return
values

(DATE)

The DATE value of the value.

Description

The str_to_date$( ) system function converts a string or text value to a DATE value.
The date in value must be in the format determined by the DATEFMT preference. The
default DATEFMT date format is MM/DD/YY.
If value is a null string or text, str_to_date$( ) returns a null DATE value. If value is
an invalid date such as 2/30/49, VISION Runtime Manager reports a runtime error.
Leading white space characters such as spaces and tabs are skipped during the
translation.

Chapter 6: System functions

561

Example

This SET statement uses str_to_date$( ) to set the DATE variable newdate to the date
12/31/94 when the DATEFMT preference is set to the default format.
SET newdate TO str_to_date$(12/31/94)

See also

Related
information

System functions
date_to_mdy$( ) (page 440)
mdy_to_date$( ) (page 506)
null_convert$( ) (page 508)

str_to_time$( ) (page 564)

str_to_val$( ) (page 565)
to_date$( ) (page 579)

For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
DATEFMT
MON1 . . . MON12

562

Unify VISION: 4GL Reference

str_to_datetime$( )
System function: convert a string or text value to datetime

Syntax

str_to_datetime$( value)

Arguments

value

(STRING, TEXT) The string or text containing the datetime value to be

converted.

Return
values

(DATETIME)

A value of type DATETIME converted from the value argument.

Description

The str_to_datetime$( ) function converts a string or text value argument to a

DATETIME value. The datetime in value must be in the format determined by the
DATETIMEFMT preference. The default DATETIMEFMT date format is MM/DD/YY
HH:II:SS.SSS. If a two-digit year is specified in the value argument, the
CENTURY_CUTOFF external preference determines the century.
The NULL keyword can be specified as an argument. If the value argument is a NULL
string or text, a null-valued datetime is returned. If the value argument contains an
invalid date such as 2/30/49, VISION Runtime Manager reports a runtime error.
Leading white space characters such as spaces and tabs are skipped during the
translation.

See also

System functions

to_datetime$( ) (page 580)

Example

This example uses the str_to_datetime$( ) function to convert a string value to

datetime; for instance, the following sets dt to 12/25/99 16:15:00.000:
SET dt to str_to_datetime$(12/25/99 16:15:00)

For information about the CENTURY_CUTOFF external preference, see External

Related
information preferences syntax descriptions in Unify VISION: Application Reference.

Chapter 6: System functions

563

str_to_time$( )
System function: convert a string or text value to time value

Syntax

str_to_time$( value )

Arguments

value

(STRING or TEXT) The string or text containing the time to be

translated.

Return
values

(TIME)

The TIME value of the value.

Description

The str_to_time$( ) system function converts value to a TIME value. The time in the
string must be in the form:
HH:MM

where HH is a two-digit (or one-digit for hours less than 10) hour and MM is a
two-digit number of minutes. This function assumes a twenty-four-hour clock.
If value is a null string or text value, str_to_time$( ) returns a null TIME value.
Leading white space characters, such as spaces and tabs, are skipped during the
translation.

Example

This SET statement uses str_to_time$( ) to set the TIME variable newtime to the time
15:30.
SET newtime TO str_to_time$(15:30)

See also

564

System functions
null_convert$( ) (page 508)
str_to_date$( ) (page 561)

str_to_val$( ) (page 565)

to_time$( ) (page 590)

Unify VISION: 4GL Reference

str_to_val$( )
System function: convert text or string value to number

Syntax

str_to_val$( value )

Arguments

value

Return
values

(NUMERIC/FLOAT)

(STRING or TEXT) The string or text containing the character

representation of the number to be translated.

value cannot be converted to a numeric value or is zero-length.

FLOAT value

value can contain digits (09), a radix separator, or a leading sign (+

or ). If value is a null string, str_to_val$( ) returns a null NUMERIC
value.

NUMERIC value

value contains a valid number and no decimal point.

Description

The str_to_val$( ) system function converts a TEXT or STRING value to a number.

This function assumes that value is a floating point number if it encounters the
decimal point (.) within value. If the string or text contains a decimal point,
str_to_val$( ) returns a FLOAT value. If str_to_val$( ) does not find a decimal point
in the string, it assumes that value is an integer and returns a NUMERIC value.
Leading white space characters such as spaces and tabs are skipped during the
translation. The function returns an error when it encounters the first non-digit
character (except for the ., , or + characters).

Chapter 6: System functions

565

Example

This SET statement uses str_to_val$( ) to set the NUMERIC variable num_val to the
integer 91.
SET num_val TO str_to_val$( 91)

See also

System functions
null_convert$( ) (page 508)
str_to_date$( ) (page 561)
str_to_time$( ) (page 564)

to_num$( ) (page 583)

to_string$( ) (page 584)
val_to_str$( ) (page 602)

Related
For more information about decimal point usage, see RADIXSEP in Unify VISION:
information Application Reference.

566

Unify VISION: 4GL Reference

strlen$( )
System function: counts characters in a TEXT or STRING value

Syntax

strlen$( value )

Arguments

value

(STRING or TEXT) The string or text that contains the characters to be

counted.

Return
values

(NUMERIC)

For a valid STRING or TEXT value, the number of characters is

returned. If the value is null, a NULL numeric value is returned. For
TEXT values, the count includes special characters, such as new-line
and control characters.

Description

The strlen$( ) system function determines the number of characters in a TEXT or

STRING value.

Example

This example uses strlen$( ) to check whether the field variable title has more than 30
characters. If title is too long, the code sample restarts the input.
FIELD title
METHOD ON FIELD
BEGIN
INPUT
IF ( strlen$(title) > 30 ) THEN
BEGIN
DISPLAY Title too longabbreviate to 30 FOR
FYI_MESSAGE WAIT
RESTART ON FIELD
END
END

Chapter 6: System functions

567

This example determines whether the memo variable is larger than the 2000 character
limit for a text view. If memo contains more than 2,000 characters, it will be opened
by the vi editing program. If memo is small, it will be edited within the form field.
FIELD memo
METHOD ON FIELD
BEGIN
IF strlen$($memo) > 2000 THEN
BEGIN
SET tmp_cmd to vi + $memo:FILE_PATH
system$(tmp_cmd)
END
ELSE
INPUT;
END

See also

568

System functions
clip_str$( ) (page 420)
substr$( ) (page 571)

Unify VISION: 4GL Reference

subbinary$( )
System function: extract portion of binary value

Syntax

subbinary$( binary_value, startsub, endsub )

Arguments

binary_value
(BINARY) A BINARY value that contains the binary data to be
extracted.
startsub

(NUMERIC) A NUMERIC integer for the starting point within

binary_value.

endsub

(NUMERIC) A NUMERIC integer for the ending point within

binary_value.

Return
values

(BINARY)

A BINARY value is returned. For a null binary_value, a NULL value is

returned.

Description

The subbinary$( ) system function obtains a portion of binary data from a BINARY
value. It returns the data that starts at the startsub index within binary_value and ends
at the endsub index. The first character of binary_value has an index value of 1.
If startsub is out of the valid range of binary_value, subbinary$( ) returns a
zero-length BINARY value. If endsub is greater than the length of binary_value,
subbinary$( ) returns all of binary_value starting at startsub (which is shorter than the
length you requested with endsub).

Example

This example extracts a set of integers from a list of 4-byte integers.

FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1)
BEGIN
SET $start TO $idx * 4;
SET $end TO $start + 4:
SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end));
END;

See also

System functions
binarylen$( ) (page 414)

Chapter 6: System functions

569

substitute_str$( )
System function

Syntax

STRING | TEXT

substitute_strs$(
STRING | TEXT sourceString, MATRIX substitutionPairList )

Arguments

sourceString

( STRING/TEXT) The value that contains one or more strings to be

substituted. sourceString must be a non-NULL, non-empty STRING or
TEXT type. The sourceString argument cannot have new line
characters in it.

substitutionPairList
( MATRIX) A set of substitution pairs, each pair consisting of a string
and a substitutionValue.

Return
values

(STRING/TEXT)

Description

Each row in the matrix, substitutionPairList, defines a substitution pair. There must be
at least one but no more than 128 rows in substitutionPairList. There must be two
columns in each row. A substitution pair consists of a string and a substitutionValue.
The value in the first column identifies the string. The string must be a defined,
non-NULL, non-empty STRING value. The substitutionValue must be a defined,
non-NULL, STRING or TEXT value.

A copy of the original sourceString with each string replaced with its
corresponding substitutionValue.

The substitute_strs$() system function scans sourceString for occurrences of each

string. Each occurrence of a string will be replaced with its corresponding
substitutionValue.

570

Unify VISION: 4GL Reference

substr$( )
System function: extract a string from a value

Syntax

substr$( value, startsub, endsub )

Arguments

value

(STRING or TEXT) The string that contains the substring or subtext to

be extracted.

startsub

(NUMERIC) The starting index within value.

endsub

(NUMERIC) The ending index within value.

Return
values

(STRING/TEXT)
For non-null value, a STRING value is returned if value is of type
STRING; a TEXT value is returned if value is of type TEXT. For a null
value, a NULL value is returned.

Description

The substr$( ) system function obtains a substring from a value. It returns the
substring that starts at the startsub index within string and ends at the endsub index.
The first character of value has an index value of 1.
If startsub is out of the valid range of value, substr$( ) returns a zero-length string. If
endsub is greater than the length of value, substr$( ) returns all of value starting at
startsub (which is shorter than the length you requested with endsub).

Chapter 6: System functions

571

Example

In this example, substr$( ) is used to divide the emp_phone string into an area code
(in area_code) and a local telephone number (in local_phone). This example sample
assumes that the telephone number in emp_phone is 14 characters long and contains
the telephone number in the form (xxx) yyyyyyy.
SET area_code TO substr$(emp_phone, 2, 4)
SET local_phone TO substr$(emp_phone, 6, 13)

This example extracts the document header from document_text.

SET $tmp_text TO substr$(document_text,1,doc_header_length)

See also

572

System functions
clip_str$( ) (page 420)
strlen$( ) (page 567)

Unify VISION: 4GL Reference

sync_pipelines$( )
System function: pause for pipeline to close

Syntax

sync_pipelines$( )

Description

The sync_pipelines$( ) function causes execution of the partition to stop until all child
processes associated with closed pipelines have terminated. A child process is one
started by a CREATE PIPELINE statement.
By default, the execution of the CLOSE PIPELINE is stopped for a maximum of one
second waiting for the child processes to complete execution. You can use the
sync_pipelines$( ) function to stop execution of your partition until all of the child
processes have terminated, no matter how long it takes. Use this function when the
processing of your partition is dependent on the completion of a process in a pipeline.
Child processes associated with open pipelines are not affected by the
sync_pipelines$( ) function.

See also

Script language
CREATE PIPELINE (page 196)

Example

This example uses the sync_pipelines$( ) function to wait until the RPT process is
complete:
CREATE PIPELINE $pipe RPT script , sort, uniq OUTPUT resultfile;
CLOSE PIPELINE $pipe;
sync_pipeline$();
system$(cp resultfile /datafiles/report);

Related information

Chapter 6: System functions

For more information about related classes and methods, see Unify
VISION: Class Reference

573

system$( )
System function: execute an operating system command

Syntax

system$( command_string )

Arguments

command_string
(STRING) The string that contains the command or application to be
executed.

Return
values

(NUMERIC)
0

The operating system has successfully executed command_string.

UNDEFINED

The command_string is not a valid string expression.

system_value

If the operating system cannot execute command_string, system$( )

returns the value from the operating system function system( ).
(Windows) The failure code returned by the WinExec( ) function.

Description

The system$( ) system function executes an operating system command. An operating

system command is a command that you would type in at the operating system
prompt.
UNIX

This function starts a command shell and gives this shell the command_string as input.
The shell executes the commands in command_string and then exits. The type of shell
that is executed is determined by the setting of the SHELL preference.
Windows NT
For Windows NT this function starts a command shell and gives this shell the
command_string as input. The shell executes the commands in command_string and
then exits. The type of shell that is executed is determined by the setting of the SHELL
preference.
574

Unify VISION: 4GL Reference

Example

This example uses system$( ) to call the edit editor when the user answers YES in
the see_totals field.
FIELD see_totals
METHOD AFTER FIELD
IF ( see_totals = TRUE ) THEN
system$(edit /acctapp/totals)

Windows

This example uses system$( ) to call the notepad editor when the user clicks on
button1 with the developer-defined command view_readme.
COMMAND view_readme
BEGIN
system$ (notepad c:\\acctapp\\read.me)
END

A backslash is required when executing commands built into command.com. To use

backslashes, you must precede each backslash with a second backslash: \\. The
commands del, copy, ren, and dir are examples of commands that are built into
command.com. The following example deletes the amount file after the user clicks
on a button.
COMMAND delete_file
BEGIN
set tmpfile to \\tmp\\amount;
system$ (c:\\winnt\\system32\\cmd.exe /c del + $tmpfile);
END

See also

System functions
background$( ) (page 409)
push_shell$( ) (page 516)

Chapter 6: System functions

575

to_amount$( )
System function: convert a number to an amount

Syntax

to_amount$( number )

Arguments

number

(NUMERIC/FLOAT/BINARY) The value to be converted.

Return
values

(AMOUNT)

The AMOUNT value of number.

Description

The to_amount$( ) system function converts a number to an AMOUNT value. The

number can be a NUMERIC, FLOAT, or BINARY value. If number is a BINARY value,
its length is assumed to be compatible with the length of an AMOUNT value.
The to_amount$( ) function can accept an AMOUNT argument. This function returns
the AMOUNT value without converting it.
If number is a null value, to_amount$( ) returns a null AMOUNT value.

Example

In this example, to_amount$( ) sets the AMOUNT variable amount_val to the

AMOUNT value of the two fields dollars and cents. Two NUMERIC values are
converted to a single AMOUNT variable.
SET money TO (dollars * 100) + cents
SET amount_val TO to_amount$(money)

See also

576

System functions
to_binary$( ) (page 577)
to_bool$( ) (page 578)
to_date$( ) (page 579)
to_float$( ) (page 581)
to_num$( ) (page 583)

to_string$( ) (page 584)

to_string_using$( ) (page 586)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

Unify VISION: 4GL Reference

to_binary$( )
System function: convert a value to a binary value

Syntax

to_binary$( value )

Arguments

value

A value of any type.

Return
values

(BINARY)

The binary value of value.

Description

The to_binary$( ) system function converts a value to a BINARY value. The value to
be converted can be of any type. For a null value, a NULL BINARY value is returned.
The to_binary$( ) function can accept a BINARY argument. It returns the BINARY
value without converting it.

Example

This example creates a BINARY variable that contains a list of integers.

FOR (SET $idx TO 0; $idx < num_elements; SET $idx TO $idx + 1)
BEGIN
SET $intlist TO $intlist + to_binary$($numeric_array[$idx]);
END;

See also

System functions
null_convert$( ) (page 508)
to_amount$( ) (page 576)
to_bool$( ) (page 578)
to_date$( ) (page 579)
to_float$( ) (page 581)

Chapter 6: System functions

to_num$( ) (page 583)

to_string$( ) (page 584)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

577

to_bool$( )
System function: convert a number to a boolean value

Syntax

to_bool$( number )

Arguments

number

Return
values

(BOOLEAN)

Description

(NUMERIC/BINARY) The value to be converted.

TRUE

number is nonzero (<> 0).

FALSE

number is zero (0).

The to_bool$( ) system function converts a number to a BOOLEAN value. If number is

a null value, to_bool$( ) returns a null BOOLEAN value.
If number is a BINARY value, its length is assumed to be compatible with the length of
a NUMERIC value.
The to_bool$( ) function can accept a BOOLEAN argument. This function returns the
BOOLEAN value without converting it.

Example

This IF statement uses to_bool$( ) to check whether the expression num_val +

num_val2 is zero.
IF ( to_bool$(num_val + num_val2) ) THEN
DISPLAY num_val + num_val2 is nonzero
FOR FYI_MESSAGE WAIT

See also

578

System functions
null_convert$( ) (page 508)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_date$( ) (page 579)
to_float$( ) (page 581)
to_num$( ) (page 583)

to_string$( ) (page 584)

to_string_using$( ) (page 586)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

Unify VISION: 4GL Reference

to_date$( )
System function: convert a number or a datetime value to a date

Syntax

to_date$( value )

Arguments

value

(NUMERIC/BINARY/DATETIME) The value to be converted.

Return
values

(DATE)

The DATE value of number.

Description

The to_date$( ) system function converts a number to a DATE value. The number can
be any NUMERIC or BINARY value in the range of DATE values valid in the database.
If number is a BINARY value, its length is assumed to be compatible with the length of
a DATE value.
The to_date$( ) function can accept a DATE argument. This function returns the DATE
value without converting it.
For DATETIME arguments, the returned date is the date portion of the datetime
argument. If the datetime argument has an undefined date portion, then the returned
date is undefined.
If number is a null value, to_date$( ) returns a null DATE value.

Example

This SET statement uses to_date$( ) to set the DATE variable date_val to the DATE
value of 200. The DATE value of 200 is 6/04/90.
SET date_val TO to_date$(200)

See also

System functions
date_to_mdy$( ) (page 440)
mdy_to_date$( ) (page 506)
null_convert$( ) (page 508)
str_to_date$( ) (page 561)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)

Chapter 6: System functions

to_datetime$( ) (page 580)

to_float$( ) (page 581)
to_num$( ) (page 583)
to_string$( ) (page 584)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

579

to_datetime$( )
System function: convert a value to datetime

Syntax

to_datetime$( value)

Arguments

value

(DATE, TIME, BINARY) The value to be converted.

Return
values

(DATETIME)

A value of type DATETIME converted from the value argument.

Description

The to_datetime$( ) function converts the specified value to a value of type

DATETIME. If value is a NULL value, a null-valued datetime is returned. The value is
converted by the rules for assignment-compatible data types.
If value is a DATE value, the time portion of the result is 00:00:00.00 (midnight). If
value is a TIME value, the date portion of the result is undefined. If value is a BINARY
value, its length is assumed to be compatible with the length of a DATETIME value.
The to_datetime$( ) function can accept a DATETIME argument. This function returns
the DATETIME value without converting it.

See also

System functions

str_to_datetime$( ) (page 563)

Example

This example uses the to_datetime$( ) function to convert a date value to datetime;
for instance, the following sets dt to 01/02/97 00:00.000:
SET d to 01/02/97
SET dt to_datetime$(d)

For information about conversion of compatible data types, see Data types in Unify
Related
information VISION: Application Reference.

580

Unify VISION: 4GL Reference

to_float$( )
System function: convert a number to float

Syntax

to_float$( number )

Arguments

number

(NUMERIC/AMOUNT/BINARY) The value to be converted.

Return
values

(FLOAT)

The FLOAT value of number.

Description

The to_float$( ) system function converts a number to a FLOAT value. The number
can be a NUMERIC, BINARY, or AMOUNT value.
If number is a BINARY value, its length is assumed to be compatible with the length of
a FLOAT value.
The to_float$( ) function can accept a FLOAT argument. This function returns the
FLOAT value without converting it.

If number is a null value, to_float$( ) returns a null FLOAT value.

Example

This SET statement uses to_float$( ) to set the FLOAT variable float_val to the FLOAT
value of 897. The FLOAT value of 897 is 897.00.
SET float_val TO to_float$(897)

See also

System functions
null_convert$( ) (page 508)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)
to_date$( ) (page 579)
to_num$( ) (page 583)

Chapter 6: System functions

to_string$( ) (page 584)

to_string_using$( ) (page 586)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

581

to_julian$( )
System function: return the number of Julian days in a value

Syntax

to_julian$( value )

Arguments

value

(DATE, DATETIME) The value to be converted; the date portion of a

datetime value must be defined.

Return
values

(NUMERIC)

The number of Julian days in the value argument.

Description

The to_julian$( ) function returns the number of Julian days represented by the month
and day in the year. The Julian day is the integer number of the days placement in the
year.

Example

This example uses the to_julian$( ) function to convert a value to its Julian
equivalent; the value 60 is returned:
SET julianDays to to_julian$(2/29/96 16:15:00)

582

Unify VISION: 4GL Reference

to_num$( )
System function: convert a value to numeric

Syntax

to_num$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/FLOAT/TIME) The value to be

converted.

Return
values

(NUMERIC)

The NUMERIC value of value.

Description

The to_num$( ) system function converts a value to a NUMERIC value. This value can
be of any type except STRING or TEXT. If the argument is a FLOAT or AMOUNT, it
must be in the range between 231 and +2311; otherwise, it is truncated. If the
argument is a BOOLEAN, FALSE returns 0 and TRUE returns 1. If the argument is
DATE or TIME, any value is legal and the inverse of the to_date$( ) or to_time$( )
functions will be performed.
If value is a BINARY value, its length is assumed to be compatible with the length of a
numeric value.
The to_num$( ) function can accept a NUMERIC argument. This function returns the
NUMERIC value without converting it.
If value is a null value of type AMOUNT, BOOLEAN, DATE, FLOAT or TIME,
to_num$( ) returns a null NUMERIC value.

Example

This SET statement uses to_num$( ) to set the NUMERIC variable num_val to the
NUMERIC value of 8997.34. The NUMERIC value of 8997.34 is 8997.
SET num_val TO to_num$(8997.34)

See also

System functions
null_convert$( ) (page 508)
str_to_val$( ) (page 565)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)
to_date$( ) (page 579)

Chapter 6: System functions

to_float$( ) (page 581)

to_string$( ) (page 584)
to_text$( ) (page 588)
to_time$( ) (page 590)
val_to_str$( ) (page 602)

583

to_string$( )
System function: convert a value to string

Syntax

to_string$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/DATETIME/FLOAT/NUMERIC/
OBJECT_REF/TEXT/TIME) The value to be converted.

Return
values

(STRING)

The string value of value.

Description

The to_string$( ) function converts value to a string. This value can have any of the
following Unify VISION data types: NUMERIC, FLOAT, BOOLEAN, AMOUNT, DATE,
TEXT, BINARY, or TIME.
The to_string$( ) function converts value from one internal data type format to
another. The val_to_str$( ) function converts value from one external (display) data
type format to another.
Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string
containing the number. Amount values include the radix separator but not the currency
symbol. Float values are not rounded. BOOLEAN values are converted to the strings
YES or NO. DATE and TIME values are converted to their string equivalents.
Text values are truncated at the first newline character.
Binary values are truncated at the first newline or other control character or at the first
unprintable character.
For DATETIME arguments, the returned string is in the default datetime format with a
two-digit year.
The to_string$( ) function can accept a STRING argument. This function returns the
STRING value without converting it.

584

Unify VISION: 4GL Reference

If value contains a null value of any data type, to_string$( ) returns a null string. To
return a string containing the null format for the data type associated with value, use
the Unify VISION system function val_to_str$( ).
The default null display character for strings is *. You can change the STRING null
character by setting the STRNULLCH preference.

Example

The first SET statement uses to_string$( ) to assign the string 91 to char_val.
SET char_val TO to_string$(91)

The next SET statement uses to_string$( ) to assign to date_str the string equivalent
of the DATE value in in_date. If in_date has a DATE value of 7/12/87, date_str
contains the string 07/12/87. If in_date contains a null value, date_str contains the
null string ***********.
SET date_str TO to_string$(in_date)

This last example statement uses to_string$( ) to convert the NULL constant into a
null STRING value. This null value is then passed as an argument to the user-defined
VISION 4GL function user_func( ).
SET result TO user_func( to_string$(NULL) )

The NULL constant has no data type associated with it. To use this constant as an
argument (or in any context where data type is required), the constant must be
converted to a null value that has a data type. You can use any of the data type
conversion functions (such as to_amount$( ), to_bool$( ), to_date$( ), to_float$( ),
and to_time$( ) ) in the same way.

See also

System functions
str_to_val$( ) (page 565)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)
to_date$( ) (page 579)

Chapter 6: System functions

to_float$( ) (page 581)

to_num$( ) (page 583)
to_string_using$( ) (page 586)
to_text$( ) (page 588)
val_to_str$( ) (page 602)

585

to_string_using$( )
System function: format a value

Syntax

to_string_using$( value, format_string )

Arguments

value

(AMOUNT/DATE/DATETIME/FLOAT/NUMERIC/STRING/TEXT/TIME)
The value to be formatted.

format_string

(STRING) The string that contains the formatting information.

Return
values

(STRING)

The value formatted according to format_string.

Description

The to_string_using$( ) system function formats a value according to the

format_string. This value can actually have any of the Unify VISION data types except
OBJECT_REF. However, you can specify a format string only for the data types
AMOUNT, DATETIME, FLOAT, NUMERIC, STRING, or TEXT. If value is a null value,
to_string_using$( ) returns a string filled with the appropriate null character. The
default null display character for strings is *.
The null string returned has the length of format_string regardless of the format
actually in this string.
The format_string can include any of the display formats valid in the USING clause of
the DISPLAY statement. The USING clause determines how AMOUNT, NUMERIC,
FLOAT, and STRING values appear in the field window. If format_string is a null
string or is a zero-length string, to_string_using$( ) uses a default string format. This
format is the same format used by the DISPLAY statement when the USING clause is
omitted.
For DATETIME arguments, if the date portion of the datetime is undefined, then the
format template cannot contain any date format template characters.
This function is useful if you need to send formatted data over a pipeline. You can
capture the results of a DISPLAY USING statement with to_string_using$( ).

586

Unify VISION: 4GL Reference

Example

This SET statement uses to_string_using$( ) to set the STRING variable amount_str
to the formatted value of the AMOUNT variable amount_val. If amount_val contains
the value 1246.75, amount_str contains the string $1,246.75.
SET amount_str TO to_string_using$(amount_val, $$,$$$.&&)

See also

System functions
to_amount$( ) (page 576)
to_bool$( ) (page 578)
to_float$( ) (page 581)

to_string$( ) (page 584)

val_to_str$( ) (page 602)

For information about format templates, see Format templates in Unify VISION:
Related
information Application Reference.

Chapter 6: System functions

587

to_text$( )
System function: convert a value to text

Syntax

to_text$( value )

Arguments

value

A value of any type.

Return
values

(TEXT)

The text value of value.

Description

The to_text$( ) system function converts a value of any type to a TEXT value. If value
is NULL, the value returned is NULL.
Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string
containing the number. Amount values include the radix separator but not the currency
symbol. Float values are not rounded. BOOLEAN values are converted to the strings
YES or NO. DATE, DATETIME, and TIME values are converted to their string
equivalents.
The to_text$( ) function can accept a TEXT argument. It returns the TEXT value
without converting it.
Binary values are truncated at the first newline or other control character or at the first
unprintable character.

588

Unify VISION: 4GL Reference

Example

This example creates a text variable that contains a list of employee names and hire
dates.
SET $first_name, $last_name, $hire_date TO
SELECT first_name, last_name, hire_date FROM employee
WHERE hire_date < $year_end
EXECUTING
BEGIN
SET $tmp_text TO $tmp_text + $first_name + + $last_name + ;
SET $tmp_text TO $tmp_text + to_text$($hire_date);
SET $tmp_text TO $tmp_text + char_code_to_str$(013);
END;

See also

System functions
null_convert$( ) (page 508)
to_amount$( ) (page 576)
to_binary$( ) (page 577)
to_bool$( ) (page 578)

Chapter 6: System functions

to_date$( ) (page 579)

to_float$( ) (page 581)
to_num$( ) (page 583)
to_string$( ) (page 584)

589

to_time$( )
System function: convert a number or a datetime to time

Syntax

to_time$( value )

Arguments

value

(NUMERIC/BINARY/DATETIME) The value to be converted.

Return
values

(TIME)

The TIME value of number.

Description

The to_time$( ) system function converts a number to a TIME value. The number can
be any integer and is interpreted as the number of minutes since midnight.
If number is a BINARY value, its length is assumed to be compatible with the length of
a TIME value.
The to_time$( ) function can accept a TIME argument. This function returns the TIME
value without converting it.
If number is a null value, to_time$( ) returns a null TIME value.
For DATETIME arguments, the returned time is the time portion of the datetime
argument, truncated to hours and minutes.

Example

This SET statement uses to_time$( ) to set the TIME variable time_val to the TIME
value of 572. The TIME value of 572 is 9:32.
SET time_val TO to_time$(572)

See also

590

System functions
null_convert$( ) (page 508)
str_to_time$( ) (page 564)
to_amount$( ) (page 576)
to_binary$( ) (page 577)

to_bool$( ) (page 578)

to_date$( ) (page 579)
to_float$( ) (page 581)
to_num$( ) (page 583)

Unify VISION: 4GL Reference

to_value$( )
System function: pass macro arguments to SQL

Syntax

to_value$( value )

Arguments

value

Return
values

Any Unify VISION constant, variable, or expression.

A Unify VISION object.

Description

The to_value$( ) system function allows macro arguments to be passed as Unify

VISION objects to an SQL statement.

Example

When the select1 macro is expanded by the preprocessor, the to_value$( ) system
function is recognized as a Unify VISION object. The value of arg1 is therefore
prepared as a Unify VISION object within an SQL statement.
#define select1(arg1) \
SELECT emp_last_name FROM employee WHERE emp_last_name = to_value$(arg1)

Chapter 6: System functions

591

trim_bytes$( )
System function: string building

Syntax

trim_bytes$ ( buffer, trim_char )

Return
values

(STRING/TEXT/BINARY)
The same type as the buffer argument.

Arguments

buffer

(STRING/TEXT/BINARY) Specifies the variable to trim characters

from.

trim_char

(STRING/NUMERIC) Specifies the value of the trim character.

Description

This function returns a value that is of the same type as the buffer argument. This
returned value is a copy of the original buffer with any trailing characters of value
trim_char removed.
Although the description of this routine is mostly character-oriented, when the buffer
parameter is of type BINARY, this routine is byte-oriented instead of
character-oriented. This distinction is apparent only when characters are encoded into
a multi-byte character set such as Unicode.
If the buffer parameter is of type BINARY, then trim_char must be type NUMERIC. If
the buffer parameter is of type STRING or TEXT, then trim_char must be type
STRING.
When trim_char is of type NUMERIC, it must have a value between 0 and 255
inclusive. It represents the decimal value of the byte to trim.
When trim_char is of type STRING, the first character of the STRING is used as the
character to trim.
If trim_char is a STRING of zero length, then no trimming is done and the returned
value is a copy of buffer. This behavior is defined to be consistent with the
pad_str_right$( ) system function.

592

Unify VISION: 4GL Reference

The trim_char parameter must not be NULL.

If buffer is type STRING or TEXT, then this function will not remove trailing bytes that
are part of the last multi-byte character.
If the parameter buffer is NULL, then NULL is returned. This behavior is defined to be
consistent with the pad_str_right$( ) system function.

Example

This example uses the trim_bytes$( ) function to remove trailing spaces:

SET CustFld to substr$($Buffer, 11, 34)
SET CustomName to trim_bytes$(CustFld, )

See also

System functions

copy_in$( ) (page 423)

pad_str_right$( ) (page 514)

For more information about MQSeries, see Unify VISION:Interconnecting

Related
information Applications with Enterprise Integrator.

Chapter 6: System functions

593

tx_mode$( )
System function : enable transaction handling

Syntax

tx_mode$( mode )

Support

Support for this feature is DBMS dependent.

DBMS dependent

INFORMIX

Supported for INFORMIX SE only. The tx_mode$( ) system function

has no effect for INFORMIX MODE ANSI.

INGRES

The tx_mode$( ) function has no effect because INGRES

automatically starts a multi-step transaction at the first SQL statement
after a connect, commit, or rollback statement.

ORACLE

The tx_mode$( ) system function has no effect for ORACLE.

SYBASE SQL

Supported.

Server
Unify DataServer

The tx_mode$( ) system function has no effect for Unify DataServer.

Arguments

mode

Return
values

(BOOLEAN)

594

One of the values TRUE, FALSE, or UNDEFINED.

TRUE

Automatic transaction handling is enabled.

FALSE

Automatic transaction handling is disabled.

Unify VISION: 4GL Reference

Description

The tx_mode$( ) system function specifies whether automatic transaction handling is

enabled or disabled.
By default, the ACLTXMODE preference is set to TRUE and Unify VISION
automatically begins and commits transactions. However, if the ACLTXMODE
preference is set to FALSE, automatic transaction handling is disabled.
When automatic transaction handling is disabled, transaction level specifications have
no effect, and shared locks are released after a commit or rollback operation.
You can use tx_mode$( ) to dynamically enable or disable automatic transaction
handling, regardless of the setting of ACLTXMODE.
To determine (but not change) the current transaction mode, specify the UNDEFINED
argument for tx_mode$( ).
The tx_mode$( ) system function returns the value returned by the most recently
executed SQL statement, regardless of the current database connection.
ODBC interface

The tx_mode$( ) has no effect.

Example

In this example, automatic transaction handling is first disabled, and then the current
transaction, if any, is committed. A new transaction is then started to process and
commit an update operation.
tx_mode$(FALSE)
COMMIT WORK
BEGIN WORK
UPDATE emp SET vac = vac + 8;
COMMIT WORK

See also

Script language
BEGIN WORK (page 165)
CHOOSE FORM USING (page 174)
COMMIT WORK (page 184)
ROLLBACK WORK (page 348)

Chapter 6: System functions

595

Related
For information about transaction control, see Managing transactions and locks in
information Unify VISION: Developing an Application.
For information about related external preferences, see External preferences syntax
descriptions in Unify VISION: Application Reference:
ACLTXMODE

596

Unify VISION: 4GL Reference

ui_type$( )
System function: determine user interface

Syntax

ui_type$( variable )

Arguments

variable

(STRING) A variable that returns the current presentation mode.

OPENLOOK

OPEN LOOK graphical user interface

MOTIF

Motif graphical user interface

MSWINDOWS Windows user interface

Return
values

Description

(BOOLEAN)
TRUE

The ui_type$( ) function was completed successfully.

FALSE

The ui_type$( ) function failed because an internal error occurred.

The ui_type$( ) system function enables you to return at runtime information about
the user interface being used. You can use the ui_type$( ) function to execute
conditional script segments that are specific to a user interface.
This function fails only when an internal error occurs.

Chapter 6: System functions

597

Example

This example deletes a log file from the operating system. Since delete commands are
operating system dependent, the developer must determine the operating system
before deleting the file. The developer uses the ui_type$( ) function in combination
with the background$( ) and system( ) functions to delete the file.
COMMAND delete_amount
/* Button on form displays Delete Amount Log File */
BEGIN
IF ui_type$($gui_mode) = FALSE THEN
BEGIN
/* Internal error should never occur */
DISPLAY NOTICE 55 Internal error. Please call your support person
LABELS OK
RESULT INTO uifunction_answer
END
ELSE IF $gui_mode = MSWINDOWS THEN /* Windows operating system */
BEGIN
SET tmpfile TO \\tmp\\amount;
system$(c:\\winnt\\command.com /c del + $tmpfile)
/* Deletes amount file */
END
ELSE IF $gui_mode = OPENLOOK OR $gui_mode = MOTIF THEN
/* UNIX operating system */
BEGIN
SET tmpfile TO /tmp/amount;
background$(/bin/csh,rm + $tmpfile) /* Deletes amount file */
END
END

See also

598

System functions
db_type$( ) (page 446)
os_type$( ) (page 511)

Unify VISION: 4GL Reference

unique_sequence$( )
System function: return a unique numeric value

Syntax

unique_sequence$( )

Arguments

None.

Return
values

(NUMERIC)

Description

Each time the unique_sequence$( ) system function is executed, it returns a unique

NUMERIC value. The values returned are not necessarily a consecutive sequence.

Example

In this example, a new form is created. Its name is assigned a unique value by
appending a unique sequence number. The unique numeric value is converted to a
STRING value by the to_string$( ) system function.

A unique NUMERIC value.

VOID FUNCTION launch_a_form(form_class, RESULT name_of_form, RESULT

form_object_id)
BEGIN
SET $name_of_form TO $form_class+_+to_string$(unique_sequence$())
CHOOSE FORM USING CHILD FORM $form_name OF CLASS $form_class
OBJECT_REF INTO $form_object_id
END

Chapter 6: System functions

599

user_id$( )
System function: obtain users ID

Syntax

user_id$( )

Support

Support for this feature is platform dependent.

UNIX

Supported.

Windows

For Windows, this function returns 0.

Return
values

(NUMERIC)

The operating system user ID number of the user.

Description

The user_id$( ) system function obtains the users ID number from the operating
system. This function is useful for recording the identity of the user who makes certain
modifications to the database.

Example

In this example, user_id$( ) sets the emp_uid variable to the user ID of the user who
is currently executing the application.
METHOD BEFORE ADD
SET emp_uid TO user_id$()

See also

600

System functions
get_password$( ) (page 488)
group_id$( ) (page 494)

group_name$( ) (page 495)

user_name$( ) (page 601)

Unify VISION: 4GL Reference

user_name$( )
System function: obtain the users login name

Syntax

user_name$( )

Support

Support for this feature is platform dependent.

UNIX

Supported.

Windows

For Windows, the user_name$( ) system function returns the login

name of the user.

Return
values

(STRING)

The operating system login name of the user.

Description

The user_name$( ) system function obtains the users login name from the operating
system user file. This function is useful for recording the identity of the user who
makes certain modifications to the database.

Example

In this example, user_name$( ) sets the emp_name variable to the login name of the
user who is currently executing the application.
METHOD BEFORE ADD
SET emp_name TO user_name$()

See also

System functions
get_password$( ) (page 488)
group_id$( ) (page 494)

Chapter 6: System functions

group_name$( ) (page 495)

user_id$( ) (page 600)

601

val_to_str$( )
System function: convert a value to string

Syntax

val_to_str$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/DATETIME/FLOAT/NUMERIC/
OBJECT_REF/TEXT/TIME) The value to be converted.

Return
values

(STRING)

The string value of value.

(Partitioned applications only) The value argument can include
OBJECT_REF values.

Description

The val_to_str$( ) system function converts value to a string. Number values

(NUMERIC, FLOAT, and AMOUNT) are converted to a string containing the number.
Amount values include the decimal point but not the dollar sign. Float values are not
rounded. Boolean values are converted to the strings YES or NO. Date and time
values are converted to their string equivalent.
Text values are truncated at the first newline or other control character.
Binary values are truncated at the first control character or at the first unprintable
character.
No leading or trailing spaces are included in the returned string.
For DATETIME arguments, the returned string is in the default datetime display
format.
If value contains a null value, val_to_str$( ) returns a string containing the null value
for the data type associated with value. To return a null string when value is null, use
the system function to_string$( ).

602

Unify VISION: 4GL Reference

The to_string$( ) function converts value from one internal data type format to
another. The val_to_str$( ) function converts value from one external (display) data
type format to another.
The default null display character is *. You can change the null display characters by
setting preferences:
AMTNULLCH
BOLNULLCH
DATNULLCH
DTTMNULLCH
FLTNULLCH
STRNULLCH
TIMNULLCH
TXTNULLCH

Example

This SET statement uses val_to_str$( ) to assign the string 91 to char_val.

SET char_val TO val_to_str$(91)

This SET statement uses val_to_str$( ) to assign to date_str the string equivalent of
the DATE value in in_date. If in_date had a DATE value of 7/12/87, date_str would
contain the string 07/12/87. If in_date contained a null value, date_str would contain
the null string for DATE: **********.
SET date_str TO val_to_str$(in_date)

See also

System functions
null_convert$( ) (page 508)
str_to_val$( ) (page 565)
to_amount$( ) (page 576)
to_binary (page 577)
to_bool (page 578)

Chapter 6: System functions

to_date$( ) (page 579)

to_float (page 581)
to_num$( ) (page 583)
to_string$( ) (page 584)
to_string_using$( ) (page 586)

603

yesno$( )
System function: display a notice box

Syntax

yesno$( yes_no_msg, default_value )

Arguments

yes_no_msg

(STRING) A string containing the question to be displayed in a notice

box.

default_value

(NUMERIC) An integer value to control the default response to the

questions possible values:

Return
values

Description

Default response is yes.

Default response is no.

No default; user response is required.

Responses are auto-accepted; yes is the default

value.

Responses are auto-accepted, and the user must

respond; there is no default value.

(BOOLEAN)
TRUE

The users response to the yes_no_msg prompt is either yes or

YES.

FALSE

The users response to the yes_no_msg prompt is either no or NO.

The yesno$( ) system function displays a prompt message, yes_no_msg, in a notice

box and then waits for the users response.
The default_value controls the default action for the response. If default_value is set to
1, the user must respond.

604

Unify VISION: 4GL Reference

Example

This example uses yesno$( ) to ask the user whether to continue to the next record if
the current record is not stored in the database.
METHOD ON NEXT RECORD
IF ( NOT (is_current_record_stored$() ) ) THEN
BEGIN
IF ( yesno$(
You are about to lose your record changes. Save them?,
1) ) THEN
BEGIN
DISPLAY Updating... for FYI_MESSAGE
UPDATE CURRENT RECORD
DISPLAY Record Updated FOR FYI_MESSAGE
END
END

If the current record is not stored and the user answers yes to the prompt:
You are about to lose your record changes? Save them?

The current record is stored with the UPDATE CURRENT RECORD statement.

Chapter 6: System functions

605

606

Unify VISION: 4GL Reference

7
Predefined C functions
This chapter contains complete descriptions of predefined C functions. These
functions can be called by C-hooks which are global functions written in the C
language. A discussion of C-hooks and their implementation is found in Unify VISION:
Concepts.
Descriptions of the predefined C functions appear in alphabetical order and include
several parts:

Syntax

Presents the syntax for the function. BOLDFACE words are keywords.
Italicized words within the syntax are described under Arguments.

Support

Describes restrictions or dependencies, if any.

Arguments

Describes the italicized arguments shown in the syntax.

Return values
Describes the values returned by the function.
Arguments

Describes values the variable can return.

Description

Describes usage, conditions, and notes.

Example

Gives a sample that shows how the function might be used.

See also

Lists related statements described in this manual.

Related information
Lists chapters or topics in other manuals that are related to the
function.
607

uacldb( )
Predefined C function

Syntax

Unify DataServer only

#include <include/rhli.h>
[ #include <include/rhlierr.h> ]
#include <include/chookinc.h>
int uacldb(dbidp, status)
UDBID *dbidp;
USTATUS *status;

Support

Support for this feature is DBMS dependent.

INFORMIX

The uacldb( ) C function is not supported for INFORMIX. The

function returns TRUE with *dbidp set to 1.

INGRES

The uacldb( ) C function is not supported for INGRES. The function

returns TRUE with *dbidp set to 1.

ORACLE

The uacldb( ) C function is not supported for ORACLE. The function

returns TRUE with *dbidp set to 1.

SYBASE SQL

The uacldb( ) C function is not supported for SYBASE

SQL Server. The function returns TRUE with *dbidp set
to 1.

Server

Unify DataServer

Supported.

Arguments

608

dbidp

Pointer to the returned database ID.

status

Pointer to the returned RHLI function system value.

Unify VISION: 4GL Reference

Return
values

Status
values

Description

USUCCESS

The operation was successful.

UFAILURE

A failure occurred during the operation. Check the status value for the
error.

UENORM

Operation was successful. The dbidp parameter points to the database

ID.

UEDBCLS

The database is closed.

The uacldb( ) function sets the passed parameter dbidp pointer to the location of the
database identifier for the database opened by Unify VISION.
All #include statements specified in the syntax are required in the callers source file.

Warning

Never attempt to close the database that has been opened by Unify VISION. Unify
VISION automatically closes the database when the application exits.
Unify VISION returns the database ID of the database connection of the current form.
If the connection is not open, uacldb( ) also opens the connection.

Chapter 7: Predefined C functions

609

Example

The following example prints a message if the current database ID could not be
retrieved.
UDBID dbid;
if (! uacldb(&dbid, &status))
{
fprintf(stderr,
Unable to get database ID: status = %ld\n,
status);
}
else
{
/* Get current process ID */
if (! uallpid(dbid, &npid, &pidl, &status))
{
fprintf(stderr,
Unable to get all process ID info: status = %ld\n,
status);
}
if (npid > 0)
{
free ((char *) pidl);
}

See also

Predefined C functions
uaclrid( ) (page 621)
uacltx( ) (page 623)

See also Unify DataServer: SQL/A Language Reference.

Related
information
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

610

Unify VISION: 4GL Reference

uacldbp( )
Predefined C function

Syntax

SYBASE SQL Server only

#include <include/chookinc.h>
#include <sybfront.h>
#include <sybdb.h>
int uacldbp(dbprocess, status)
DBPROCESS **dbprocess;
USTATUS *status;

Support

Support for this feature is DBMS dependent.

INFORMIX

The uacldbp( ) function is not supported for INFORMIX.

INGRES

The uacldbp( ) C function is not supported for INGRES.

ORACLE

The uacldbp( ) function is not supported for ORACLE.

SYBASE SQL

Supported.

Server
Unify DataServer

The uacldbp( ) function is not supported for Unify DataServer.

Arguments

dbprocess

Address of a pointer to the SYBASE SQL Server DBPROCESS

structure.

status

Pointer to the returned function status value.

Chapter 7: Predefined C functions

611

Return
values

Status
values

Description

TRUE

The operation was successful.

FALSE

A failure occurred during the operation. Check the status value for the
error.

UEDBCLS

The database is closed.

UECMFATL

Internal error (nonfatal).

The uacldbp( ) C function sets the passed DBPROCESS pointer to the address of the
SYBASE SQL Server database to be used by VISION Runtime Manager. The
DBPROCESS structure is required to perform any database operation through the
SYBASE DB-Library SQL Interface. C-hooks can use the SYBASE DB-Library SQL
Interface functions with the pointer to the DBPROCESS structure obtained by calling
this function.
Call the uacldbp( ) function every time you call a C-hook to perform a SYBASE SQL
Server DB-Library call. If a scan is active, uacldbp( ) saves the active scan in the
nested query manager area.
The sybfront.h and sybdb.h include files are used to call SYBASE SQL Server
routines or declare SYBASE SQL Server variables. Attempting to call uacldbp( ) for an
unsupported DBMS results in a null pointer.
All #include statements specified in the syntax are required in the callers source file.
Unify VISION returns the DBPROCESS for the connection of the current form. If the
connection is not open, uacldbid( ) also opens the connection.

612

Unify VISION: 4GL Reference

Example

The following example shows how the uacldbp( ) function can be used to acquire a
pointer to the DBPROCESS structure and perform database operations.
DBPROCESS *dbprocess;
USTATUS status;
/* get dbprocess */
if(!uacldbp(&dbprocess, &status))
{
fprintf(stderr, Unable to get a pointer to DBPROCESS);
return(0);
}

See also

Predefined C functions
uaclwhr( ) (page 626)

For information about C-hook functions, see Creating and calling 3GL functions in
Related
information Unify VISION: Developing an Application.
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 7: Predefined C functions

613

uaclGetDatetime( )
Predefined C function

Syntax

#include <include/chookinc.h>
int uaclGetDatetime( dt, y, m, d, h, i, s, ms )
AVAL *dt;
int *y, *m, *d, *h, *i, *s, *ms;

Arguments

Return
values

Description
614

dt

The AVAL structure that contains the date, time, or datetime value.

Pointer to the returned year.

Pointer to the returned month.

Pointer to the returned day.

Pointer to the returned hour.

Pointer to the returned minute.

Pointer to the returned second.

ms

Pointer to the returned milliseconds.

The operation was successful.

A failure occurred during the operation.

This function will get the constituent parts from the dt AVAL structure and place the
Unify VISION: 4GL Reference

integer values in each of the arguments pointed to by y, m, d, h, i, s, and ms. The dt

argument may be of type DATETIME, DATE, or TIME. If it is of type DATE or TIME,
only the appropriate arguments receive values.
All #include statements specified in the syntax are required in the callers source file.
For datetime values, if the date portion of dt is undefined, the returned date portion is
0/0/0.

See also

Predefined C functions
uaclPutDatetime( ) (page 619)

For more information about using 3GL functions, see Creating and calling 3GL
Related
information functions in Unify VISION: Developing an Application.

Chapter 7: Predefined C functions

615

uacllda( )
Predefined C function

Syntax

ORACLE only

#include <include/rhli.h>
[ #include <include/rhlierr.h> ]
#include <include/chookinc.h>
int uacllda(lda, status)
char **lda;
USTATUS *status;

Support

Support for this feature is DBMS dependent.

INFORMIX

The uacllda( ) C function is not supported for INFORMIX.

INGRES

The uacllda( ) C function is not supported for INGRES.

ORACLE

Supported.

SYBASE SQL

The uacllda( ) C function is not supported for SYBASE

SQL Server.

Server

Unify DataServer

The uacllda( ) C function is not supported for Unify DataServer.

Arguments

Return
values

616

lda

Pointer to the returned address of the ORACLE LDA structure.

status

Pointer to the returned function status value.

TRUE

The operation was successful.

FALSE

A failure occurred during the operation. Check the status value for the
error.
Unify VISION: 4GL Reference

Status
values

Description

UEDBCLS

The database is closed.

UEINVAL

Invalid value; value is not valid on the current database.

UEFAULT

Invalid parameter passed.

UENORM

Operation successful.

The uacllda( ) function sets the pointer to the LDA (ORACLE login data area)
structure for the ORACLE database used by VISION Runtime Manager. The LDA
structure is required to perform any database operation through the ORACLE Call
Interface (OCI). C-hooks can use the OCI functions with the pointer to the LDA
structure obtained by calling this function. Attempting to call uacllda( ) for an
unsupported DBMS results in a linking error. For more information, refer to the
ORACLE OCI documentation.
The #include statements specified in the syntax are required in the callers source file.
Unify VISION passes the form connection information to the C function. If the
connection is not open, uacllda( ) also opens the connection.

Example

The following example shows how the uacllda( ) function can be used to acquire a
pointer to the LDA (ORACLE login data area) structure and perform database
operations. This example finds all tables owned by the current user.
LDA *lda;
CDA crs1, crs2;
USTATUS status;
/* get lda */
if(!uacllda(&lda, &status))
{
fprintf(stderr, Unable to get a pointer to LDA );
return(0);
}
/* open cursor */
if (oopen(&crs1, lda, (char *)0, 1, 1, (char *)0, 1))
{
return(0);
}
/* parse query */

Chapter 7: Predefined C functions

617

if (osql3(&crs1, select TNAME from TAB where TABTYPE=TABLE, 1))

{
return(0);
}
/* execute query */
if (oexec(&crs1))
{
return(0);
}

For information about multiple database connections, see Getting started in Unify
Related
information VISION: Developing an Application.

618

Unify VISION: 4GL Reference

uaclPutDatetime( )
Predefined C function

Syntax

#include <include/chookinc.h>
int uaclPutDatetime( dt, y, m, d, h, i, s, ms )
AVAL *dt;
int y, m, d, h, i, s, ms;

Arguments

Return
values

dt

The AVAL structure to contain the time, date, or datetime value.

The year in the datetime value.

The month in the datetime value.

The day in the datetime value.

The hour in the datetime value.

The minute in the datetime value.

The second in the datetime value.

The operation was successful.

A failure occurred during the operation.

Chapter 7: Predefined C functions

619

Description

This function places the constituent parts of a time, date, or datetime value into the
date, time, or datetime dt AVAL structure. If the data type of dt is unset, it is defined to
be of type DATETIME. If the data type of dt is DATE or DATETIME, then the numeric
arguments must result in a valid date value or 0/0/00 for datetime values. Otherwise,
AVAL is returned as undefined in the dt structure. Arguments not applicable to the
data type of dt are ignored.
All #include statements specified in the syntax are required in the callers source file.
For datetime values, if the y/m/d value is 0/0/0, then the date portion of dt is set to
undefined.

See also

Predefined C functions
uaclGetDatetime( ) (page 608)

For more information about using 3GL functions, see Creating and calling 3GL
Related
information functions in Unify VISION: Developing an Application.

620

Unify VISION: 4GL Reference

uaclrid( )
Predefined C function

Syntax

Unify DataServer only

#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/chookinc.h>
URID uaclrid(status)
USTATUS *status ;

Support

Support for this feature is DBMS dependent.

INFORMIX

The uaclrid( ) C function is not supported for INFORMIX. The

function returns FALSE with *status set to 0.

INGRES

The uaclrid( ) C function is not supported for INGRES. The function

returns FALSE with *status set to 0.

ORACLE

The uaclrid( ) C function is not supported for ORACLE. The function

returns FALSE with *status set to 0.

SYBASE SQL

The uaclrid( ) C function is not supported for SYBASE

SQL Server. The function returns FALSE with *status set
to 0.

Server

Unify DataServer

Supported.

Arguments

status

Pointer to the returned RHLI function system status value.

Return
values

Row ID

The operation was successful.

UNULLRID

An attempt was made to access an unsupported DBMS or an error

occurred

Chapter 7: Predefined C functions

621

Status
values

Description

UENOROW

The row ID cannot be retrieved.

UENOIMP

An attempt was made to access an unsupported DBMS.

The uaclrid( ) function retrieves the identifier of the row in the selected set that is
currently being processed by pmgr. The row identifier is useful for retrieving text and
binary information.
The uaclrid( ) function is valid only on a form with a target table. This function
should not be called by a C-hook that is called from a global function. Use uaclrid( )
only in add-update mode, not in find mode. If uaclrid( ) is called when there is no
selected set, the function fails and the status value is set to UENOROW.
The #include statements specified in the syntax are required in the callers source file.

Warning

See also

Do not modify displayable fields. Modifying columns of the row does not cause the
AMGR display to be updated.

Predefined C functions
uacldb( ) (page 608)
uacltx( ) (page 623)
uaclwhr( ) (page 626)

See also Unify DataServer: Writing RHLI Applications.

Related
information

622

Unify VISION: 4GL Reference

uacltx( )
Predefined C function

Unify DataServer only

Syntax

#include <include/rhli.h>
[ #include <include/rhlierr.h> ]
#include <include/chookinc.h>
int uacltx(txidp, status)
UTXID *txidp;
USTATUS *status;

Support

Support for this feature is DBMS dependent.

INFORMIX

The uacltx( ) C function is not supported for INFORMIX. The function

always returns TRUE with *txidp set to 1.

INGRES

The uacltx( ) C function is not supported for INGRES. The function

always returns TRUE with *txidp set to 1.

ORACLE

The uacltx( ) C function is not supported for ORACLE. The function

always returns TRUE with *txidp set to 1.

SYBASE SQL

The uacltx( ) C function is not supported for SYBASE

SQL Server. The function always returns TRUE with
*txidp set to 1.

Server

Unify DataServer

Supported.

Arguments

txidp

Pointer to the returned Unify VISION current transaction ID.

status

Pointer to the returned RHLI function system value.

Chapter 7: Predefined C functions

623

Return
values

Status
values

Description

TRUE

The operation was successful.

FALSE

A failure occurred during the operation. Check the status value for the
error.

UEILTX

The transaction ID is invalid.

UEDBCLS

The database is closed.

For Unify DataServer, the uacltx( ) function stores the current transaction ID to the
location specified by txidp. It is useful in C-hooks that call RHLI functions. Any of the
status values returned by sqlcbtx( ) are possible. Refer to the Unify DataServer
documentation.
The #include statements specified in the syntax are required in the callers source file.

Warning

Never attempt to roll back or commit the current Unify VISION transaction
through the RHLI. Use the ACCELL/4GL ROLLBACK WORK statement to roll back
a Unify VISION transaction. A transaction can be committed either by using the
ACCELL/4GL COMMIT WORK statement or by starting execution of a form at the
Start Tx or Restart Tx transaction level.
Unify VISION passes the form connection information to the C function. If the
connection is not open, uacldb( ) also opens the connection.

Example

The following example prints a message if unable to retrieve the current transaction
ID.
UTXID txid;
USTATUS stat;
USTATUS statl[1];
UUSRINF usrinf;
UOID uid;
if (! uacltx(&txid, &stat))
{

624

Unify VISION: 4GL Reference

fprintf(stderr,
Unable to get a transaction ID: status = %ld\n,
stat);
}
else
{
/* Get info about current user */
uid = getuid();
if (! uinfusr(txid, 1, &uid, UCLASS2, &usrinf, statl, &stat))
{
fprintf(stderr,
Unable to get current user info: status = %ld\n,
stat);
}
}

See also

Predefined C functions
uacldb( ) (page 608)
uaclrid( ) (page 621)

See also Unify DataServer: SQL/A Language Reference.

Related
information
For information about multiple database connections, see Getting started in Unify
VISION: Developing an Application.

Chapter 7: Predefined C functions

625

uaclwhr( )
Predefined C function

Syntax

#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/chookinc.h>
char * uaclwhr(status)
USTATUS *status

Arguments

status

Return
values

Status
values

626

Pointer to the returned function status value.

If successful, returns a pointer to the WHERE clause, not including

the keyword WHERE. This pointer remains in effect only until the
next call to uaclwhr( ).
(char *)0

Operation was not successful.

UENOROW

The row ID cannot be retrieved, for example, because there is no

current row, because the form is in find mode, or because the form has
no target table.

UENORM

The operation was successful.

UENOMEM

Insufficient memory is available.

Unify VISION: 4GL Reference

Description

The uaclwhr( ) function is called only from a C function. In add/update/delete mode,

the uaclwhr( ) function returns a pointer to a string that contains a WHERE clause.
The WHERE clause can then be concatenated with other clauses to build a command
to update, delete, or select the current record on the current form. This function is
typically used to select text or binary columns associated with the current record.
uaclwhr( ) is valid only on a form with a target table. This function should not be
called by a C function that is called from a global function. Use uaclwhr( ) only in
add/update/delete mode, not in find mode. If uaclwhr( ) is called when there is no
selected set, the function fails and the status value is set to UENOROW.
No privileges are needed to execute this function. However, permissions are required
to perform database operations.

Example

This example shows a portion of a C program that builds and executes a query that
selects the pic_data column for the current record.
char
sqltext[2048];
{
strcpy(sqltext, SELECT pic_data FROM pic_tab WHERE );
strcat(sqltext, uaclwhr(picstatus));
exec_sql(sqltext); /* function executes an SQL statement */
}

See also

Predefined C functions
uacldb( ) (page 608)
uacldbp( ) (page 611)
uacllda( ) (page 616)

Chapter 7: Predefined C functions

627

628

Unify VISION: 4GL Reference

Appendixes

629

630

Unify VISION: 4GL Reference

Appendix A: Reserved words

The following words are reserved for use by Unify VISION and must not be used as identifiers
in forms or scripts. However, keywords can be used in quoted identifiers.
ACCELL
ACCELL_TYPE
ACCEPT
ACLADD_UPDATE
ACLCANCEL_FORM
ACLDISMISS_FORM
ACLEXIT
ACLFIND
ACLCLEAR_FIELD
ACLCLEAR_TO_ADD
ACLCLEAR_TO_FIND
ACLCONTEXTHELP
ACLDELETE
ACLEXPLAIN_ERROR
ACLFIRST_RECORD
ACLINDEXEDHELP
ACLLAST_RECORD
ACLNEXT_FIELD
ACLNEXT_FORM
ACLNEXT_RECORD
ACLNEXT_SET
ACLPREVIOUS_FIELD
ACLPREVIOUS_SET
ACLRETURN_VALUES
ACLSET_NULL
ACLZOOM
ACTION
ACTION_ID
ACTION_NAME
ACTION_OBJECT_ID
ACTION_OBJECT_NAME
ACTIVATE
ACTIVE
ACTIVEX
ACTIVEX_APPL_RUNNING
ACTIVEX_CLASS_NAME

ACTIVEX_DEFAULT_VERB
ACTIVEX_DISPLAY_AS_ICON
ACTIVEX_OBJECT_TITLE
ACTIVEX_SCALE_TO_FIT
ACTIVEX_TYPE
ACTIVEX_VERBS
ADD
ADD_ALLOWED
ADD_UPDATE
AFTER
ALL
ALTER
AMBIGUOUS
AMOUNT
AND
APPEND
APPLICATION
ARCHIVES
ARE
ARRANGE
AS
ASC
ASCENDING
ASYNC
ASYNCHRONOUS
AT
AUD_ACTION
AUD_LABEL
AUD_ON_ENTRY
AUTO_ACCEPT
AUTO_COMMIT
AUTO_COMPILE
AUTO_CURRENT
AUTO_EDIT
AUTO_FIND
AUTO_ZOOM
631

BACKGROUND
BEFORE
BEGIN
BEGIN_SQL
BINARY
BLINK
BOOL
BORDER
BOUNDED
BOX
BREAK
BREAKPOINT
BUSINESS_EVENT
BUTTON
BUTTON_PRESS
BUTTON_RELEASE
BUTTONS
BY
CACHED
CANCEL
CANCEL_ZOOM
CANVAS
CASCADE
CASE
CASE_CONVERSION
CELL_LABEL
CELL_VALUE
CENTER
CENTERED
CHANGE
CHANGES
CHARACTERISTICS
CHILD
CHOOSE
CLASS
CLASS_ICON
CLASS_NAME
CLEAR
CLEAR_ADD_EXP
CLEAR_AFTER_AU
CLEAR_FIND_EXP
CLICK

632

CLICK_ON_FIELD
CLOSE
CODE_SECTION
COL
COL_ORIGIN
COLOR_PALETTE_NAME
COLUMN_BOUNDED
COLUMN_INDEX
COLUMN_LOWER_BOUNDS
COLUMN_UPPER_BOUNDS
COLUMNS
COMMAND
COMMIT
COMMIT_HOLDING_LOCKS
COMPILE_COMMAND
COMPONENT_BACKGROUND
COMPONENT_CLASS
COMPONENT_FOREGROUND
COMPONENT_LABEL
COMPONENT_VALUE
CONNECTION
CONNECTION_NAME
CONNECTION_SOURCE
CONSISTENCY
CONSISTENCY_MODE
CONTINUE
COPY
CREATE
CREATE_CMD
CUR_FIELD
CUR_NEXT_FIELD
CURRENT
CURRENT_FIELD_NAME
CURRENT_FORM_ON_DESTROY
CURRENT_NEXT_FIELD_NAME
CURRENT_PAGE_ID
CURRENT_PAGE_NAME
CURSOR
CURSOR_COLUMN
CURSOR_POSITION
CURSOR_ROW
CUSTOM
CUT

Unify VISION: 4GL Reference

DATA
DATA_FORMAT
DATA_TYPE
DATE
DB_COLUMN_LENGTH
DB_COLUMN_NAME
DB_COLUMN_TYPE
DB_LENGTH
DB_TYPE
DBMS_ERROR
DBNAME
DBPASSWORD
DBPATH
DBTYPE
DBUSER
DDE_EVENT
DEFAULT
DEFAULT_ITEM_NUMBER
DEFAULT_OBJECT_NAME
DEFINE
DEINSTALL
DELETE
DELETE_ALLOWED
DEMOTING_LOCKS
DESCENDING
DESCRIPTION
DESIGN_COMMAND
DESTROY
DETAIL_FORM_NAMES
DETAIL_KEY_NAMES
DIMENSION
DIRECTIVE
DISABLE
DISABLED
DISMISS
DISMISS_FORM
DISPLAY
DISPLAY_FORMAT

Appendix A: Reserved words

DISPLAY_JUSTIFY
DOUBLE
DRAG
DRAG_ALLOWED
DRAG_DROP_ALLOWED
DRAG_ICON_NAME
DRAG_INVALID_ICON_NAME
DROP
ECHOED
EDIT_ACTION
EDIT_MODE
EDITOR
ELSE
ENABLE
END
END_X
END_Y
END_SQL
ENTER
ENTRY_POINT_CLASS_NAME
ERASE
ERROR
ERROR_LOG_FILE
ESTIMATED_COLUMN_COUNT
ESTIMATED COUNT
ESTIMATED_ROW_COUNT
ESTIMATING
EVENT
EVENTS
EXCEPT
EXECUTE
EXECUTE_COMMAND
EXECUTING
EXIT
EXTERN

633

FALSE
FIELD
FIELD_BEEP_ERROR_MESSAGE
FIELD_BEEP_ON_ERROR
FIELD_ERROR_MESSAGE
FIELD_LENGTH
FIELD_NAME
FIELD_VALIDATION_RULE
FILE
FILE_PATH
FIND
FIND_ACTION
FIND_ALLOWED
FIND_ALLOWED$
FIND_COUNT
FIND_LABEL
FIND_PROMPT
FINDABLE
FIRST
FIRST_FIELD
FIRST_FIELD_NAME
FIRST_INSTANCE
FIRST_RECORD
FLOAT
FOCUSABLE
FOCUS_IN
FOCUS_OUT
FONT_FACE
FONT_FAMILY
FONT_SIZE
FOR
FORCE_HORIZONTAL_SCROLLING
FORCE_VERTICAL_SCROLLING
FOREGROUND

634

FORM
FORM_CONNECTION_NAME
FORM_CONNECTION_SOURCE
FORM_LIST
FORM_MODE
FORM_NAME
FORM_TEMPLATE_FILE
FORM_STATE
FORMS
FREE_SQL
FROM
FUNCTION
FUNCTION_KEY
FUNCTIONS
FYI_COL
FYI_MESSAGE
FYI_ROW
GENERATE_METRICS
GENERATE_TRANSACTIONS
GRAB_MODE
GRANT
GROUP_BOX
HANDLER
HEIGHT
HELP
HELP_ARCHIVE
HELP_DOCUMENTS
HELP_FORM_NAME
HELP_FORM_COL
HELP_FORM_ROW
HELP_TAG
HOLDING
HORIZONTAL_SCROLLBAR
HOT_SPOT

Unify VISION: 4GL Reference

ICON_NAME
ICONIC
IDENTIFIED
IF
IMAGE
IMAGE_FORMAT
IMAGE_NAME
IMAGE_SCALE
IMAGE_SCALING
IN
IN_MEMORY
INCREMENT_AMOUNT
INFO_LEVEL
INFO_LEVEL$
INIT
INITIATE_HOT_LINK
INITIATE_LINK
INPUT
INPUT_ACCELL_TYPE
INPUT_COUNT
INPUT_DB_COLUMN_TYPE
INPUT_DB_COLUMN_TYPE_CODE
INPUT_PRECISION
INPUT_SCALE
INSERT
INSTALL
INSTANCE
INTEGER
INTERFACE
INTERFACE_SOURCE
INTERNAL
INTO
IS
IS_DEFAULT

Appendix A: Reserved words

IS_DETAIL
IS_MASTER
IS_PREPARED
IS_REPLICATED
IS_VALID
ITEM_BACKGROUND
ITEM_COUNT
ITEM_FOREGROUND
ITEM_LABEL
KEY
KEYMAP
KEYS
LABEL
LABEL_JUSTIFY
LABEL_STRING
LABELS
LANGDIR
LAST
LAST_RECORD
LEAVE
LEFT
LIKE
LINE
LIST
LIST_INDEX
LIST_LOWER_BOUNDS
LIST_UPPER_BOUNDS
LOCAL
LOCATION
LOCKED_IN_CACHE
LOCKS
LOG_ERRORS
LOW_INTENSITY

635

LOWER
MACINTOSH
MASTER_KEY_NAMES
MATRIX
MAKE
MAXIMUM_HEIGHT
MAXIMUM_LABEL
MAXIMUM_VALUE
MAXIMUM_WIDTH
MENU_ACTION_OBJECT_ID
MENU_ACTION_OBJECT_NAME
MENUBAR_OBJECT_ID
MENU_LABEL
MESSAGE
METHOD_LIST
METHOD_NAME
METHOD_TEMPLATE_FILE
MINIMUM_HEIGHT
MINIMUM_VALUE
MINIMUM_WIDTH
MORE_PROMPT
MOUSE_ENTER
MOUSE_LEAVE
MOVE
MSG_DESTINATION
MSG_ERRORDISPLAY
MSG_ERRORS
MSG_METHOD
MSG_STATE
MSWINDOWS
MULTI_VALUED
NEW
NEXT
NEXT_FIELD

636

NEXT_FIELD_NAME
NO_CONSISTENCY
NONE
NOT
NOTEBOOK
NOTICE
NULL
NUMERIC
OBJECT
OBJECT_ID
OBJECT_NAME
OBJECT_REF
OBJECT_SEARCH_PATH
OCCURRENCES
OF
ON
ONEWAY
ONLY
OPEN
OPERATION
OR
ORDER
ORDERED_BY
ORIENTATION
OUTPUT
OUTPUT_ACCELL_TYPE
OUTPUT_COUNT
OUTPUT_DB_COLUMN_TYPE
OUTPUT_DB_COLUMN_TYPE_CODE
OUTPUT_NAME
OUTPUT_PRECISION
OUTPUT_SCALE
OVERWRITE

Unify VISION: 4GL Reference

PAGE
PAGE_BORDERS
PAINT
PARENT_ID
PARTITION
PARTITIONGROUP_ASSIGNED
PARTITIONGROUP_OBJECT_ID
PARTITION_OBJECT_ID
PASTE
PERSISTENT
PIPELINE
POINTER
POSITION
PREPARE_SQL
PREV_FIELD
PREV_FORM
PREV_INSTANCE
PREVIOUS
PREVIOUS_FIELD_NAME
PREVIOUS_FORM_NAME
PRINT
PRIVATE
PROJECT_LIST
PUBLIC
QUEUE
RAISE
RECEIVE_DATA
RECORD
RECORD_ACTION
RECORD_CONSISTENCY
RECORD_COUNT
RECORD_NUMBER
RECORD_STATE
REF
REFERENCE

Appendix A: Reserved words

REFERENCED_CLASS_NAME
REFRESH
REGISTER
REJECT
REPAINT
REPEAT
REPEATED
REPLGROUP_NAME
REPLGROUP_OBJECT_ID
REPLGROUP_REGISTRY_OBJECT
REPLICATE
REPLICATED
REQUEST_DATA
REQUIRED
RESCAN_RATE
RESIZABLE
RESIZE
RESTART
RESULT
RETRIEVE
RETRIEVE_VALUE
RETURN
RETURNING
REVERSE
REVOKE
RIGHT
ROLLBACK
ROW
ROW_BOUNDED
ROW_INDEX
ROW_LOWER_BOUNDS
ROW_ORIGIN
ROW_UPPER_BOUNDS
ROW_VALUED
ROWS
RUN_COMMAND

637

SCHEMA
SCREEN
SCREEN_H
SCREEN_W
SCREEN_X
SCREEN_Y
SCRIPT
SCRIPT_ERROR
SCROLLING_LIST_SELECTOR
SEARCH_PATH
SEARCH_RANGES
SEC
SECOND
SECONDS
SELECT
SELECTED
SELECTED_SET_SCROLLBAR
SEND
SERVICE
SET
SET_CONSISTENCY
SHELL
SHLIKE
SLIDER_MAXIMUM
SLIDER_MAXIMUM_LABEL
SLIDER_MINIMUM
SLIDER_MINIMUM_LABEL
SLOCK
SQL_COLUMN_CONDITION
SQL_OPTIONAL_CONDITION
SQL_ORDER_BY_CLAUSE
SQL_ORDER_BY_COLUMN
SQL_WHERE_CLAUSE
START
STATEMENT_TEXT
STIPPLED
STOP_FOR_INPUT
STORE
STORED

638

STRING
SUBCLASS
SUPER
SWITCH
SYSTEM_HELP
TAB_SIDE
TAB_STOP
TABLE
TARGET_FIELD
TARGET_TABLE
TEMP_DIRECTORY
TERMINAL_EMULATOR
TERMINATE_HOT_LINK
TERMINATE_LINK
TEXT
THEN
THICKNESS
THIS_INSTANCE
TILE
TIME
TIMER
TITLE
TO
TRANSACTION
TRANSPORT
TRIM
TRUE
TX
TX_MODE_ADD_RECORD
TX_MODE_BECOME_CURRENT
TX_MODE_CLEAR_TO_ADD
TX_MODE_CLEAR_TO_FIND
TX_MODE_CREATE_FORM
TX_MODE_DELETE_RECORD
TX_MODE_DESTROY_FORM
TX_MODE_FORM_CREATION
TX_MODE_LOSE_CURRENCY
TX_MODE_NOT_CURRENT
TX_MODE_UPDATE_RECORD

Unify VISION: 4GL Reference

UNCACHED
UNDEFINED
UNDERLINE
UNKNOWN
UNLOCK
UNTIL
UPDATE
UPDATE_ALLOWED
UPDATE_ALLOWED$
UPDATEABLE
USAGE
USE_BASE_WINDOW
USERMENU
USING
UV_ADD_UPDATE
UV_CANCEL_FORM
UV_CLEAR_FIELD
UV_CLEAR_TO_ADD
UV_CLEAR_TO_FIND
UV_CONTEXT_HELP
UV_DELETE
UV_DISMISS_FORM
UV_EXIT
UV_FIND
UV_FIRST_RECORD
UV_HELP_INDEX
UV_LAST_RECORD
UV_NEXT_FIELD
UV_NEXT_RECORD
UV_NEXT_SET
UV_NEXT_TAB
UV_PREVIOUS_FIELD
UV_PREVIOUS_RECORD
UV_PREVIOUS_SET

Appendix A: Reserved words

UV_PREVIOUS_TAB
UV_RECALL_ERROR_MESSAGE
UV_RECALL_FIELD
UV_RETURN_VALUES
UV_SET_NULL
UV_ZOOM
VALUE
VALUES
VERTICAL_SCROLLBAR
VIEW
VISIBLE
VOID
WAIT
WHEN
WHERE
WHILE
WIDTH
WINDOW_HEIGHT
WINDOW_STYLE
WINDOW_WIDTH
WITH
WORK
WRAP
WRITE
X
XLOCK
Y
Z
ZOOM
ZOOM_INDICATOR

639

640

Unify VISION: 4GL Reference

Appendix B: External files

The following files, located in the release include directory, are required
by some of the functions used in scripts.
avalmacs.h

Defines macros for the AVAL structure.

chookinc.h

Defines all elements required for passing values to and

from a function.

chooktb.c

Defines external C functions.

command.h

Defines return value names for user commands.

dbmserrrs.h

Defines the error information passed to a DBMS_ERROR

function.

rhlierr.h

Defines database error status values.

scrpterr.h

Defines the error information passed to a

SCRIPT_ERROR function.

sscodes.h

Defines the values returned by the status$( ) system

function.

sybdb.h

(SYBASE SQL Server only) Defines the DBPROCESS

structure.

sybfront.h

(SYBASE SQL Server only) Defines symbolic constants,

such as function return values.

641

642

Unify VISION: 4GL Reference

Glossary
3GL function

A type of external function written in

a third-generation programming
language, for example, the C
programming language.

ancestor form
A form in the form tree that is
between the current form and the first
form.
See also child form; descendent
form; parent form.

abort
To terminate the application or the
current transaction without saving
changes.

ANSI (American National Standards

add/update/delete mode
One of two methods of operation for a
form during application execution. In
add/update/delete mode the user can
add new records to the database,
modify existing records, or remove
existing records.
See also find mode.

application management event

Any significant change in the state of
a system resource or an application.

Institute)
An organization that establishes
voluntary industry standards for
database systems.

ASCII (American standard code for

AMS (application management

information interchange)
A standard set of codes that are used
to represent characters on many
computers. An ASCII file is a text file
that consists of standard characters.
See also binary file.

system)
An integrated configuration of
third-party software tools for
distributing and managing
applications in a distributed
client/server environment.

attribute
A value that defines a particular
characteristic (for example, size) of an
object.
See also preference.
BAROC (basic recorder of objects

AMS transaction

A measured interval during

application runtime.

in C)
(Tivoli Systems) A file format for
defining the slots of an event class.
643

binary file
A file that contains code in the format
required by the computer processor.

Boolean
An entity that has two possible values:
TRUE or FALSE.

business event
An event defined by a Unify VISION
application.
See also application management
event.

cancel
To dismiss the current form, dialog, or
selection without executing any
changes.

child form
A form that is a direct descendent of a
parent form.
See also ancestor form; descendent
form; parent form.

class
The initial definition of any
predefined object or
developer-defined object contained in
an application.

clause
A discrete portion of a script
statement. For example, the ON
CHOOSE NEXT FORM method has a
USING clause.
644

clear-to-find expression
An expression specified by the
CLEAR_FIND_EXP attribute that sets
the initial search criteria for a target
field.
column
The database entity that defines one
data element in a table.
See also row.
column type
The format in which the database
stores column data. VISION data types
are distinct from database column
types.
See also data type.
command
A user request that initiates an
application operation.
See also developer-defined
command; operation; predefined
command.
commit
Terminate a transaction and save all
changes made by that transaction to
the database, making the changes
visible to other transactions.
concurrency
The ability for multiple users to
simultaneously access a single
database.
created form
A form that has been defined and
initialized.
Unify VISION: 4GL Reference

current field
The active field on the current form.

DDL (data definition language)

SQL statements that describe database

elements and their relationships.

current form
The form that has user input focus.
current object
The object that is selected.
current record
The record in the selected set that is
currently active.
custom manager
A developer-built version of vision
where the developer has added
customized 3GL function calls.
data type
The format in which Unify VISION
stores or displays data. Unify VISION
data types are distinct from database
column types.
See also column type.
database
A set of tables defined and managed
by the DBMS.
database operation
A VISION Runtime Manager process
that affects values or rows in a
database table.

declaration
A script statement that supplies
information about an identifier used in
the script, such as the name and type
of a global function.
defined form
A form that has been defined as a
class in an object library.
definition
Statements that specify the actions to
be performed by a function.
dereference operator
A symbol that indicates that the
OBJECT_REF value on the left side
identifies the object to be referenced
on the right side, for example,
text_ref>VALUE
descendent form
A form created later than, and is a
direct chain from, forms higher in the
form tree.
See also ancestor form; child form;
parent form.
developer-defined command
A command class that has been
defined by the developer in a
COMMAND section of a script.
See also command; predefined
command.
DDE (Dynamic Data Exchange)

database procedure
A set of SQL statements that are
stored under a name and can be called
from a VISION 4GL script.
Glossary

A method of interprocess
communication based on the
messaging system built into Microsoft
Windows.
645

dirty data
Database objects that are
write-locked; the objects may or may
not have been changed by a database
operation, and they may contain
uncommitted data.
display format
The format or layout to display a type
of data.
display-only
Data that is read only, that is, data that
cannot be edited or modified.
distributed application
An application that is divided into
application partitions.
DML (data manipulation language)
SQL statements that manipulate

database information but do not affect

the database design.
executing form
A form running under VISION
Runtime Manager.
explicit
An operation that occurs as the result
of a deliberate statement or user
action, such as pressing a command
key sequence.
See also implicit.
extension
Syntax that differs from or
supplements the ANSI standard syntax
for SQL commands.
646

find mode
One of two methods of operation for a
form during application execution. In
find mode the user can search for
existing records that satisfy specific
search criteria.
See also add/update/delete mode.

fire
To execute automatically when a
specific event occurs. For example, a
SYBASE SQL Server trigger can be
fired when an update is applied to a
database column.
form class
An area containing dialog options and
images organized to display and
retrieve information for a user.
See also form instance

form instance
A copy of a form class that is being
executed by VISION Runtime
Manager.
See also form class.

form mode
One of the methods of operation for a
form: find mode or add/update/delete
mode.
form state
In Unify VISION, a form instance can
be in one of three states: defined,
created, and current.
See also created form; current
form; defined form.
Unify VISION: 4GL Reference

form tree
At runtime, defined, created, and
current forms are controlled by a tree
structure, with the first form at the
root of the tree.

global function
A script that contains script functions
or 3GL functions that are defined for
all other scripts in the application.
See also script.

implicit
An operation that occurs
automatically or by default whenever
a specified condition occurs.
See also explicit.

include file
A file that contains declarations and
definitions for variables that are used
in a script.

input focus
The object to which keyboard input is
directed. Assigning focus to a form
instance makes the form current.
See also object.

instance
A named activation of a class.

interactive database operation

A database operation performed on
the selected set that is initiated by the
user or script.
Glossary

keyword
A word defined as part of the VISION
4GL script syntax. Keywords are also
reserved words; they cannot be
assigned definitions by developers.
local function
A method defined only within a form
or global function.
metacharacter
A special character, such as an
asterisk (*), that represents a range or
pattern for matching search criteria.
Sometimes called a wild card.
Metacharacters are DBMS dependent.
noninteractive database operation
An operation on a database table that
is initiated by an SQL statement or
noninteractive script statement.
null
A value of a specific type that is
empty.
See also undefined.
object
In Unify VISION, any form,
application, global function, or other
type of entity recognized by Unify
VISION.
See also instance.
object reference
A handle that uniquely identifies an
object instance in an application.
Object references are assigned when
the object is created, as in form
activation. Object references are
647

stored in the Unify VISION data type

OBJECT_REF.

operation
The series of actions and script
sections that are executed in response
to an event, such as a user command.

parent form
The immediate ancestor form of a
form.
See also ancestor form; child form;
descendent form.

password
A code that identifies the current user
to the operating system or to the
database.

predefined command
A command provided by Unify
VISION that executes a predetermined
sequence of operations when selected
by the user. Predefined commands
include typical database operations
and record manipulation.
See also command;
developer-defined command.

preference
A variable that specifies a value to be
used during application development
or runtime execution.
See also attribute.
648

raise
Changing the stacking order of a
window so as to hide another window.
read lock
An instruction that permits read
access to database rows but prevents
write access by all transactions.
See also write lock.
record
A copy of a database row, displayed
in a selected set.
See also row.
referential integrity
The rules that govern data
consistency, which guarantees that
when a table is updated, all related
tables and objects agree.
repeating group
An object (such as a button or field)
that is repeated one or more times to
display multiple records on a form.
result parameter
A value returned from a database
procedure or stored procedure that can
be used in other statements or
function calls.
return status
A value returned from a method or
function, a database procedure, or a
stored procedure that indicates
whether the function or method was
completed successfully.
Unify VISION: 4GL Reference

row
The database object that consists of a
unique set of related columns that
constitute a single entry in a table.
Sometimes called a tuple. One
database row corresponds to one
Unify VISION record.
See also column; record.

rule
A special database procedure that is
executed (is fired) when an insert,
update, or delete operation is
executed.
See also column; record.

runtime
The execution of an application, as
opposed to its development.

script
Methods and statements that control
execution of a form or other object at
runtime.
See also global function.

script statement
A line in a script. A statement is
associated with a method that
determines when the statement is
executed.

sort
To arrange objects based on an
ordering criteria.
SQL (structured query language)

A relational database language that

provides statements for creating,
manipulating, or searching tables,
based on an English keyword syntax.
stippled
Disabled, indicated by shading an
object with small dots.
stored procedure
A set of database commands stored in
and executed by the DBMS.
subform
A form contained in a form class.
system information field
A predefined field that is used to
display system information.
table
The database entity that stores related
rows. Sometimes called a relation.
target table
The database table that is associated
with a specific form.
TEC (Tivoli/Enterprise Console)

selected set
A group of records that are copies of
rows selected from a database table.
Glossary

(Tivoli Systems) An application that

collects, processes, and automatically
responds to management events in a
client/server environment.
649

timer
An application event, defined by the
developer, that is executed after a
specified time period.
TME (Tivoli/Management

Environment)
(Tivoli Systems) An application
management system (AMS) that can
be used with Unify VISION to
distribute and manage applications.
transaction
A set of one or more database
operations that must be completed as
a single unit.
transaction abort error
An error that causes the DBMS to
abort the transaction.
trigger
A special stored procedure that is
executed (fired) when an insert,
update, or delete operation is
executed.
undefined
Uninitialized; a variable that has no
valid value or type associated with it.
See also null.
update
An operation that changes an existing
row in or adds a new row to the
database table.

650

user
Any person who uses a completed
application.
value parameter
A function parameter that is defined
as a local variable and initialized with
a value when the function is called.
When execution returns to the calling
program, the argument value remains
unchanged.

VISION 4GL

The Unify VISION fourth-generation

language used to create scripts and
global functions.
VISION Runtime Manager
The Unify VISION runtime

component that executes an

application partition.
write lock
An instruction that prevents both read
and write access to a specified
database row or table by all
transactions other than the transaction
that placed the write lock.
See also read lock.
zoom form
A type of child form that displays
information related to the current
form and that can return values to the
current form.

Unify VISION: 4GL Reference