Reference: Statements and Options

SAP Sybase IQ 16.0 SP01

DOCUMENT ID: DC00801-01-1601-01

LAST REVISED: May 2013

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of

SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software

vendors. National product specifications may vary.

These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only,

without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the

materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty

statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional

warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered

trademarks of SAP AG in Germany and other countries. Please see

http://www.sap.com/corporate-en/legal/copyright/

index.epx#trademark

for additional trademark information and notices.

Contents

Audience.................................................................................1

SQL Statements.....................................................................3

Common Elements in SQL Syntax.................................3

Syntax Conventions ........................................................4

Statement Applicability Indicators...................................5

ALLOCATE DESCRIPTOR Statement [ESQL] ...............5

ALTER DATABASE Statement........................................7

ALTER DBSPACE Statement.........................................9

ALTER DOMAIN Statement ..........................................13

ALTER EVENT Statement ............................................14

ALTER FUNCTION Statement ......................................16

ALTER INDEX Statement .............................................17

ALTER LDAP SERVER Statement...............................20

ALTER LOGICAL SERVER Statement .........................22

ALTER LOGIN POLICY Statement ...............................24

LDAP Login Policy Options..................................29

Multiplex Login Policy Configuration....................30

Logical Server Access Configuration...................30

ALTER LS POLICY Statement ......................................32

LS Policy Options .................................................33

ALTER MULTIPLEX RENAME Statement....................34

ALTER MULTIPLEX SERVER Statement .....................35

ALTER PROCEDURE Statement.................................36

ALTER ROLE Statement..............................................38

ALTER SEQUENCE statement.....................................40

ALTER SERVER Statement ..........................................41

ALTER SERVICE Statement .........................................44

ALTER SPATIAL REFERENCE SYSTEM Statement ...46

ALTER TABLE Statement .............................................52

ALTER TEXT INDEX Statement ...................................66

Reference: Statements and Options iii

ALTER TEXT CONFIGURATION Statement ................68

ALTER TRIGGER statement ........................................70

ALTER USER Statement ..............................................71

ALTER VIEW Statement ...............................................75

Identifying and Fixing Invalid Dependent Views

.........................................................................77

BACKUP Statement......................................................78

BEGIN … END Statement............................................84

BEGIN PARALLEL IQ … END PARALLEL IQ

Statement.................................................................87

BEGIN TRANSACTION Statement [T-SQL].................88

CALL Statement...........................................................90

CASE Statement...........................................................92

CHECKPOINT Statement.............................................94

CLEAR Statement [Interactive SQL].............................94

CLOSE Statement [ESQL] [SP]....................................95

COMMENT Statement..................................................96

COMMIT Statement....................................................102

CONFIGURE Statement [Interactive SQL].................104

CONNECT Statement [ESQL] [Interactive SQL]........104

CREATE DATABASE Statement .................................107

CREATE DBSPACE Statement...................................117

CREATE DOMAIN Statement.....................................121

CREATE EVENT Statement.......................................123

CREATE EXISTING TABLE Statement......................129

CREATE EXTERNLOGIN Statement.........................131

CREATE FUNCTION Statement.................................133

CREATE FUNCTION Statement (Java UDF)....139

CREATE INDEX Statement........................................142

CREATE LDAP SERVER Statement..........................150

CREATE LOGICAL SERVER Statement ....................153

CREATE LOGIN POLICY Statement..........................155

LDAP Login Policy Options................................160

Multiplex Login Policy Configuration..................161

Contents

iv SAP Sybase IQ

CREATE LS POLICY Statement.................................162

CREATE MESSAGE Statement [T-SQL]....................163

CREATE MULTIPLEX SERVER Statement ................164

CREATE PROCEDURE Statement............................165

Referencing Temporary Tables Within

Procedures....................................................172

CREATE PROCEDURE Statement [T-SQL]...............172

CREATE PROCEDURE Statement (External

Procedures)............................................................175

CREATE PROCEDURE Statement (Java UDF) 181

CREATE PROCEDURE Statement (Table UDF)

.......................................................................183

CREATE ROLE Statement.........................................187

CREATE SCHEMA Statement....................................189

CREATE SEQUENCE statement................................190

CREATE SERVER Statement .....................................192

CREATE SERVICE Statement ....................................194

CREATE SPATIAL REFERENCE SYSTEM Statement

................................................................................197

CREATE SPATIAL UNIT OF MEASURE Statement ..204

CREATE TABLE Statement........................................205

CREATE TEXT CONFIGURATION Statement...........222

CREATE TEXT INDEX Statement..............................223

CREATE TRIGGER statement...................................224

CREATE USER Statement.........................................230

CREATE VARIABLE Statement ..................................232

CREATE VIEW Statement..........................................234

DEALLOCATE DESCRIPTOR Statement [ESQL] ......237

Declaration Section [ESQL]........................................237

DECLARE Statement.................................................238

DECLARE CURSOR Statement [ESQL] [SP]............240

DECLARE CURSOR Statement [T-SQL]....................245

DECLARE LOCAL TEMPORARY TABLE Statement .246

DELETE Statement....................................................248

DELETE (positioned) Statement [ESQL] [SP]............250

Contents

Reference: Statements and Options v

DESCRIBE Statement [ESQL]...................................251

DISCONNECT Statement [Interactive SQL]...............254

DROP Statement........................................................255

DROP CONNECTION Statement...............................259

DROP DATABASE Statement.....................................260

DROP EXTERNLOGIN Statement.............................261

DROP LDAP SERVER Statement..............................262

DROP LOGIN POLICY Statement..............................263

DROP LOGICAL SERVER Statement........................264

DROP LS POLICY Statement....................................265

DROP MULTIPLEX SERVER Statement....................265

DROP ROLE Statement .............................................266

DROP SEQUENCE statement...................................268

DROP SERVER Statement........................................269

DROP SERVICE Statement.......................................269

DROP SPATIAL REFERENCE SYSTEM Statement . 270

DROP SPATIAL UNIT OF MEASURE Statement ......271

DROP STATEMENT Statement [ESQL].....................271

DROP TEXT CONFIGURATION Statement...............272

DROP TEXT INDEX Statement..................................273

DROP TRIGGER statement.......................................274

DROP USER Statement.............................................275

DROP VARIABLE Statement......................................276

EXECUTE Statement [ESQL].....................................276

EXECUTE Statement [T-SQL]....................................278

EXECUTE IMMEDIATE Statement [ESQL] [SP]........279

EXIT Statement [Interactive SQL]...............................282

FETCH Statement [ESQL] [SP]..................................283

FOR Statement...........................................................286

FOR JSON Statement................................................289

FORWARD TO Statement ..........................................294

FROM Clause.............................................................295

GET DESCRIPTOR Statement [ESQL] ......................303

GOTO Statement [T-SQL] ...........................................304

GRANT CHANGE PASSWORD Statement................304

Contents

vi SAP Sybase IQ

GRANT CONNECT Statement...................................306

GRANT CREATE Statement.......................................308

GRANT Object-Level Privilege Statement ..................309

GRANT EXECUTE Statement....................................310

GRANT INTEGRATED LOGIN Statement..................311

GRANT KERBEROS LOGIN Statement.....................312

GRANT ROLE Statement...........................................312

GRANT SET USER Statement...................................317

GRANT System Privilege Statement ..........................319

List of All System Privileges ...............................320

GRANT USAGE ON SEQUENCE Statement.............323

IF Statement...............................................................323

IF Statement [T-SQL]..................................................325

INCLUDE Statement [ESQL]......................................326

INSERT Statement.....................................................327

INSTALL JAVA Statement...........................................336

IQ UTILITIES Statement.............................................338

LEAVE Statement.......................................................342

LOAD TABLE Statement.............................................343

Storage Sizes....................................................361

LOCK TABLE Statement.............................................362

LOOP Statement........................................................364

MESSAGE Statement.................................................366

OPEN Statement [ESQL] [SP]....................................369

OUTPUT Statement [Interactive SQL]........................371

PARAMETERS Statement [Interactive SQL]..............374

PREPARE Statement [ESQL].....................................375

PRINT Statement [T-SQL]..........................................378

PUT Statement [ESQL]...............................................379

RAISERROR Statement [T-SQL]................................381

READ Statement [Interactive SQL].............................382

REFRESH TEXT INDEX Statement...........................384

RELEASE SAVEPOINT Statement............................386

REMOVE Statement ...................................................387

RESIGNAL Statement................................................388

Contents

Reference: Statements and Options vii

RESTORE DATABASE Statement..............................389

RESUME Statement...................................................395

RETURN Statement...................................................396

REVOKE CHANGE PASSWORD Statement .............398

REVOKE CONNECT Statement .................................399

REVOKE CREATE Statement ....................................400

REVOKE EXECUTE Statement .................................401

REVOKE INTEGRATED LOGIN Statement ................401

REVOKE KERBEROS LOGIN Statement..................402

REVOKE Object-Level Privilege Statement ................403

REVOKE ROLE Statement.........................................404

REVOKE SET USER Statement ................................407

REVOKE System Privilege Statement........................408

List of All System Privileges ...............................410

REVOKE USAGE ON SEQUENCE Statement..........412

ROLLBACK Statement ...............................................413

ROLLBACK TO SAVEPOINT Statement....................413

ROLLBACK TRANSACTION Statement [T-SQL] ........414

SAVEPOINT Statement..............................................415

SAVE TRANSACTION Statement [T-SQL] .................416

SELECT Statement....................................................417

SET Statement [ESQL]...............................................426

SET Statement [T-SQL]..............................................427

SET CONNECTION Statement [ESQL] [Interactive

SQL].......................................................................429

SET DESCRIPTOR Statement [ESQL] ......................430

SET OPTION Statement.............................................431

SET OPTION Statement [Interactive SQL] ................434

SET SQLCA Statement [ESQL]..................................435

SETUSER Statement.................................................436

SIGNAL Statement.....................................................437

START DATABASE Statement [Interactive SQL]........438

START ENGINE Statement [Interactive SQL] .............439

START JAVA Statement ..............................................440

STOP DATABASE Statement [Interactive SQL]..........441

Contents

viii SAP Sybase IQ

STOP ENGINE Statement [Interactive SQL]..............442

STOP JAVA Statement...............................................442

TRIGGER EVENT Statement.....................................443

TRUNCATE Statement ...............................................444

TRUNCATE TEXT INDEX Statement ........................445

UNION Operation.......................................................446

UPDATE Statement ....................................................448

UPDATE (positioned) Statement [ESQL] [SP] ............451

VALIDATE Statement..................................................453

VALIDATE LDAP SERVER Statement........................455

WAITFOR Statement ..................................................458

WHENEVER Statement [ESQL].................................459

WHILE Statement [T-SQL]..........................................460

Database Options..............................................................463

Introduction to Database Options...............................463

Current Option Settings.....................................464

Scope and Duration of Database Options.........465

Temporary Options............................................466

PUBLIC Options................................................466

SECURITY Options...........................................466

SYSTEM Options...............................................467

Delete an Option Setting....................................467

Initial Option Settings.........................................468

Deprecated Database Options..........................469

General Database Options.........................................469

Data Extraction Options.....................................474

Transact-SQL Compatibility Options...........................474

Transact-SQL Option Settings for Adaptive

Server Enterprise Compatibility .....................475

Interactive SQL Options..............................................476

Alphabetical List of Options........................................477

AFFINITY_AUTOEXCLUDE_TIMEOUT Option

.......................................................................477

AGGREGATION_PREFERENCE Option ..........478

Contents

Reference: Statements and Options ix

ALLOW_NULLS_BY_DEFAULT Option [TSQL]

.......................................................................479

ALLOW_SNAPSHOT_VERSIONING Option ....480

ANSI_CLOSE_CURSORS_ON_ROLLBACK

Option [TSQL]...............................................480

ANSI_PERMISSIONS Option [TSQL]...............481

ANSINULL Option [TSQL].................................482

ANSI_SUBSTRING Option [TSQL]...................483

ANSI_UPDATE_CONSTRAINTS Option ...........484

ALLOW_READ_CLIENT_FILE Option..............485

ASE_BINARY_DISPLAY Option ........................486

ASE_FUNCTION_BEHAVIOR Option...............487

AUDITING Option [database] ............................488

BASE_TABLES_IN_RLV_STORE Option..........488

BIT_VECTOR_PINNABLE_CACHE_PERCEN

T Option.........................................................489

BLOCKING Option.............................................490

BLOCKING_TIMEOUT Option..........................490

BT_PREFETCH_MAX_MISS Option.................491

BT_PREFETCH_SIZE Option...........................492

BTREE_PAGE_SPLIT_PAD_PERCENT Option

.......................................................................493

CACHE_AFFINITY_PERCENT Option.............494

CACHE_PARTITIONS Option............................494

CHAINED Option [TSQL]...................................495

CHECKPOINT_TIME Option.............................496

CIS_ROWSET_SIZE Option ..............................497

CLOSE_ON_ENDTRANS Option [TSQL].........497

CONTINUE_AFTER_RAISERROR Option

[TSQL]...........................................................498

CONVERSION_ERROR Option [TSQL]............499

CONVERSION_MODE Option..........................499

CONVERT_VARCHAR_TO_1242 Option..........506

COOPERATIVE_COMMIT_TIMEOUT Option...506

COOPERATIVE_COMMITS Option...................507

Contents

x SAP Sybase IQ

CREATE_HG_WITH_EXACT_DISTINCTS.......508

CREATE_HG_AND_FORCE_PHYSICAL_DEL

ETE...............................................................509

CURSOR_WINDOW_ROWS Option.................510

DATE_FIRST_DAY_OF_WEEK Option.............510

DATE_FORMAT Option .....................................512

DATE_ORDER Option .......................................514

DBCC_LOG_PROGRESS Option.....................514

DBCC_PINNABLE_CACHE_PERCENT Option

.......................................................................515

DEBUG_MESSAGES Option ............................516

DEDICATED_TASK Option................................517

DEFAULT_DBSPACE Option.............................517

DEFAULT_DISK_STRIPING Option ..................519

DEFAULT_HAVING_SELECTIVITY_PPM

Option............................................................519

DEFAULT_ISQL_ENCODING Option

[Interactive SQL]............................................520

DEFAULT_KB_PER_STRIPE Option ................521

DEFAULT_LIKE_MATCH_SELECTIVITY_PPM

Option............................................................522

DEFAULT_LIKE_RANGE_SELECTIVITY_PPM

Option............................................................523

DEFAULT_PROXY_TABLE_ROW_COUNT

Option............................................................523

DEFAULT_TABLE_UDF_ROW_COUNT Option

.......................................................................524

DELAYED_COMMIT_TIMEOUT Option............525

DELAYED_COMMITS Option............................525

DISABLE_RI_CHECK Option............................526

DIVIDE_BY_ZERO_ERROR Option [TSQL] .....526

DQP_ENABLED Option.....................................527

DQP_ENABLED_OVER_NETWORK Option....528

EARLY_PREDICATE_EXECUTION Option.......528

ENABLE_ASYNC_IO Option.............................530

Contents

Reference: Statements and Options xi

ENABLE_LOB_VARIABLES Option ..................530

EXTENDED_JOIN_SYNTAX Option.................531

FLOATING_POINT_ACCUMULATOR Option ....532

FORCE_DROP Option......................................532

FORCE_NO_SCROLL_CURSORS Option.......533

FORCE_UPDATABLE_CURSORS Option ........534

FP_LOOKUP_SIZE Option................................535

FP_LOOKUP_SIZE_PPM Option......................535

FP_NBIT_AUTOSIZE_LIMIT Option.................536

FP_NBIT_ENFORCE_LIMITS Option...............538

FP_NBIT_IQ15_COMPATIBILITY Option..........539

FP_NBIT_LOOKUP_MB Option........................540

FP_NBIT_ROLLOVER_MAX_MB Option..........542

FP_PREDICATE_WORKUNIT_PAGES Option

.......................................................................543

FPL_EXPRESSION_MEMORY_KB Option ......543

GARRAY_FILL_FACTOR_PERCENT Option ....544

GARRAY_INSERT_PREFETCH_SIZE Option..545

GARRAY_PAGE_SPLIT_PAD_PERCENT

Option............................................................545

GARRAY_RO_PREFETCH_SIZE Option..........546

HASH_PINNABLE_CACHE_PERCENT Option

.......................................................................547

HASH_THRASHING_PERCENT Option...........548

HG_DELETE_METHOD Option........................548

HG_SEARCH_RANGE Option..........................549

HTTP_SESSION_TIMEOUT Option..................550

IDENTITY_ENFORCE_UNIQUENESS Option. 551

IDENTITY_INSERT Option................................551

IN_SUBQUERY_PREFERENCE Option...........552

INDEX_ADVISOR Option..................................554

INDEX_ADVISOR_MAX_ROWS Option...........556

INDEX_PREFERENCE Option..........................557

INFER_SUBQUERY_PREDICATES Option ......558

IQGOVERN_MAX_PRIORITY Option ...............559

Contents

xii SAP Sybase IQ

IQGOVERN_PRIORITY Option .........................559

IQGOVERN_PRIORITY_TIME Option ..............560

ISOLATION_LEVEL Option...............................561

JAVA_LOCATION Option ...................................561

JAVA_VM_OPTIONS Option.............................562

JOIN_EXPANSION_FACTOR Option ................562

JOIN_OPTIMIZATION Option............................563

JOIN_PREFERENCE Option............................565

JOIN_SIMPLIFICATION_THRESHOLD Option

.......................................................................567

LF_BITMAP_CACHE_KB Option......................567

LOAD_ZEROLENGTH_ASNULL Option ...........568

LOG_CONNECT Option....................................569

LOG_CURSOR_OPERATIONS Option.............570

LOG_DEADLOCKS Option...............................570

LOGIN_MODE Option.......................................571

LOGIN_PROCEDURE Option...........................572

MAIN_RESERVED_DBSPACE_MB Option......572

MAX_CARTESIAN_RESULT Option .................573

MAX_CLIENT_NUMERIC_PRECISION Option

.......................................................................574

MAX_CLIENT_NUMERIC_SCALE Option........575

MAX_CUBE_RESULT Option ............................576

MAX_CURSOR_COUNT Option.......................576

MAX_HASH_ROWS Option ..............................577

MAX_IQ_THREADS_PER_CONNECTION

Option............................................................578

MAX_IQ_THREADS_PER_TEAM Option.........578

MAX_JOIN_ENUMERATION Option.................579

MAX_PARTITIONED_HASH_MB Option..........580

MAX_PREFIX_PER_CONTAINS_PHRASE

Option............................................................581

MAX_QUERY_PARALLELISM Option...............581

MAX_QUERY_TIME Option..............................582

MAX_STATEMENT_COUNT Option..................583

Contents

Reference: Statements and Options xiii

MAX_TEMP_SPACE_PER_CONNECTION

Option............................................................583

MINIMIZE_STORAGE Option............................585

MIN_PASSWORD_LENGTH Option.................586

MIN_ROLE_ADMINS Option.............................586

MONITOR_OUTPUT_DIRECTORY Option .......587

MPX_AUTOEXCLUDE_TIMEOUT Option.........588

MPX_HEARTBEAT_FREQUENCY Option ........588

MPX_IDLE_CONNECTION_TIMEOUT Option

.......................................................................589

MPX_LIVENESS_TIMEOUT Option..................589

MPX_MAX_CONNECTION_POOL_SIZE

Option............................................................590

MPX_MAX_UNUSED_POOL_SIZE Option......591

MPX_WORK_UNIT_TIMEOUT Option..............591

NEAREST_CENTURY Option [TSQL] ...............592

NOEXEC Option................................................593

NON_ANSI_NULL_VARCHAR Option ..............593

NON_KEYWORDS Option [TSQL]....................594

NOTIFY_MODULUS Option ..............................595

ODBC_DISTINGUISH_CHAR_AND_VARCHA

R Option........................................................595

ON_CHARSET_CONVERSION_FAILURE

Option............................................................596

ON_ERROR Option [Interactive SQL]...............597

ON_TSQL_ERROR Option [TSQL]...................598

OS_FILE_CACHE_BUFFERING Option...........599

OS_FILE_CACHE_BUFFERING_TEMPDB

Option............................................................600

POST_LOGIN_PROCEDURE Option...............601

PRECISION Option...........................................602

PREFETCH Option............................................603

PREFETCH_BUFFER_LIMIT Option................603

PREFETCH_BUFFER_PERCENT Option........604

PREFETCH_GARRAY_PERCENT Option........604

Contents

xiv SAP Sybase IQ

PREFETCH_SORT_PERCENT Option.............605

PRESERVE_SOURCE_FORMAT Option

[database]......................................................606

QUERY_DETAIL Option ....................................606

QUERY_NAME Option...................................... 607

QUERY_PLAN Option....................................... 608

QUERY_PLAN_AFTER_RUN Option ................608

QUERY_PLAN_AS_HTML Option.....................609

QUERY_PLAN_AS_HTML_DIRECTORY

Option............................................................611

QUERY_PLAN_MIN_TIME Option....................612

QUERY_PLAN_TEXT_ACCESS Option...........613

QUERY_PLAN_TEXT_CACHING Option.........614

QUERY_ROWS_RETURNED_LIMIT Option....615

QUERY_TEMP_SPACE_LIMIT Option..............615

QUERY_TIMING Option....................................616

QUOTED_IDENTIFIER Option [TSQL] ..............617

RECOVERY_TIME Option .................................618

RESERVED_KEYWORDS Option.....................618

RETURN_DATE_TIME_AS_STRING Option .... 619

REVERT_TO_V15_OPTIMIZER Option ............620

ROUND_TO_EVEN Option...............................620

ROW_COUNT Option ........................................621

RV_AUTO_MERGE_EVAL_INTERVAL Option

.......................................................................622

RV_MAX_ACTIVE_SUBFRAGMENT_COUNT

Option............................................................623

RV_MERGE_NODE_MEMSIZE Option ............623

RV_MERGE_TABLE_MEMPERCENT Option ...624

RV_MERGE_TABLE_NUMROWS Option .........625

RV_RESERVED_DBSPACE_MB Option...........625

SCALE Option...................................................626

SNAPSHOT_VERSIONING Option ...................627

SIGNIFICANTDIGITSFORDOUBLEEQUALITY

Option............................................................628

Contents

Reference: Statements and Options xv

SORT_COLLATION Option ...............................628

SORT_PINNABLE_CACHE_PERCENT Option

.......................................................................629

SQL_FLAGGER_ERROR_LEVEL Option

[TSQL]...........................................................630

SQL_FLAGGER_WARNING_LEVEL Option

[TSQL]...........................................................631

STRING_RTRUNCATION Option [TSQL] ..........632

SUBQUERY_CACHING_PREFERENCE

Option............................................................633

SUBQUERY_FLATTENING_PERCENT Option

.......................................................................634

SUBQUERY_FLATTENING_PREFERENCE

Option............................................................635

SUBQUERY_PLACEMENT_PREFERENCE

Option............................................................636

SUPPRESS_TDS_DEBUGGING Option..........637

SWEEPER_THREADS_PERCENT Option.......638

TDS_EMPTY_STRING_IS_NULL Option

[database]......................................................638

TEMP_EXTRACT_APPEND Option..................639

TEMP_EXTRACT_BINARY Option...................640

TEMP_EXTRACT_COLUMN_DELIMITER

Option............................................................641

TEMP_EXTRACT_DIRECTORY Option ............642

TEMP_EXTRACT_ESCAPE_QUOTES Option

.......................................................................643

TEMP_EXTRACT_NAMEn Options..................643

TEMP_EXTRACT_NULL_AS_EMPTY Option

.......................................................................645

TEMP_EXTRACT_NULL_AS_ZERO Option.....646

TEMP_EXTRACT_QUOTE Option....................647

TEMP_EXTRACT_QUOTES Option.................648

TEMP_EXTRACT_QUOTES_ALL Option.........648

TEMP_EXTRACT_ROW_DELIMITER Option...649

Contents

xvi SAP Sybase IQ

TEMP_EXTRACT_SIZEn Options.....................650

TEMP_EXTRACT_SWAP Option......................651

TEMP_RESERVED_DBSPACE_MB Option.....652

TEMP_SPACE_LIMIT_CHECK Option..............652

TEXT_DELETE_METHOD Option....................653

TIME_FORMAT Option......................................654

TIMESTAMP_FORMAT Option..........................655

TOP_NSORT_CUTOFF_PAGES Option...........656

TRIM_PARTIAL_MBC Option............................657

TRUSTED_CERTIFICATES_FILE Option .........658

TSQL_VARIABLES Option [TSQL] ....................658

USER_RESOURCE_RESERVATION Option ....659

VERIFY_PASSWORD_FUNCTION Option.......659

WASH_AREA_BUFFERS_PERCENT Option

.......................................................................662

WAIT_FOR_COMMIT Option ............................663

WD_DELETE_METHOD Option........................663

Index ................................................................................665

Contents

Reference: Statements and Options xvii

Contents

xviii SAP Sybase IQ

Audience

This book is for Sybase

IQ users who require reference material for SAP

Sybase

IQ SQL

statements and database options.

Reference material for other aspects of SAP Sybase IQ, including language elements, data

types, functions, system procedures, and system tables is provided in

Reference: Building

Blocks, Tables, and Procedures

. Other books provide more context on how to perform

particular tasks. This reference book is the place to look for information such as available SQL

syntax, parameters, and options. For command line utility start-up parameters, see the

Utility

Guide

Audience

Reference: Statements and Options 1

Audience

2 SAP Sybase IQ

SQL Statements

Descriptions of the SQL statements available in SAP Sybase IQ, including some that can be

used only from Embedded SQL or Interactive SQL.

Common Elements in SQL Syntax

Language elements that are found in the syntax of many SQL statements.

For more information on the elements described here, see

Identifiers

Search Conditions

Expressions

, and

Strings

Reference: Building Blocks, Tables, and Procedures > SQL

Language Elements

• column-name – an identifier that represents the name of a column.

• condition – an expression that evaluates to TRUE, FALSE, or UNKNOWN.

• connection-name – a string representing the name of an active connection.

• data-type – a storage data type.

• expression – an expression.

• filename – a string containing a file name.

• host-variable – a C language variable, declared as a host variable, preceded by a colon.

• indicator-variable – a second host variable of type short int immediately following a

normal host variable. An indicator variable must also be preceded by a colon. Indicator

variables are used to pass NULL values to and from the database.

• number – any sequence of digits followed by an optional decimal part and preceded by an

optional negative sign. Optionally, the number can be followed by an ‘e’ and then an

exponent. For example,

-4.038

.001

3.4e10

1e-10

• owner – an identifier representing the user ID who owns a database object.

• role-name – an identifier representing the role name of a foreign key.

• savepoint-name – an identifier that represents the name of a savepoint.

• search-condition – a condition that evaluates to TRUE, FALSE, or UNKNOWN.

• special-value – one of the special values described in

Reference: Building Blocks, Tables,

and Procedures > SQL Language Elements > Special Values

• statement-label – an identifier that represents the label of a loop or compound statement.

• table-list – a list of table names, which might include correlation names. For more

information, see

FROM clause

SQL Statements

Reference: Statements and Options 3

• table-name – an identifier that represents the name of a table.

• userid – an identifier representing a user name. The user ID is not case-sensitive and is

unaffected by the setting of the CASE RESPECT property of the database.

• variable-name – an identifier that represents a variable name.

See also

•

FROM Clause

on page 295

Syntax Conventions

Conventions used in the SQL syntax descriptions.

• Keywords – all SQL keywords appear in UPPERCASE; however, SQL keywords are case-

insensitive, so you can type keywords in any case. For example, SELECT is the same as

Select, which is the same as select.

• Placeholders – items that must be replaced with appropriate identifiers or expressions are

shown in

italics

• Continuation – lines beginning with an ellipsis ( … ) are a continuation from the previous

line.

• Optional portions – optional portions of a statement are enclosed by square brackets. For

example:

RELEASE SAVEPOINT [ savepoint-name ]

This example indicates that the

savepoint-name

is optional. Do not type the square

brackets.

• Repeating items – lists of repeating items are shown with an element of the list followed by

an ellipsis. One or more list elements are allowed. When more than one is specified, they

must be separated by commas if indicated as such. For example:

UNIQUE ( column-name [ , ... ] )

The example indicates that you can specify

column-name

more than once, separated by

commas. Do not type the square brackets.

• Alternatives – when one option must be chosen, the alternatives are enclosed in curly

braces. For example:

[ QUOTES { ON | OFF } ]

The example indicates that if you choose the QUOTES option, you must provide one of

ON or OFF. Do not type the braces.

• One or more options – if you choose more than one, separate your choices by commas. For

example:

{ CONNECT, DBA, RESOURCE }

SQL Statements

4 SAP Sybase IQ

Statement Applicability Indicators

Some statement titles are followed by an indicator in square brackets that shows where the

statement can be used.

These indicators are as follows:

• [ESQL] – the statement is for use in Embedded SQL.

• [Interactive SQL] – the statement is for use only in Interactive SQL (dbisql).

• [SP] – the statement is for use in stored procedures or batches.

• [T-SQL] – the statement is implemented for compatibility with Adaptive Server

Enterprise. In some cases, the statement cannot be used in stored procedures that are not

Transact-SQL format. In other cases, there is an alternative statement that is closer to the

ISO/ANSI SQL standard that is recommended unless Transact-SQL compatibility is an

issue.

If two sets of brackets are used, the statement can be used in both environments. For example,

[ESQL] [SP] means a statement can be used either in Embedded SQL or in stored procedures.

ALLOCATE DESCRIPTOR Statement [ESQL]

Allocates space for a SQL descriptor area (SQLDA).

Syntax

ALLOCATE DESCRIPTOR descriptor-name

… [ WITH MAX { integer | host-variable } ]

Parameters

•

WITH MAX – lets you specify the number of variables within the descriptor area. The

default size is 1.

Examples

•

Example 1 – this sample program includes an example of ALLOCATE DESCRIPTOR

statement usage:

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

EXEC SQL INCLUDE SQLCA;

#include <sqldef.h>

EXEC SQL BEGIN DECLARE SECTION;

SQL Statements

Reference: Statements and Options 5

int x;

short type;

int numcols;

char string[100];

a_sql_statement_number stmt = 0;

EXEC SQL END DECLARE SECTION;

int main(int argc, char * argv[])

{

struct sqlda * sqlda1;

if( !db_init( &sqlca ) ) {

return 1;

}

db_string_connect(&sqlca, "UID=dba;PWD=sql;DBF=d:\\IQ-16_0\

\sample.db");

EXEC SQL ALLOCATE DESCRIPTOR sqlda1 WITH MAX 25;

EXEC SQL PREPARE :stmt FROM

'select * from Employees';

EXEC SQL DECLARE curs CURSOR FOR :stmt;

EXEC SQL OPEN curs;

EXEC SQL DESCRIBE :stmt into sqlda1;

EXEC SQL GET DESCRIPTOR sqlda1 :numcols=COUNT;

// how many columns?

if( numcols > 25 ) {

// reallocate if necessary

EXEC SQL DEALLOCATE DESCRIPTOR sqlda1;

EXEC SQL ALLOCATE DESCRIPTOR sqlda1

WITH MAX :numcols;

}

type = DT_STRING; // change the type to string

EXEC SQL SET DESCRIPTOR sqlda1 VALUE 2 TYPE = :type;

fill_sqlda( sqlda1 ); // allocate space for the variables

EXEC SQL FETCH ABSOLUTE 1 curs USING DESCRIPTOR sqlda1;

EXEC SQL GET DESCRIPTOR sqlda1 VALUE 2 :string = DATA;

printf("name = %s", string );

EXEC SQL DEALLOCATE DESCRIPTOR sqlda1;

EXEC SQL CLOSE curs;

EXEC SQL DROP STATEMENT :stmt;

db_string_disconnect( &sqlca, "" );

db_fini( &sqlca );

return 0;

}

Usage

You must declare the following in your C code prior to using this statement:

SQL Statements

6 SAP Sybase IQ

struct sqlda * descriptor_name

You must still call fill_sqlda to allocate space for the actual data items before doing a fetch or

any statement that accesses the data within a descriptor area.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Open Client/Open Server.

See also

•

DEALLOCATE DESCRIPTOR Statement [ESQL]

on page 237

ALTER DATABASE Statement

Upgrades a database created with a previous version of the software, adds or removes

jConnect

™

for JDBC

™

support, or defines management of system procedure execution. Run

this statement with DBISQL Interactive SQL.

Syntax

ALTER DATABASE UPGRADE

[ PROCEDURE ON ]

[ JCONNECT { ON | OFF } ]

[ RESTART { ON | OFF } ]

[ SYSTEM PROCEDURE AS DEFINER {ON | OFF} ]

Parameters

•

PROCEDURE – drops and re-creates all dbo- and sys-owned procedures in the database.

•

JCONNECT – to allow the SAP Sybase IQ jConnect JDBC driver to access system

catalog information, you must specify ON. This installs jConnect system tables and

procedures. To exclude the jConnect system objects, specify OFF. You can still use JDBC,

as long as you do not access system catalog information. The default is to include jConnect

support (JCONNECT ON).

•

RESTART – when ON (default) is specified and the AutoStop connection parameter is set

to NO, the database restarts after it is upgraded. Otherwise, the database is stopped after an

upgrade.

•

SYSTEM PROCEDURE AS DEFINER – defines whether a privileged system

procedure runs with the privileges of the invoker (the person executing the procedure) or

the definer (the owner of the procedure).

•

OFF – all privileged system procedures execute with the privileges of the invoker. Use

sp_proc_priv() to identify the system privileges required to run a system procedure.

SQL Statements

Reference: Statements and Options 7

•

ON (default), or not specified –

• when upgrading a pre-16.0 database, pre-16.0 privileged system procedures

execute with the privileges of the definer and 16.0 or later privileged system

procedures execute with the privileges of the invoker.

• when upgrading a database that is version 16.0 or later, the default is the behavior of

the database being upgraded.

Note: Changing the execution model after upgrade may result in loss of functionality on

custom stored procedures and applications that explicitly grant EXECUTE privilege on

system procedures. It may also impact the ability to run system procedures. See

Reference:

Building Blocks, Tables, and Procedures > System Procedures

Examples

•

Example 1 – disables jConnect support:

ALTER DATABASE UPGRADE JCONNECT OFF

Usage

The ALTER DATABASE statement upgrades databases created with earlier versions of the

software. This applies to maintenance releases as well as major releases.

When you upgrade a database, SAP Sybase IQ makes these changes:

• Upgrades the system tables to the current version.

• Adds any new database options.

• Enables new features in the current version.

You can also use ALTER DATABASE UPGRADE simply to add jConnect features, if the

database was created with the current version of the software.

Note:

• See the

Installation and Configuration Guide

for backup recommendations before you

upgrade.

• Be sure to start the server in a way that restricts user connections before you run ALTER

DATABASE UPGRADE. For instructions and other upgrade caveats, see the

Migration

guide for your platform.

• Use the iqunload utility to upgrade databases created in versions earlier than 15.0. See the

Migration

guide for your platform.

After using ALTER DATABASE UPGRADE, shut down the database.

Side effects:

• Automatic commit

SQL Statements

8 SAP Sybase IQ

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires the ALTER DATABASE system privilege.

See also

•

CREATE DATABASE Statement

on page 107

ALTER DBSPACE Statement

Changes the read/write mode, changes the size, or extends an existing dbspace.

Syntax

ALTER DBSPACE dbspace-name

{ ADD new-file-spec [, new-file-spec ... ]

| DROP FILE logical-file-name [, FILE logical-file-name ... ]

| RENAME TO newname | RENAME 'new-file-pathname'

| READONLY | READWRITE

| ONLINE | OFFLINE

| STRIPING{ ON | OFF }

| STRIPESIZEKB size-in-KB

ALTER FILE file-name

{ READONLY | [ FORCE ] READWRITE }

| SIZE file-size [ KB | MB | GB | TB ]

| ADD file-size [ KB | MB | GB | TB | PAGES ] }

RENAME PATH 'new-file-pathname'

RENAME TO newname

new-file-spec:

FILE logical-file-name 'file-path' iq-file-opts

iq-file-opts:

[ [ SIZE ] file-size ]

…[ KB | MB | GB | TB ] ]

[ RESERVE reserve-size [ KB | MB | GB | TB ] ]

Parameters

•

ADD – adds one or more files to the specified dbspace. The dbfile name and the physical

file path are required for each file and must be unique. You can add files to IQ main, IQ

shared temporary, or IQ temporary dbspaces. You may add a file to a read-only dbspace,

but the dbspace remains read-only. You can add files to multiplex shared temporary

dbspaces only in read-only mode (the default for ADD FILE).

SQL Statements

Reference: Statements and Options 9

A catalog dbspace may contain only one file, so ADD FILE may not be used on catalog

dbspaces.

For an RLV dbspace, use ADD FILE on simplex servers only. You cannot add a file to a

multiplex RLV dbspace.

When used in the ALTER FILE clause, extends the size of the file in units of pages,

kilobytes (KB), megabytes (MB), gigabytes (GB), or terabytes (TB). The default is MB.

You can ADD only if the free list (an allocation map) has sufficient room and if the dbspace

has sufficient reserved space.

•

DROP FILE – removes the specified file from an IQ dbspace. The file must be empty. You

cannot drop the last file from the specified dbspace. Instead use DROP DBSPACE if the

dbspace contains only one file. Rename TO clause—Renames the

dbspace-name

to a new

name. The new name must be unique in the database. You cannot rename

IQ_SYSTEM_MAIN, IQ_SYSTEM_MSG, IQ_SYSTEM_TEMP, IQ_SHARED_TEMP,

or SYSTEM.

•

RENAME TO – when used with the DROP FILE clause, renames the pathname of the

dbspace that contains a single file. It is semantically equivalent to the RENAME PATH

clause. An error is returned if the dbspace contains more than one file.

When used with the ALTER FILE clause, renames the specified file’s logical name to a

new name. The new name must be unique in the database.

•

READONLY – when used with the DROP clause, changes any dbspace except

IQ_SYSTEM_MAIN, IQ_SYSTEM_TEMP, IQ_SYSTEM_MSG, IQ_SHARED_TEMP,

and SYSTEM to read-only. Disallows DML modifications to any object currently assigned

to the dbspace. Can only be used for dbspaces in the IQ main store.

When used with the ALTER FILE clause, changes the specified file to read-only. The file

must be associated with an IQ main dbspace. You cannot change files in

IQ_SHARED_TEMP to READONLY status.

•

READWRITE – when used with the DROP FILE clause, changes the dbspace to read-

write. The dbspace must be online. Can only be used for dbspaces in the IQ main store.

When used with the ALTER FILE clause, changes specified IQ main or temporary store

dbfile to read-write. The file must be associated with an IQ main or temporary dbspace.

•

ONLINE – puts an offline dbspace and all associated files online. Can only be used for

dbspaces in the IQ main store.

•

OFFLINE – puts an online read-only dbspace and all associated files offline. (Returns an

error if the dbspace is read-write, offline already, or not of the IQ main store.) Can only be

used for dbspaces in the IQ main store.

•

STRIPING – changes the disk striping on the dbspace as specified. When disk striping is

set ON, data is allocated from each file within the dbspace in a round-robin fashion. For

SQL Statements

10 SAP Sybase IQ

example, the first database page written goes to the first file, the second page written goes

to the next file within given dbspace, and so on. Read-only dbspaces are skipped.

•

STRIPESIZEKB – specifies the number of kilobytes (KB) to write to each file before the

disk striping algorithm moves to the next stripe for the specified dbspace.

•

FORCE READWRITE – when used with the ALTER FILE clause, changes the status of

the specified shared temporary store dbfile to read-write, although there may be known file

status problems on secondary nodes. The file may be associated with an IQ main, shared

temporary, or temporary dbspace, but because new dbfiles in IQ_SYSTEM_MAIN and

user main are created read-write, this clause only affects shared temporary dbspaces.

•

SIZE – specifies the new size of the file in units of kilobytes (KB), megabytes (MB),

gigabytes (GB), or terabytes (TB). The default is megabytes. You can increase the size of

the dbspace only if the free list (an allocation map) has sufficient room and if the dbspace

has sufficient reserved space. You can decrease the size of the dbspace only if the portion to

be truncated is not in use.

•

RENAME PATH – when used with the ALTER FILE clause, renames the file pathname

associated with the specified file. This clause merely associates the file with the new file

path instead of the old path. The clause does not actually change the operating system file

name. You must change the file name through your operating system. The dbspace must be

offline to rename the file path. The new path is used when the dbspace is altered online or

when the database is restarted.

You may not rename the path of a file in IQ_SYSTEM_MAIN, because if the new path

were not accessible, the database would be unable to start. If you need to rename the path of

a file in IQ_SYSTEM_MAIN, make the file read-only, empty the file, drop the file, and add

the file again with the new file path name. Enclose the physical file path to the dbfile in

single quotes.

Examples

•

Example 1 – changes the mode of a dbspace called DspHist to READONLY:

ALTER DBSPACE DspHist READONLY

•

Example 2 – adds 500MB to the dbspace DspHist by adding the file FileHist3 of

size 500MB:

ALTER DBSPACE DspHist

ALTER FILE FileHist3 ADD 500MB

•

Example 3 – on a UNIX system, adds two 500MB files to the dbspace DspHist:

ALTER DBSPACE DspHist ADD

FILE FileHist3 '/History1/data/file3' SIZE 500MB,

FILE FileHist4 '/History1/data/file4' SIZE 500

•

Example 4 – increases the size of the dbspace IQ_SYSTEM_TEMP by 2GB:

SQL Statements

Reference: Statements and Options 11

ALTER DBSPACE IQ_SYSTEM_TEMP ADD 2 GB

•

Example 5 – removes two files from dbspace DspHist. Both files must be empty:

ALTER DBSPACE DspHist

DROP FILE FileHist2, FILE FileHist4

•

Example 6 – increases the size of the dbspace IQ_SYSTEM_MAIN by 1000 pages. (ADD

clause defaults to pages):

ALTER DBSPACE IQ_SYSTEM_MAIN ADD 1000

Usage

ALTER DBSPACE changes the read-write mode, changes the online/offline state, alters the file

size, renames the dbspace name, file logical name or file path, or sets the dbspace striping

parameters. For details about existing dbspaces, run sp_iqdbspace procedure,

sp_iqdbspaceinfo procedure, sp_iqfile procedure, sp_iqdbspaceobjectinfo, and

sp_iqobjectinfo. Dbspace and dbfile names are always case-insensitive. The physical file

paths are case-sensitive, if the database is CASE RESPECT and the operating system supports

case-sensitive files. Otherwise, the file paths are case-insensitive.

Enclose dbspace and dbfile names either in no quotes or in double quotes.

In Windows, if you specify a path, any backslash characters (\) must be doubled if they are

followed by an n or an x. This prevents them being interpreted as a newline character (\n) or as

a hexadecimal number (\x), according to the rules for strings in SQL. It is safer to always

double the backslash.

Side effects:

• Automatic commit

• Automatic checkpoint

• A mode change to READONLY causes immediate relocation of the internal database

structures on the dbspace to one of the read-write dbspaces.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires the MANAGE ANY DBSPACE system privilege.

See also

•

CREATE DATABASE Statement

on page 107

•

CREATE DBSPACE Statement

on page 117

•

DROP Statement

on page 255

SQL Statements

12 SAP Sybase IQ

ALTER DOMAIN Statement

Renames a user-defined domain or data type. Does not rename Java types.

Syntax

ALTER { DOMAIN | DATATYPE } user-type

RENAME new-name

Parameters

•

new-name – an identifier representing the new domain name.

•

user-type – user-defined data type of the domain being renamed.

Examples

•

Example 1 – renames the Address domain to MailingAddress:

ALTER DOMAIN Address RENAME MailingAddress

Usage

The ALTER DOMAIN statement updates the name of the user-defined domain or data type in

the SYSUSERTYPE system table.

You must recreate any procedures, views or events that reference the user-defined domain or

data type, or else they will continue to reference the former name.

Side effects:

• Automatic commit

Permissions

Must be the database user who created the domain or requires the ALTER DATATYPE or

ALTER ANY OBJECT system privilege.

See also

•

CREATE DOMAIN Statement

on page 121

SQL Statements

Reference: Statements and Options 13

ALTER EVENT Statement

Changes the definition of an event or its associated handler for automating predefined actions.

Also alters the definition of scheduled actions.

Syntax

ALTER EVENT event-name

[ DELETE TYPE | TYPE event-type ]

{ WHERE { trigger-condition | NULL }

| { ADD | [ MODIFY ] | DELETE } SCHEDULE schedule-spec}

[ ENABLE | DISABLE ]

[ [ MODIFY ] HANDLER compound-statement | DELETE HANDLER}

event-type:

BackupEnd

| “Connect”

| ConnectFailed

| DatabaseStart

| DBDiskSpace

| “Disconnect”

| GlobalAutoincrement

| GrowDB

| GrowLog

| GrowTemp

| IQMainDBSpaceFree

| IQTempDBSpaceFree

| LogDiskSpace

| “RAISERROR”

| ServerIdle

| TempDiskSpace

trigger-condition:

event_condition( condition-name )

{ =

| <

| >

| !=

| <=

| >= } value

schedule-spec:

[ schedule-name ]

{ START TIME start-time | BETWEEN start-time AND end-time }

[ EVERY period { HOURS | MINUTES | SECONDS } ]

[ ON { ( day-of-week, … ) | ( day-of-month, … ) } ]

[ START DATE start-date ]

Parameters

•

DELETE TYPE – removes an association of the event with an event type.

SQL Statements

14 SAP Sybase IQ

•

ADD | MODIFY | DELETE SCHEDULE – changes the definition of a schedule. Only

one schedule can be altered in any one ALTER EVENT statement.

•

WHERE – determines the condition under which an event is fired. The WHERE NULL

option deletes a condition.

Note: For other parameter descriptions, see the CREATE EVENT Statement.

Examples

•

Example 1 – lists event names by querying the system table SYSEVENT:

SELECT event_id, event_name FROM SYS.SYSEVENT

•

Example 2 – lists schedule names by querying the system table SYSSCHEDULE:

SELECT event_id, sched_name FROM SYS.SYSSCHEDULE

Usage

ALTER EVENT lets you alter an event definition created with CREATE EVENT. Possible

uses include:

• Change an event handler during development.

• Define and test an event handler without a trigger condition or schedule during a

development phase, and then add the conditions for execution using ALTER EVENT once

the event handler is completed.

• Disable an event handler temporarily by disabling the event.

When you alter an event using ALTER EVENT, specify the event name and, optionally, the

schedule name.

Each event has a unique event ID. Use the event_id columns of SYSEVENT and

SYSSCHEDULE to match the event to the associated schedule.

Side effects:

• Automatic commit

Permissions

Requires one of:

• MANAGE ANY EVENT system privilege.

• ALTER ANY OBJECT system privilege.

See also

•

BEGIN … END Statement

on page 84

•

CREATE EVENT Statement

on page 123

SQL Statements

Reference: Statements and Options 15

ALTER FUNCTION Statement

Modifies an existing function. Include the entire modified function in the ALTER FUNCTION

statement.

Syntax

Syntax 1

ALTER FUNCTION [ owner.]function-name function-definition

function-definition:

CREATE FUNCTION syntax

Syntax 2

ALTER FUNCTION [ owner.]function-name

SET HIDDEN

Syntax 3

ALTER FUNCTION [ owner.]function-name

RECOMPILE

Parameters

•

SET HIDDEN – to scramble the definition of the associated function and cause it to

become unreadable. The function can be unloaded and reloaded into other databases.

Warning! The SET HIDDEN clause setting is irreversible. If you need the original source

again, you must maintain it outside the database.

•

RECOMPILE – to recompile a user-defined function. When you recompile a function,

the definition stored in the catalog is re-parsed and the syntax is verified. The preserved

source for a function is not changed by recompiling. When you recompile a function, the

definitions scrambled by the SET HIDDEN clause remain scrambled and unreadable.

Usage

•

Syntax 1 – identical in syntax to the CREATE FUNCTION statement except for the first

word. Either version of the CREATE FUNCTION statement can be altered.

Existing permissions on the function are maintained and do not have to be reassigned. If a

DROP FUNCTION and CREATE FUNCTION were carried out, execute permissions must be

reassigned.

Side effects:

• Automatic commit

SQL Statements

16 SAP Sybase IQ

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

Permissions

Alter a Watcom SQL or Transact-SQL function – Requires one of:

• ALTER ANY PROCEDURE system privilege.

• ALTER ANY OBJECT system privilege.

• You own the function.

Alter an external C/C++ Scalar or Aggregate, or external Java function – Requires one of:

• Requires CREATE EXTERNAL REFERENCE system privilege.

• Also requires one of:

• ALTER ANY PROCEDURE system privilege.

• ALTER ANY OBJECT system privilege.

• You own the function.

See also

•

ALTER PROCEDURE Statement

on page 36

•

CREATE FUNCTION Statement

on page 133

•

DROP Statement

on page 255

ALTER INDEX Statement

Renames indexes in base or global temporary tables, foreign key role names of indexes and

foreign keys explicitly created by a user, or changes the clustered nature of an index on a

catalog store table. You cannot rename indexes created to enforce key constraints.

Syntax

ALTER { INDEX index-name

| [ INDEX ] FOREIGN KEY role-name

| [ INDEX ] PRIMARY KEY

| ON [owner.]table-name { rename-clause | move-clause | cluster-

clause}

rename-clause:

RENAME TO | AS new-name

move-clause:

MOVE TO dbspace-name

cluster-clause:

CLUSTERED | NONCLUSTERED

SQL Statements

Reference: Statements and Options 17

Parameters

•

ON – specifies the name of the table that contains the index or foreign key to rename.

•

RENAME – specifies the new name of the index or foreign key role.

•

MOVE – moves the specified index, unique constraint, foreign key, or primary key to the

specified dbspace. For unique constraint or foreign key, you must specify its unique index

name.

•

cluster-clause – specifies whether the index should be changed to CLUSTERED or

NONCLUSTERED. Applies to catalog store tables only and only one index on a table can

be clustered.

Examples

•

Example 1 – move the primary key, HG for c5, from dbspace Dsp4 to Dsp8:

CREATE TABLE foo (

c1 INT IN Dsp1,

c2 VARCHAR(20),

c3 CLOB IN Dsp2,

c4 DATE,

c5 BIGINT,

PRIMARY KEY (c5) IN Dsp4) IN Dsp3);

CREATE DATE INDEX c4_date ON foo(c4) IN Dsp5;

ALTER INDEX PRIMARY KEY ON foo MOVE TO Dsp8;

•

Example 2 – move DATE index from Dsp5 to Dsp9:

ALTER INDEX c4_date ON foo MOVE TO Dsp9

•

Example 3 – rename an index COL1_HG_OLD in the table jal.mytable to

COL1_HG_NEW:

ALTER INDEX COL1_HG_OLD ON jal.mytable

RENAME AS COL1_HG_NEW

•

Example 4 – rename a foreign key role name ky_dept_id in table dba.Employees

to emp_dept_id:

ALTER INDEX FOREIGN KEY ky_dept_id

ON dba.Employees

RENAME TO emp_dept_id

Usage

You must have CREATE privilege on the new dbspace and be the table owner or have the

MANAGE ANY DBSPACE system privilege.

Note: Attempts to alter an index in a local temporary table return the error index not

found. Attempts to alter a nonuser-created index, such as a default index (FP), return the

SQL Statements

18 SAP Sybase IQ

error Cannot alter index. Only indexes in base tables or global

temporary tables with an owner type of USER can be altered.

Side effects:

• Automatic commit. Clears the Results tab in the Results pane in Interactive SQL. Closes

all cursors for the current connection.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

move-clause

for materialized view requires one of:

• MANAGE ANY DBSPACE system privilege.

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• You own the materialized view along with one of:

• CREATE ANY OBJECT system privilege.

• CREATE privilege on the target dbspace.

move-clause for all other indexes requires one of:

• MANAGE ANY DBSPACE system privilege.

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• You own the underlying table or have REFERENCE privilege on the table along with one

of:

• CREATE ANY OBJECT system privilege.

• CREATE privilege on the target dbspace.

cluster-clause for materialized view requires one of:

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• You own the materialized view.

cluster-clause for all other indexes, requires one of:

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• REFERENCE privilege on the table.

• You own the table.

All other clauses require one of:

SQL Statements

Reference: Statements and Options 19

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• REFERENCE privilege on the table.

• You own the underlying table.

See also

•

ALTER TABLE Statement

on page 52

•

CREATE INDEX Statement

on page 142

•

CREATE TABLE Statement

on page 205

ALTER LDAP SERVER Statement

Any changes to an LDAP server configuration object are applied on subsequent connections.

Any connection already started when the change is applied does not immediately reflect the

change.

Syntax

ALTER LDAP SERVER ldapua-server-name

{ ldapua-server-attribs

| [ WITH ( SUSPEND | ACTIVATE | REFRESH ) ] }

ldapua-server-attribs:

SEARCH DN

URL { ‘URL_string’ | NULL }

| ACCESS ACCOUNT { ‘DN_string’ | NULL }

| IDENTIFIED BY ( ‘password’ | NULL }

| IDENTIFIED BY ENCRYPTED { encrypted-password | NULL }

| AUTHENTICATION URL { ‘URL_string’ | NULL }

| CONNECTION TIMEOUT timeout_value

| CONNECTION RETRIES retry_value

| TLS { ON | OFF }

Parameters

•

URL – identifies the host (by name or by IP address), port number, and the search to be

performed for the DN lookup for a given user ID. This value is validated for correct LDAP

URL syntax before it is stored in the ISYSLDAPSERVER system table. The maximum

size for this string is 1024 bytes.

•

ACCESS ACCOUNT – user created in the LDAP server for use by SAP Sybase IQ, not a

user within SAP Sybase IQ. The distinguished name (DN) for this user is used to connect

to the LDAP server. This user has permissions within the LDAP server to search for DNs

by user ID in the locations specified by the SEARCH DN URL. The maximum size for this

string is 1024 bytes.

SQL Statements

20 SAP Sybase IQ

•

IDENTIFIED BY – provides the password associated with the ACCESS ACCOUNT

user. The password is stored using symmetric encryption on disk. Use the value NULL to

clear the password and set it to none. The maximum size of a clear text password is 255

bytes.

•

IDENTIFIED BY ENCRYPTED – configures the password associated with the

ACCESS ACCOUNT distinguished name in an encrypted format. The binary value is the

encrypted password and is stored on disk as is. Use the value NULL to clear the password

and set it to none. The maximum size of the binary is 289 bytes. The encrypted key should

be a valid varbinary value. Do not enclose the encrypted key in quotation marks.

•

AUTHENTICATION URL – identifies the host (by name or IP address) and the port

number of the LDAP server to use for authentication of the user. This is the value defined

for URL_string and is validated for correct LDAP URL syntax before it is stored in

ISYSLDAPSERVER system table. The DN of the user obtained from a prior DN search

and the user password bind a new connection to the authentication URL. A successful

connection to the LDAP server is considered proof of the identity of the connecting user.

The maximum size for this string is 1024 bytes.

•

CONNECTION TIMEOUT – specifies the connection timeout from SAP Sybase IQ to

the LDAP server for both DN searches and authentication. This value is in milliseconds,

with a default value of 10 seconds.

•

CONNECTION RETRIES – specifies the number of retries on connections from SAP

Sybase IQ to the LDAP server for both DN searches and authentication. The valid range of

values is 1– 60, with a default value of 3.

•

TLS – defines whether the TLS or Secure LDAP protocol is used for connections to the

LDAP server for both DN searches and authentication. When set to ON, the TLS protocol

is used and the URL would being with "ldap://" When set to OFF (or not specified), Secure

LDAP protocol is used and the URL begins with “ldaps://”. When using the TLS protocol,

specify the database security option TRUSTED_CERTIFICATES_FILE with a file name

containing the certificate of the Certificate Authority (CA) that signed the certificate used

by the LDAP server.

•

WITH ACTIVATE – activates the LDAP server configuration object for immediate use

upon creation. This permits the definition and activation of LDAP User Authentication in

one statement. The LDAP server configuration object state changes to READY when

WITH ACTIVATE is used.

Examples

•

Example 1 – suspends the LDAP server configuration object named apps_primary:

ALTER LDAP SERVER apps_primary SUSPEND

•

Example 2 – changes the LDAP server configuration object named apps_primary to

use a different URL for authentication on host fairfax, sets the port number to 1066,

SQL Statements

Reference: Statements and Options 21

sets the number of connection retries to 10, and finally activates the LDAP server

configuration object:

ALTER LDAP SERVER apps_primary

AUTHENTICATION URL 'ldap://my_LDAPserver:1066/'

CONNECTION RETRIES 10

WITH ACTIVATE

Usage

In addition to resetting LDAP server configuration object values for attributes, the ALTER

LDAP SERVER statement allows an administrator to make manual adjustments to a server's

state and behavior by putting the LDAP server configuration object in maintenance mode and

returning it to service from maintenance mode.

Standards

ANSI SQL – Compliance level: Transact-SQL extension.

Permissions

Requires the MANAGE ANY LDAP SERVER system privilege.

ALTER LOGICAL SERVER Statement

Modifies configuration for the existing user-defined logical server in the database. This

statement enforces consistent shared system temporary store settings across physical nodes

shared by logical servers.

Syntax

ALTER LOGICAL SERVER logical-server-name

{ alter-ls-clause } [ WITH STOP SERVER ]

alter-ls-clause:

{ADD MEMBERSHIP '(' { ls-member, ... } ')'

| DROP MEMBERSHIP '(' { ls-member, ... } ')'

| POLICY policy-name }

ls-member:

FOR LOGICAL COORDINATOR | mpx-server-name

Parameters

•

logical-server-name – refers to an existing user-defined logical server name.

•

WITH STOP SERVER – automatically shuts down all servers in the logical server when

the TEMP_DATA_IN_SHARED_TEMP database option is changed directly or indirectly.

SQL Statements

22 SAP Sybase IQ

Applies to

Multiplex only.

Examples

•

Example 1 – alters a user-defined logical server by adding multiplex nodes n1 and n2 to

logical server ls1:

ALTER LOGICAL SERVER ls1 ADD MEMBERSHIP (n1, n2)

•

Example 2 – adds logical membership of COORDINATOR and drop a named

membership of the current coordinator node n1 from logical server ls1:

ALTER LOGICAL SERVER ls1 ADD MEMBERSHIP (FOR LOGICAL COORDINATOR)

ALTER LOGICAL SERVER ls1 DROP MEMBERSHIP (n1)

•

Example 3 – changes the logical server policy for logical server ls2 to policy lsp1.

ALTER LOGICAL SERVER ls2 POLICY lsp1

Usage

The SYS.ISYSIQLSMEMBER system table stores definitions for the logical server

memberships.

A member node that is added to or dropped from a logical server starts or stops accepting

logical server connections only after the TLV log corresponding to ALTER LOGICAL SERVER

is played on that node. Existing connections of a logical server continue to run on a node when

that node is dropped from the logical server, however, distributed processing is stopped for

these connections.

An error is returned if:

• Any ls-member specified with the ADD MEMBERSHIP clause is already a member of the

logical server.

• Any ls-member specified with the DROP MEMBERSHIP clause is not an existing

member of the logical server.

• A logical server membership change causes a node to belong to multiple logical servers

assigned to a single login policy. Logical server membership in a login policy cannot

overlap.

Permissions

Requires the MANAGE MULTIPLEX system privilege.

SQL Statements

Reference: Statements and Options 23

ALTER LOGIN POLICY Statement

Changes existing login policies or configures logical server access.

Syntax

Syntax 1

ALTER LOGIN POLICY policy-name

{ { ADD | DROP | SET } LOGICAL SERVER ls-assignment-list

[ LOGICAL SERVER ls-override-list ])

ls-assignment-list:

{ { ls-name, ...}

| ALL

| COORDINATOR

| SERVER

| NONE

| DEFAULT }

ls-override-list:

{ ls-name, ...}

ls-name:

{ OPEN | user-defined-ls-name }

Syntax 2

ALTER LOGIN POLICY policy-name policy-option

policy-option:

policy-option-name = policy-option-value

policy-option-value:

{ UNLIMITED | DEFAULT | value }

policy-option-name:

AUTO_UNLOCK_TIME

| CHANGE_PASSWORD_DUAL_CONTROL

| DEFAULT_LOGICAL_SERVER

| LOCKED

| MAX_CONNECTIONS

| MAX_DAYS_SINCE_LOGIN

| MAX_FAILED_LOGIN_ATTEMPTS

| MAX_NON_DBA_CONNECTIONS

| PASSWORD_EXPIRY_ON_NEXT_LOGIN

| PASSWORD_GRACE_TIME

| PASSWORD_LIFE_TIME

| ROOT_AUTO_UNLOCK_TIME

| LDAP_PRIMARY_SERVER

| LDAP_SECONDARY_SERVER

| LDAP_AUTO_FAILBACK_PERIOD

SQL Statements

24 SAP Sybase IQ

| LDAP_FAILOVER_TO_STD

| LDAP_REFRESH_DN

Parameters

•

policy-name – the name of the login policy. Specify root to modify the root login policy.

•

policy-option-name – the name of the policy option. See

and

LDAP

for details on each option.

•

policy-option-value – the value assigned to the login policy option. If you specify

UNLIMITED, no limits are used. If you specify DEFAULT, the default limits are used. See

and

LDAP Login Policy Options

for supported values for each

option.

Applies to

Simplex and multiplex.

Examples

•

Example 1 – see

Logical Server Access Configuration

and

Multiplex Login Policy

Configuration

•

Example 2 – sets the password_life_time value to UNLIMITED and the

max_failed_login_attempts value to 5 in the Test1 login policy:

ALTER LOGIN POLICY Test1

password_life_time=UNLIMITED

max_failed_login_attempts=5;

Usage

If you do not specify a policy option, values for this login policy are taken from the root login

policy. New policies do not inherit the MAX_NON_DBA_CONNECTIONS and

ROOT_AUTO_UNLOCK_TIME policy options.

All new databases include a root login policy. You can modify the root login policy values, but

you cannot delete the policy.

Permissions

Requires the MANAGE ANY LOGIN POLICY system privilege.

SQL Statements

Reference: Statements and Options 25

Available options for root and user-defined login policies.

Option Description

AUTO_UN-

LOCK_TIME

The time period after which locked accounts not granted the MANAGE

ANY USER system privilege are automatically unlocked. This option can

be defined in any login policy, including the root login policy.

•

Values – 0 – UNLIMITED

•

Default – UNLIMITED

•

Applies to – All users not granted the MANAGE ANY USER system

privilege.

CHANGE_PASS-

WORD_DUAL_CON-

TROL

Requires input from two users, each granted the CHANGE PASSWORD

system privilege, to change the password of another user.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users.

DEFAULT_LOGI-

CAL_SERVER

If the connection string specifies no logical server, the user connects to the

DEFAULT_LOGICAL_SERVER option specified in the user's login pol-

icy.

•

Values –

• Name of an existing user-defined logical server

• ALL – allows access to all logical servers.

• AUTO – value of the default logical server in the root login policy.

• COORDINATOR – the current coordinator node.

• NONE – denies access to any multiplex server.

• OPEN – use alone or with the name of a user-defined logical server.

Allows access to all multiplex nodes that are not members of any

user-defined logical servers.

• SERVER – allows access to all of the multiplex nodes, subject to

the semantics of the SERVER logical server.

•

Default – AUTO

•

Applies to – All users. Requires MANAGE MULTIPLEX system

privilege.

SQL Statements

26 SAP Sybase IQ

Option Description

LOCKED If set ON, users cannot establish new connections. This setting temporarily

denies access to login policy users. Logical server overrides for this option

are not allowed.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users except those with the MANAGE ANY USER

system privilege.

MAX_CONNEC-

TIONS

The maximum number of concurrent connections allowed for a user. You

can specify a per-logical-server setting for this option.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the SERVER OPERATOR or

DROP CONNECTION system privilege.

MAX_DAYS_SINCE_

The maximum number of days that can elapse between two successive

logins by the same user.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the MANAGE ANY USER

system privilege.

MAX_FAILED_LOG-

IN_ATTEMPTS

The maximum number of failed attempts, since the last successful attempt,

to log into the user account before the account is locked.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users.

MAX_NON_DBA_C

ONNECTIONS

The maximum number of concurrent connections that a user without

SERVER OPERATOR or DROP CONNECTION system privileges can

make. This option is supported only in the root login policy.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the SERVER OPERATOR or

DROP CONNECTION privilege.

SQL Statements

Reference: Statements and Options 27

Option Description

PASSWORD_EXPI-

RY_ON_NEXT_LOG-

If set ON, the user's password expires at the next login.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users.

Note: This functionality is not currently implemented when logging in to

Sybase Control Center. A user will not be prompted to change their pass-

word. He or she will be prompted, however, when logging in to SAP Sybase

IQ outside of Sybase Control Center (for example, using Interactive SQL).

PASS-

WORD_GRACE_TIM

The number of days before password expiration during which login is

allowed but the default post_login procedure issues warnings.

•

Values – 0 – 2147483647

•

Default – 0

•

Applies to – All users.

PASS-

WORD_LIFE_TIME

The maximum number of days before a password must be changed.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users.

ROOT_AUTO_UN-

LOCK_TIME

The time period after which locked accounts granted the MANAGE ANY

USER system privilege are automatically unlocked. This option can be

defined only in the root login policy.

•

Values – 0 – UNLIMITED

•

Default – 15

•

Applies to – All users granted the MANAGE ANY USER system

privilege.

SQL Statements

28 SAP Sybase IQ

LDAP Login Policy Options

Available login policy options for LDAP user authentication

Option Description

LDAP_PRI-

MARY_SERV-

Specifies the name of the primary LDAP server.

•

Values – n/a

•

Default – None

•

Applies to – All users.

LDAP_SECON-

DARY_SERV-

Specifies the name of the secondary LDAP server.

•

Values – n/a

•

Default – None

•

Applies to – All users.

LDAP_AU-

TO_FAIL-

BACK_PERIOD

Specifies the time period, in minutes, after which automatic failback to the pri-

mary server is attempted.

•

Values – 0 - 2147483647

•

Default – 15 minutes

•

Applies to – All users.

LDAP_FAIL-

OVER_TO_STD

Permits authentication with standard authentication when authentication with the

LDAP server fails due to system resources, network outage, connection timeouts,

or similar system failures. However, it does not permit an actual authentication

failure returned from an LDAP server to fail over to standard authentication.

•

Values – ON, OFF

•

Default – ON

•

Applies to – All users.

SQL Statements

Reference: Statements and Options 29

Option Description

LDAP_RE-

FRESH_DN

Updates the ldap_refresh_dn value in the ISYSLOGINPOLICYOPTION

system table with the current time, stored in Coordinated Universal Time (UTC).

Each time a user authenticates with LDAP, if the value of ldap_refresh_dn in

ISYSLOGINPOLICYOPTION is more recent than the value of user_dn in

ISYSUSER, a search for a new user DN occurs. The user_dn value is then

updated with the new user DN and the user_dn_changed_at value is again updated

to the current time.

•

Values – NOW

•

Initial value for ROOT policy – NULL

•

Initial value for user-defined login policy – Current time stored in UTC

•

Applies to – All users.

Multiplex Login Policy Configuration

Configure login policies for multiplex servers.

Example

This example overrides the login policy settings on a logical server, increasing the maximum

number of connections on logical server ls1:

ALTER LOGIN POLICY lp1 max_connections=20 LOGICAL SERVER ls1;

Usage

Applies only to multiplex.

Any login management commands you execute on any multiplex server automatically

propagate to all servers in the multiplex. For best performance, execute these commands, or

any DDL, on the coordinator.

An override at the logical server level override means that a particular login policy option has

different settings for different logical servers. SYS.ISYSIQLSLOGINPOLICYOPTION

stores login policy option values for logical-server override. For each logical-server override

of a login policy option, a corresponding row exists in

ISYSIQLSLOGINPOLICYOPTION.

Logical Server Access Configuration

Configure logical server access.

Example 1

Assume that the root login policy allows access to logical servers ls4 and ls5 and login

policy lp1 exists with no logical server assignment. The statement below effectively assigns

SQL Statements

30 SAP Sybase IQ

Assign logical server ls1 to login policy lp1:

ALTER LOGIN POLICY lp1 ADD LOGICAL SERVER ls1

Example 2

This statement allows access of logical servers ls2 and ls3 from login policy lp1:

ALTER LOGIN POLICY lp1 ADD LOGICAL SERVER ls2, ls3

Example 3

Modify login policy lp1 to allow access to ls3 and ls4only:

ALTER LOGIN POLICY lp1 ADD LOGICAL SERVER ls4

ALTER LOGIN POLICY lp1 DROP LOGICAL SERVER ls1, ls2

or:

ALTER LOGIN POLICY lp1 SET LOGICAL SERVER ls3, ls4

Example 4

Modify login policylp1 to deny access to any logical servers:

ALTER LOGIN POLICY lp1 SET LOGICAL SERVER NONE

Example 5

Drop current logical server assignments of login policylp1 and allow it to inherit the logical

server assignments of the root login policy:

ALTER LOGIN POLICY lp1 SET LOGICAL SERVER DEFAULT

Usage

ADD, DROP, or SET clauses let you configure the logical server assignments of a login

policy:

•

ADD – adds new logical server assignments to a login policy.

•

DROP – deletes existing logical server assignments from a login policy.

•

SET – replaces all logical server assignments for a login policy with a new set of logical

server.

Use only one ADD, DROP, or SET clause. Use SERVER, NONE, and DEFAULT clauses only

with the SET clause. Specify a particular logical server name only once per ls-assignment list

or ls-override list.

An error is returned if:

• Any logical server specified with the ADD clause is already assigned to the login policy.

• Any logical server specified with the DROP clause is currently not assigned to the login

policy.

• Logical server assignment change may cause a membership overlap among assigned

logical servers.

SQL Statements

Reference: Statements and Options 31

SYS.ISYSIQLOGINPOLICYLSINFO stores logical server assignment information. For

each logical-server override of a login policy option, a corresponding row exists in

ISYSIQLOGINPOLICYLSINFO.

ALTER LS POLICY Statement

Modifies some or all option values for the root logical server policy or a user-created logical

server policy. This statement enforces consistent shared system temporary store settings

across physical nodes shared by logical servers.

Syntax

ALTER LS POLICY ls-policy-name ls-option-value-list

[ WITH STOP SERVER ]

ls-option-value-list:

{ ls-option-name = ls-policy-option-value } ...

ls-option-name:

ALLOW_COORDINATOR_AS_MEMBER

| DQP_ENABLED

| LOGIN_REDIRECTION

| REDIRECTION_WAITERS_THRESHOLD

| TEMP_DATA_IN_SHARED_TEMP

Parameters

•

ls-policy-name – the name of the logical server policy. Specify root to modify the root

logical server policy.

•

ls-option-value-list – the name of the logical server policy option. See

LS Policy Options

for details on each option.

•

ls-policy-option-value – any unspecified option inherits its value from the root logical

server policy. See

LS Policy Options

for supported values for each option

•

WITH STOP SERVER – automatically shuts down all servers in the logical server when

the TEMP_DATA_IN_SHARED_TEMP option is changed directly or indirectly.

Applies to

Multiplex only.

Examples

•

Example 1 – alters the logical server policy:

ALTER LS POLICY root

ALLOW_COORDINATOR_AS_MEMBER=ON

SQL Statements

32 SAP Sybase IQ

•

Example 2 – alters the logical server policy and causes servers to shut down automatically

when the option value changes:

ALTER LS POLICY root

TEMP_DATA_IN_SHARED_TEMP=ON WITH STOP SERVER

Usage

If you want a smaller IQ_SYSTEM_TEMP dbspace, set

TEMP_DATA_IN_SHARED_TEMP to ON, which writes temporary data to

IQ_SHARED_TEMP instead of IQ_SYSTEM_TEMP. In a distributed query processing

environment, however, setting both DQP_ENABLED and

TEMP_DATA_IN_SHARED_TEMP to ON may saturate your SAN with additional data in

IQ_SHARED_TEMP, where additional I/O operations against IQ_SHARED_TEMP may

adversely affect DQP performance.

Permissions

Requires the MANAGE MULTIPLEX system privilege.

LS Policy Options

Available options for root and user-defined LS policies.

Option Description

ALLOW_COORDINA-

TOR_AS_MEMBER

Can only be set for the ROOT logical server policy. When ON

(the default), the coordinator can be a member of any user-de-

fined logical server. OFF prevents the coordinator from being

used as a member of any user-defined logical servers.

•

Values – ON, OFF

•

Default – ON

DQP_ENABLED When set to 0, query processing is not distributed. When set to 1

(the default), query processing is distributed as long as a writ-

able shared temporary file exists. When set to 2, query pro-

cessing is distributed over the network, and the shared tempo-

rary store is not used.

•

Values – 0, 1, 2

•

Default – 1

SQL Statements

Reference: Statements and Options 33

Option Description

LOGIN_REDIRECTION When ON, enables login redirection for logical servers gov-

erned by specified login policy. When OFF (the default), disa-

bles login redirection at the logical server level, allowing ex-

ternal connection management.

•

Values – ON, OFF

•

Default – OFF

REDIRECTION_WAIT-

ERS_THRESHOLD

Specifies how many connections can queue before SAP Sybase

IQ redirects a connection to this logical server to another server.

Can be any integer value; default is 5.

•

Values – Integer

•

Default – 5

TEMP_DA-

TA_IN_SHARED_TEMP

When ON, all temporary table data and eligible scratch data

writes to the shared temporary store, provided that the shared

temporary store has at least one read-write file added. You must

restart all multiplex nodes after setting this option or after add-

ing a read-write file to the shared temporary store. (If the shared

temporary store contains no read-write file, or if you do not

restart nodes, data is written to IQ_SYSTEM_TEMP in-

stead.) When OFF (the default), all temporary table data and

scratch data writes to the local temporary store.

•

Values – ON, OFF

•

Default – OFF

ALTER MULTIPLEX RENAME Statement

Renames the multiplex and stores the multiplex name in SYS.ISYSIQINFO system table.

Syntax

ALTER MULTIPLEX RENAME multiplex-name

Applies to

Multiplex only.

Usage

When a multiplex is created, it is named after the coordinator. This statement is automatically

committed.

SQL Statements

34 SAP Sybase IQ

Permissions

Requires the MANAGE MULTIPLEX system privilege.

ALTER MULTIPLEX SERVER Statement

Changes the name, catalog file path, role, or status of the given server.

Syntax

Syntax 1

ALTER MULTIPLEX SERVER server-name server-option

server-option:

{ RENAME new-server-name

| DATABASE 'dbfile'

| ROLE { WRITER | READER | COORDINATOR }

| STATUS { INCLUDED | EXCLUDED }

| ASSIGN AS FAILOVER SERVER

| host-port-list }

host-port-list:

{ HOST ' hostname ' PORT port number ...}

{ PRIVATE HOST ' hostname ' PORT port number ...}

Syntax 2

ALTER MULTIPLEX SERVER server-name PRIVATE NULL

Parameters

•

RENAME – changes the name of the given server. The server automatically shuts down

and the next restart requires the new name.

•

DATABASE – changes the catalog file path for the given server. The server automatically

shuts down and the next restart requires the new catalog path. The user must relocate the

catalog file.

•

ROLE – changes the role of the given server. Users cannot change the role of coordinator

or role to coordinator. If the role of the writer node changes to reader, the server shuts

down.

•

STATUS – changes the status of the given server. A failover node cannot be excluded

unless it is the last node to be excluded. The server automatically shuts down after

exclusion. After including a node, you synchronize and restart it.

•

ASSIGN – designates the given server as the new failover server. The node should not be

in the excluded state. The ASSIGN AS FAILOVER clause is a standalone clause that

cannot be used with any other ALTER MULTIPLEX SERVER clause.

The coordinator must be running, but you can run the ALTER MULTIPLEX SERVER

command from any server in the multiplex. (Run all DDL statements on the coordinator.)

SQL Statements

Reference: Statements and Options 35

In all cases except when altering role from reader to writer, the named server is

automatically shut down.

•

host-port-list – Shut down the target server before you exclude it. If you do not, an

excluded server automatically shuts down and requires ALTER MULTIPLEX SERVER

server-name

STATUS INCLUDED and a synchronize to rejoin the multiplex.

Applies to

Multiplex only.

Examples

•

Example 1 – excludes secondary server mpx_writer1:

ALTER MULTIPLEX SERVER mpx_writer1 STATUS EXCLUDED

Permissions

Requires the MANAGE MULTIPLEX system privilege.

ALTER PROCEDURE Statement

Replaces an existing procedure with a modified version. Include the entire modified

procedure in the ALTER PROCEDURE statement, and reassign user permissions on the

procedure.

Syntax

Syntax 1

ALTER PROCEDURE [ owner.]procedure-name procedure-definition

Syntax 2

ALTER PROCEDURE [ owner.]procedure-name

REPLICATE { ON | OFF }

Syntax 3

ALTER PROCEDURE [ owner.]procedure-name

SET HIDDEN

Syntax 4

ALTER PROCEDURE [ owner.]procedure-name

RECOMPILE

Syntax 5

ALTER PROCEDURE

[ owner.]procedure-name ( [ parameter, …] )

[ RESULT (result-column, ...)]

EXTERNAL NAME ‘external-call’ [ LANGUAGE JAVA [ environment-name ] }

SQL Statements

36 SAP Sybase IQ

environment-name:

DISALLOW | ALLOW SERVER SIDE REQUESTS

external-call:

[column-name:]function-name@library; ...

Parameters

•

procedure-definition – CREATE PROCEDURE syntax following the name.

•

REPLICATE – if a procedure needs to be relocated to other sites using SAP Sybase

Replication Server, use the REPLICATE ON clause.

•

SET HIDDEN – to obfuscate the definition of the associated procedure and cause it to

become unreadable. The procedure can be unloaded and reloaded into other databases.

Note: This setting is irreversible. It is recommended that you retain the original procedure

definition outside of the database.

•

RECOMPILE – recompiles a stored procedure. When you recompile a procedure, the

definition stored in the catalog is re-parsed and the syntax is verified.

The procedure definition is not changed by recompiling. You can recompile procedures

with definitions hidden with the SET HIDDEN clause, but their definitions remain hidden.

•

RESULT – for procedures that generate a result set but do not include a RESULT clause,

the database server attempts to determine the result set characteristics for the procedure

and stores the information in the catalog. This can be useful if a table referenced by the

procedure has been altered to add, remove, or rename columns since the procedure was

created.

•

environment-name – DISALLOW is the default. ALLOW indicates that server-side

connections are allowed.

Note:

• Do not specify ALLOW unless necessary. Use of teh ALLOW clause slows down

certain types of SAP Sybase IQ table joins.

• Do not use UDFs with both ALLOW SERVER SIDE REQUESTS and DISALLOW

SERVER SIDE REQUESTS clauses in the same query.

Usage

The ALTER PROCEDURE statement must include the entire new procedure. You can use

PROC as a synonym for PROCEDURE. Both Watcom and Transact-SQL dialect procedures

can be altered through the use of ALTER PROCEDURE. Existing permissions on the procedure

are not changed. If you execute DROP PROCEDURE followed by CREATE PROCEDURE,

execute permissions are reassigned.

SQL Statements

Reference: Statements and Options 37

You cannot combine Syntax 2 with Syntax 1.

When using the ALTER PROCEDURE statement for table UDFs, the same set of restrictions

apply as for the CREATE PROCEDURE

Statement (External Procedures)

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Alter a Watcom-SQL or Transcat-SQL procedure – Requires one of:

• ALTER ANY PROCEDURE system privilege.

• ALTER ANY OBJECT system privilege.

• You own the procedure.

Alter an external C/C++ or external environment procedure – Requires CREATE

EXTERNAL REFERENCE system privilege. Also requires one of:

• ALTER ANY PROCEDURE system privilege.

• ALTER ANY OBJECT system privilege.

• You own the procedure.

See also

•

CREATE PROCEDURE Statement

on page 165

ALTER ROLE Statement

Migrates a compatibility role to a user-defined system role, then automatically drops the

compatibility role.

Note: You cannot use the ALTER ROLE statement to migrate SYS_AUTH_SA_ROLE or

SYS_AUTH_SSO_ROLE. These roles are automatically migrated when

SYS_AUTH_DBA_ROLE is migrated.

Syntax

Syntax 1 – To migrate SYS_AUTH_DBA_ROLE

ALTER ROLE predefined_sys_role_name

MIGRATE TO new_role_name [, new_sa_role_name, new_sso_role_name]

Syntax 2 – To migrate all other compatibility roles

ALTER ROLE predefined_sys_role_name

MIGRATE TO new_role_name

SQL Statements

38 SAP Sybase IQ

Parameters

•

predefined_sys_role_name – the name of a compatibility role that still exists (has not

already been dropped) in the database.

•

new_role_name – the name of the new role cannot begin with the prefix SYS_ or end with

the suffix _ROLE.

•

new_sa_role_name – required only when migrating SYS_AUTH_DBA_ROLE. The new

role to which the underlying system privileges of SYS_AUTH_SA_ROLE are to be

migrated to cannot already exist in the database, and the new role name cannot begin with

the prefix SYS_ or end with the suffix _ROLE.

•

new_sso_role_name – required only when migrating SYS_AUTH_DBA_ROLE. The

new role to which the underlying system privileges of SYS_AUTH_SSO_ROLE are to be

migrated to cannot already exist in the database, and the new role name cannot begin with

the prefix SYS_ or end with the suffix _ROLE.

Examples

•

Example 1 – migrates SYS_AUTH_DBA_ROLE to the new roles Custom_DBA,

Custom_SA, and Custom_SSO respectively. It then automatically migrates all users,

underlying system privileges, and roles granted to SYS_AUTH_DBA_ROLE to the

applicable new roles. Finally, it drops SYS_AUTH_DBA_ROLE,

SYS_AUTH_SA_ROLE, and SYS_AUTH_SSO_ROLE.

ALTER ROLE SYS_AUTH_DBA_ROLE

MIGRATE TO Custom_DBA, Custom_SA, Custom_SSO

•

Example 2 – migrates SYS_AUTH_OPERATOR_ROLE role to the new role

Operator_role. It then automatically migrates all users, underlying system

privileges, and roles granted to SYS_AUTH_OPERATOR_ROLE to the new role and

drops SYS_AUTH_OPERATOR_ROLE.

ALTER ROLE SYS_AUTH_OPERATOR_ROLE

MIGRATE TO Operator_role

Usage

During the migration process:

• A new user-defined role is created.

• All of the system privileges currently granted to the migrating predefined role are

automatically granted to the new user-defined role.

• All users and roles currently granted to the migrating predefined role are automatically

granted to the new user-defined role.

• The compatibility role is dropped.

SQL Statements

Reference: Statements and Options 39

Since no role administrator was specified during the migration process, only global role

administrators can manage the new role. Use the CREATE ROLE statement to add role

administrators with appropriate administrative rights to the role.

Standards

ANSI SQL – Compliance level: Transact-SQL extension.

Permissions

Requires the MANAGE ROLES system privilege granted with administrative rights.

ALTER SEQUENCE statement

Alters a sequence. This statement applies to SAP Sybase IQ catalog store tables only.

Syntax

ALTER SEQUENCE [ owner.] sequence-name

[ RESTART WITH signed-integer ]

[ INCREMENT BY signed-integer ]

[ MINVALUE signed-integer | NO MINVALUE ]

[ MAXVALUE signed-integer | NO MAXVALUE ]

[ CACHE integer | NO CACHE ]

[ CYCLE | NO CYCLE ]

Parameters

RESTART WITH clause – Restarts the named sequence with the specified value.

INCREMENT BY clause – Defines the amount the next sequence value is incremented from

the last value assigned. The default is 1. Specify a negative value to generate a descending

sequence. An error is returned if the INCREMENT BY value is 0.

MINVALUE clause – Defines the smallest value generated by the sequence. The default is 1.

An error is returned if MINVALUE is greater than ( 2^63-1) or less than -(2^63-1). An error is

also returned if MINVALUE is greater than MAXVALUE.

MAXVALUE clause – Defines the largest value generated by the sequence. The default is

2^63-1. An error is returned if MAXVALUE is greater than 2^63-1 or less than -(2^63-1).

CACHE clause – Specifies the number of preallocated sequence values that are kept in

memory for faster access. When the cache is exhausted, the sequence cache is repopulated and

a corresponding entry is written to the transaction log. At checkpoint time, the current value of

the cache is forwarded to the ISYSSEQUENCE system table. The default is 100.

CYCLE clause – Specifies whether values should continue to be generated after the

maximum or minimum value is reached.

SQL Statements

40 SAP Sybase IQ

Remarks

If the named sequence cannot be located, an error message is returned.

Privileges

You must be the owner of the sequence, or have one of the following privileges:

ALTER ANY SEQUENCE system privilege

ALTER ANY OBJECT system privilege

Side effects

None

Standards and compatibility

•

SQL/2008 – The ALTER SEQUENCE statement is part of optional SQL language feature

T176 of the SQL/2008 standard. The CACHE clause is a vendor extension.

Example

The following example sets a new maximum value for a sequence named Test:

ALTER SEQUENCE Test

MAXVALUE 1500;

ALTER SERVER Statement

Modifies the attributes of a remote server. Changes made by ALTER SERVER do not take

effect until the next connection to the remote server.

Syntax

ALTER SERVER server-name

[ CLASS 'server-class' ]

[ USING 'connection-info' ]

[ CAPABILITY 'cap-name' { ON | OFF } ]

[ CONNECTION CLOSE [ CURRENT | ALL | connection-id ] ]

server-class:

{ ASAJDBC

| ASEJDBC

| SAODBC

| ASEODBC

| DB2ODBC

| MSSODBC

| ORAODBC

| ODBC }

connection-info:

{ machine-name:port-number [ /dbname ] | data-source-name }

SQL Statements

Reference: Statements and Options 41

Parameters

•

cap-name – the name of a server capability

•

CLASS – changes the server class. For more information on server classes.

•

USING – if a JDBC-based server class is used, the USING clause is

hostname:port-

number [/dbname]

where:

•

hostname – the machine on which the remote server runs.

•

portnumber – the TCP/IP port number on which the remote server listens. The default

port number for SAP Sybase IQ and SQL Anywhere is 2638.

•

dbname – for SQL Anywhere remote servers, if you do not specify a

dbname

, the

default database is used. For Adaptive Server Enterprise, the default is the master

database, and an alternative to using

dbname

is to another database by some other

means (for example, in the FORWARD TO statement).

If an ODBC-based server class is used, the USING clause is the

data-source-name

, which

is the ODBC Data Source Name.

•

CAPABILITY – turns a server capability ON or OFF. Server capabilities are stored in the

system table SYSCAPABILITY. The names of these capabilities are stored in the system

table SYSCAPABILITYNAME. The SYSCAPABILITY table contains no entries for a

remote server until the first connection is made to that server. At the first connection, SAP

Sybase IQ interrogates the server about its capabilities and then populates

SYSCAPABILITY. For subsequent connections, the server’s capabilities are obtained

from this table.

In general, you need not alter a server’s capabilities. It might be necessary to alter

capabilities of a generic server of class ODBC.

•

CONNECTION CLOSE – when a user creates a connection to a remote server, the

remote connection is not closed until the user disconnects from the local database. The

CONNECTION CLOSE clause allows you to explicitly close connections to a remote

server. You may find this useful when a remote connection becomes inactive or is no longer

needed.

These SQL statements are equivalent and close the current connection to the remote

server:

ALTER SERVER server-name CONNECTION CLOSE

ALTER SERVER server-name CONNECTION CLOSE CURRENT

You can close both ODBC and JDBC connections to a remote server using this syntax. You

do not need the SERVER OPERATOR system privilege to execute either of these

statements.

You can also disconnect a specific remote ODBC connection by specifying a connection

ID, or disconnect all remote ODBC connections by specifying the ALL keyword. If you

attempt to close a JDBC connection by specifying the connection ID or the ALL keyword,

SQL Statements

42 SAP Sybase IQ

an error occurs. When the connection identified by

connection-id

is not the current local

connection, the user must have the SERVER OPERATOR system privilege to be able to

close the connection.

Examples

•

Example 1 – changes the server class of the Adaptive Server Enterprise server named

ase_prod so its connection to SAP Sybase IQ is ODBC-based. The Data Source Name

is ase_prod.

ALTER SERVER ase_prod

CLASS 'ASEODBC'

USING 'ase_prod'

•

Example 2 – changes a capability of server infodc:

ALTER SERVER infodc

CAPABILITY 'insert select' OFF

•

Example 3 – closes all connections to the remote server named rem_test:

ALTER SERVER rem_test

CONNECTION CLOSE ALL

•

Example 4 – closes the connection to the remote server named rem_test that has the

connection ID 142536:

ALTER SERVER rem_test

CONNECTION CLOSE 142536

Usage

Side effects:

• Automatic commit

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Open Client/Open Server.

Permissions

Requires the SERVER OPERATOR system privilege.

See also

•

CREATE SERVER Statement

on page 192

•

DROP SERVER Statement

on page 269

SQL Statements

Reference: Statements and Options 43

ALTER SERVICE Statement

Causes the database server to act as a Web server

Syntax

ALTER SERVICE service-name

[ TYPE service-type-string ]

[ attributes ]

[ AS statement' ]

attributes:

[ AUTHORIZATION { ON | OFF } ]

[ SECURE { ON | OFF } ]

[ USER { user-name | NULL } ]

[ URL [ PATH/ ] { ON | OFF | ELEMENTS } ]

[ USING { SOAP-prefix | NULL } ]

service-type-string:

{ 'RAW '

| 'HTML '

| 'XML '

| 'SOAP '

| 'DISH ' }

Parameters

•

service-type-string – Web service names may be any sequence of alphanumeric

characters or “/”, “-”, “_”, “.”, “!”, “~”, “*”, “'”, “(“, or “”)”, except that the first character

cannot begin with a slash (/) and the name cannot contain two or more consecutive slash

characters.

•

AUTHORIZATION – determines whether users must specify a user name and password

when connecting to the service. The default value is ON.

• If authorization is OFF, the AS clause is required and a single user must be identified by

the USER clause. All requests are run using that user’s account and permissions.

• If authorization is ON, all users must provide a user name and password. Optionally,

you can limit the users that are permitted to use the service by providing a user or role

name using the USER clause. If the user name is NULL, all known users can access the

service.

Run production systems with authorization turned on. Grant permission to use the service

by adding users to a role.

•

SECURE – indicates whether unsecure connections are accepted. ON indicates that only

HTTPS connections are to be accepted. Service requests received on the HTTP port are

SQL Statements

44 SAP Sybase IQ

automatically redirected to the HTTPS port. If set to OFF, both HTTP and HTTPS

connections are accepted. The default value is OFF.

•

USER – if authorization is disabled, this parameter becomes mandatory and specifies the

user ID used to execute all service requests. If authorization is enabled (the default), this

optional clause identifies the user or role permitted access to the service. The default value

is NULL, which grants access to all users.

•

URL – determines whether URI paths are accepted and, if so, how they are processed.

OFF indicates that nothing must follow the service name in a URI request. ON indicates

that the remainder of the URI is interpreted as the value of a variable named

url

ELEMENTS indicates that the remainder of the URI path is to be split at the slash

characters into a list of up to 10 elements. The values are assigned to variables named url

plus a numeric suffix of between 1 and 10; for example, the first three variable names are

url1, url2, and url3. If fewer than 10 values are supplied, the remaining variables are set to

NULL. If the service name ends with the character /, then URL must be set to OFF. The

default value is OFF.

•

USING – applies only to DISH services. The parameter specifies a name prefix. Only

SOAP services whose names begin with this prefix are handled.

•

service-type-string – identifies the type of the service. The type must be one of the listed

service types. There is no default value.

• RAW – sends the result set to the client without any further formatting. You can produce

formatted documents by generating the required tags explicitly within your procedure.

• HTML – formats the result set of a statement or procedure into an HTML document that

contains a table.

• XML – assumes the result set is an XML format. If it is not already so, it is automatically

converted to XML RAW format.

• SOAP – formats the result set as a Simple Object Access Protocol (SOAP) response.

The request must be a valid SOAP request. For more information about the SOAP

standards, see

www.w3.org/TR/SOAP

• DISH – determine SOAP Handler, or DISH, service acts as a proxy for one or more

SOAP services. In use, it acts as a container that holds and provides access to a number

of SOAP services. A Web Services Description Language (WSDL) file is

automatically generated for each of the included SOAP services. The included SOAP

services are identified by a common prefix, which must be specified in the USING

clause.

•

statement – if the statement is NULL, the URI must specify the statement to be executed.

Otherwise, the specified SQL statement is the only one that can be executed through the

service. The statement is mandatory for SOAP services, and ignored for DISH services.

The default value is NULL.

All services that are run in production systems must define a statement. The statement can

be NULL only if authorization is enabled.

SQL Statements

Reference: Statements and Options 45

Examples

•

Example 1 – to set up a Web server quickly, starts a database server with the -xs switch,

then execute these statements:

CREATE SERVICE tables TYPE 'HTML'

ALTER SERVICE tables

AUTHORIZATION OFF

USER DBA

AS SELECT * FROM SYS.ISYSTABAfter executing these statements, use

any Web browser to open the URL http://localhost/tables.

Usage

You cannot rename Web services.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires the MANAGE ANY WEB SERVICE system privilege.

See also

•

CREATE SERVICE Statement

on page 194

•

DROP SERVICE Statement

on page 269

ALTER SPATIAL REFERENCE SYSTEM Statement

Changes the settings of an existing spatial reference system. See the Remarks section for

considerations before altering a spatial reference system

Syntax

ALTER SPATIAL REFERENCE SYSTEM

srs-name

[ srs-attribute [ srs-attribute ... ] ]

srs-attribute:

SRID srs-id

| DEFINITION { definition-string | NULL }

| ORGANIZATION { organization-name IDENTIFIED BY organization-srs-id

| NULL }

| TRANSFORM DEFINITION { transform-definition-string | NULL }

| LINEAR UNIT OF MEASURE linear-unit-name

| ANGULAR UNIT OF MEASURE { angular-unit-name | NULL }

| TYPE { ROUND EARTH | PLANAR }

| COORDINATE coordinate-name { UNBOUNDED | BETWEEN low-number

SQL Statements

46 SAP Sybase IQ

AND high-number }

| ELLIPSOID SEMI MAJOR AXIS semi-major-axis-length { SEMI MINOR AXIS

semi-minor-axis-length

| INVERSE FLATTENING inverse-flattening-ratio }

| SNAP TO GRID { grid-size | DEFAULT }

| TOLERANCE { tolerance-distance | DEFAULT }

| POLYGON FORMAT polygon-format

| STORAGE FORMAT storage-format

grid-size:

DOUBLE : usually between 0 and 1

axis-order:

{ 'x/y/z/m' | 'long/lat/z/m' | 'lat/long/z/m' }

polygon-format:

{ 'CounterClockWise' | 'Clockwise' | 'EvenOdd' }

storage-format:

{ 'Internal' | 'Original' | 'Mixed' }

Parameters

•

IDENTIFIED BY – the SRID number for the spatial reference system.

•

DEFINITION – set, or override, default coordinate system settings. If any attribute is set

in a clause other than the DEFINITION clause, it takes the value specified in the other

clause regardless of what is specified in the DEFINITION clause.

definition-string

is a string in the Spatial Reference System Well Known Text syntax as

defined by SQL/MM and OGC. For example, the following query returns the definition for

WGS 84.

SELECT ST_SpatialRefSys::ST_FormatWKT( definition )

FROM ST_SPATIAL_REFERENCE_SYSTEMS

WHERE srs_id=4326;

In Interactive SQL, if you double-click the value returned, an easier to read version of the

value appears.

When the DEFINITION clause is specified, definition-string is parsed and used to choose

default values for attributes. For example, definition-string may contain an AUTHORITY

element that defines the organization-name and

organization-srs-id

Parameter values in definition-string are overridden by values explicitly set using the SQL

statement clauses. For example, if the ORGANIZATION clause is specified, it overrides

the value for ORGANIZATION in definition-string.

•

ORGANIZATION – information about the organization that created the spatial reference

system that the spatial reference system is based on.

•

TRANSFORM DEFINITION – a description of the transform to use for the spatial

reference system. Currently, only the PROJ.4 transform is supported. The transform

definition is used by the ST_Transform method when transforming data between spatial

SQL Statements

Reference: Statements and Options 47

reference systems. Some transforms may still be possible even if there is no transform-

definition-string defined.

•

LINEAR UNIT OF MEASURE – the linear unit of measure for the spatial reference

system. The value you specify must match a linear unit of measure defined in the

ST_UNITS_OF_MEASURE system view.

If this clause is not specified, and is not defined in the DEFINITION clause, the default is

METRE. To add predefined units of measure to the database, use the sa_install_feature

system procedure.

To add custom units of measure to the database, use the CREATE SPATIAL UNIT OF

MEASURE statement.

Note: While both METRE and METER are accepted spellings, METRE is preferred as it

conforms to the SQL/MM standard.

•

ANGULAR UNIT OF MEASURE – the angular unit of measure for the spatial reference

system. The value you specify must match an angular unit of measure defined in the

ST_UNITS_OF_MEASURE system table.

If this clause is not specified, and is not defined in the DEFINITION clause, the default is

DEGREE for geographic spatial reference systems and NULL for non-geographic spatial

reference systems.

The angular unit of measure must be non-NULL for geographic spatial reference systems

and it must be NULL for non-geographic spatial reference systems.

The angular unit of measure must be non-NULL for geographic spatial reference systems

and it must be NULL for non-geographic spatial reference systems. To add predefined

units of measure to the database, use the sa_install_feature system procedure.

To add custom units of measure to the database, use the CREATE SPATIAL UNIT OF

MEASURE statement.

•

TYPE – control how the SRS interprets lines between points. For geographic spatial

reference systems, the TYPE clause can specify either ROUND EARTH (the default) or

PLANAR. The ROUND EARTH model interprets lines between points as great elliptic

arcs. Given two points on the surface of the Earth, a plane is selected that intersects the two

points and the center of the Earth. This plane intersects the Earth, and the line between the

two points is the shortest distance along this intersection.

For two points that lie directly opposite each other, there is not a single unique plane that

intersects the two points and the center of the Earth. Line segments connecting these anti-

podal points are not valid and give an error in the ROUND EARTH model.

The ROUND EARTH model treats the Earth as a spheroid and selects lines that follow the

curvature of the Earth. In some cases, it may be necessary to use a planar model where a

line between two points is interpreted as a straight line in the equirectangular projection

where x=long, y=lat.

SQL Statements

48 SAP Sybase IQ

In the following example, the blue line shows the line interpretation used in the ROUND

EARTH model and the red line shows the corresponding PLANAR model.

The PLANAR model may be used to match the interpretation used by other products. The

PLANAR model may also be useful because there are some limitations for methods that

are not supported in the ROUND EARTH model (such as ST_Area, ST_ConvexHull) and

some are partially supported (ST_Distance only supported between point geometries).

Geometries based on circularstrings are not supported in ROUND EARTH spatial

reference systems.

For non-geographic SRSs, the type must be PLANAR (and that is the default if the TYPE

clause is not specified and either the DEFINITION clause is not specified or it uses a non-

geographic definition).

•

COORDINATE – the bounds on the spatial reference system's dimensions. coordinate-

name is the name of the coordinate system used by the spatial reference system. For non-

geographic coordinate systems, coordinate-name can be x, y, or m. For geographic

coordinate systems, coordinate-name can be LATITUDE, LONGITUDE, z, or m.

Specify UNBOUNDED to place no bounds on the dimensions. Use the BETWEEN clause

to set low and high bounds.

The X and Y coordinates must have associated bounds. For geographic spatial reference

systems, the longitude coordinate is bounded between -180 and 180 degrees and the

latitude coordinate is bounded between -90 and 90 degrees by default the unless

COORDINATE clause overrides these settings. For non-geographic spatial reference

systems, the CREATE statement must specify bounds for both X and Y coordinates.

LATITUDE and LONGITUDE are used for geographic coordinate systems. The bounds

for LATITUDE and LONGITUDE default to the entire Earth, if not specified.

•

ELLIPSOID – the values to use for representing the Earth as an ellipsoid for spatial

reference systems of type ROUND EARTH. If the DEFINITION clause is present, it can

SQL Statements

Reference: Statements and Options 49

specify ellipsoid definition. If the ELLIPSOID clause is specified, it overrides this default

ellipsoid.

The Earth is not a perfect sphere because the rotation of the Earth causes a flattening so that

the distance from the center of the Earth to the North or South pole is less than the distance

from the center to the equator. For this reason, the Earth is modeled as an ellipsoid with

different values for the semi-major axis (distance from center to equator) and semi-minor

axis (distance from center to the pole). It is most common to define an ellipsoid using the

semi-major axis and the inverse flattening, but it can instead be specified using the semi-

minor axis (for example, this approach must be used when a perfect sphere is used to

approximate the Earth). The semi-major and semi-minor axes are defined in the linear

units of the spatial reference system, and the inverse flattening (1/f) is a ratio:

1/f = (semi-major-axis) / (semi-major-axis - semi-minor-axis)

product-name uses the ellipsoid definition when computing distance in geographic spatial

reference systems.

•

SNAP TO GRID – flat-Earth (planar) spatial reference systems, use the SNAP TO GRID

clause to define the size of the grid SAP Sybase IQ uses when performing calculations. By

default, SAP Sybase IQ selects a grid size so that 12 significant digits can be stored at all

points in the space bounds for X and Y. For example, if a spatial reference system bounds X

between -180 and 180 and Y between -90 and 90, then a grid size of 0.000000001 (1E-9) is

selected.

•

TOLERANCE – flat-Earth (planar) spatial reference systems, use the TOLERANCE

clause to specify the precision to use when comparing points. If the distance between two

points is less than tolerance-distance, the two points are considered equal. Setting

tolerance-distance allows you to control the tolerance for imprecision in the input data or

limited internal precision. By default, tolerance-distance is set to be equal to grid-size.

When set to 0, two points must be exactly equal to be considered equal.

For round-Earth spatial reference systems, TOLERANCE must be set to 0.

•

POLYGON FORMAT – internally, SAP Sybase IQ interprets polygons by looking at the

orientation of the constituent rings. As one travels a ring in the order of the defined points,

the inside of the polygon is on the left side of the ring. The same rules are applied in

PLANAR and ROUND EARTH spatial reference systems.

The interpretation used by SAP Sybase IQ is a common but not universal interpretation.

Some products use the exact opposite orientation, and some products do not rely on ring

orientation to interpret polygons. The POLYGON FORMAT clause can be used to select a

polygon interpretation that matches the input data, as needed. The following values are

supported:

•

CounterClockwise – input follows SAP Sybase IQ's internal interpretation: the inside

of the polygon is on the left side while following ring orientation.

SQL Statements

50 SAP Sybase IQ

•

Clockwise – input follows the opposite of SAP Sybase IQ's approach: the inside of the

polygon is on the right side while following ring orientation.

•

EvenOdd – (default) The orientation of rings is ignored and the inside of the polygon

is instead determined by looking at the nesting of the rings, with the exterior ring being

the largest ring and interior rings being smaller rings inside this ring. A ray is traced

from a point within the rings and radiating outward crossing all rings. If the number the

ring being crossed is an even number, it is an outer ring. If it is odd, it is an inner ring.

•

STORAGE FORMAT – control what is stored when spatial data is loaded into the

database. Possible values are:

•

Internal – SAP Sybase IQ stores only the normalized representation. Specify this

when the original input characteristics do not need to be reproduced. This is the default

for planar spatial reference systems (TYPE PLANAR).

•

Original – SAP Sybase IQ stores only the original representation. The original input

characteristics can be reproduced, but all operations on the stored values must repeat

normalization steps, possibly slowing down operations on the data.

•

Mixed – SAP Sybase IQ stores the internal version and, if it is different from the

original version, SQL Anywhere stores the original version as well. By storing both

versions, the original representation characteristics can be reproduced and operations

on stored values do not need to repeat normalization steps. However, storage

requirements may increase significantly because potentially two representations are

being stored for each geometry. Mixed is the default format for round-Earth spatial

reference systems (TYPE ROUND EARTH).

Examples

•

Example – changes the polygon format of a fictitious spatial reference system named

mySpatialRef to EvenOdd:

ALTER SPATIAL REFERENCE SYSTEM mySpatialRef

POLYGON FORMAT 'EvenOdd';

Usage

You cannot alter a spatial reference system if there is existing data that references it. For

example, if you have a column declared as ST_Point(SRID=8743), you cannot alter the spatial

reference system with SRID 8743. This is because many spatial reference system attributes,

such as storage format, impact the storage format of the data. If you have data that references

the SRID, create a new spatial reference system and transform the data to the new SRID.

Standards

ANSI SQL – Compliance level: Transact-SQL extension.

Permissions

Requires one of:

SQL Statements

Reference: Statements and Options 51

• You are the owner of the spatial reference system.

• ALTER privilege on the spatial reference system

• MANAGE ANY SPATIAL OBJECT system privilege

• ALTER ANY OBJECT system privilege.

ALTER TABLE Statement

Modifies a table definition.

Syntax

Syntax 1

ALTER TABLE table_name ALTER OWNER TO new_owner

[ { PRESERVE | DROP } PERMISSIONS ]

[ { PRESERVE | DROP } FOREIGN KEYS ]

Syntax 2

ALTER TABLE [ owner.]table-name

|{ ENABLE | DISABLE } RLV STORE

{ alter-clause, ... }

alter-clause:

ADD create-clause

| ALTER column-name column-alteration

| ALTER [ CONSTRAINT constraint-name ] CHECK ( condition )

| DROP drop-object

| RENAME rename-object

| move-clause

| SPLIT PARTITION range-partition-name

INTO( range-partition-decl-1, range-partition-decl-2

| MERGE PARTITION partition-name-1 INTO partition-name-2

| UNPARTITION

| PARTITION BY

range-partitioning-scheme

create-clause:

column-name column-definition [ column-constraint ]

| table-constraint

| [ PARTITION BY ] range-partitioning-scheme

column definition:

column-name data-type [ NOT NULL | NULL ]

[ IN dbspace-name ]

[ DEFAULT default-value | IDENTITY ]

column-constraint:

[ CONSTRAINT constraint-name ]

{ UNIQUE

| PRIMARY KEY

| REFERENCES table-name [ (column-name ) ] [ actions ]

| CHECK ( condition )

SQL Statements

52 SAP Sybase IQ

| IQ UNIQUE ( integer )

}

table-constraint:

[ CONSTRAINT constraint-name ]

{ UNIQUE ( column-name [ , … ] )

| PRIMARY KEY ( column-name [ , … ] )

| foreign-key-constraint

| CHECK ( condition )

}

foreign-key-constraint:

FOREIGN KEY [ role-name ] [ ( column-name [ , … ] ) ]

... REFERENCES table-name [ ( column-name [ , … ] ) ]

... [ actions ]

actions:

[ ON { UPDATE | DELETE } { RESTRICT } ]

column-alteration:

{ column-data-type | alterable-column-attribute } [ alterable-column-attribute … ]

| ADD [ constraint-name ] CHECK ( condition )

| DROP { DEFAULT | CHECK | CONSTRAINT constraint-name }

alterable-column-attribute:

[ NOT ] NULL

| DEFAULT default-value

| [ CONSTRAINT constraint-name ] CHECK { NULL |( condition )

}

default-value:

CURRENT { DATABASE |DATE |REMOTE USER |TIME |TIMESTAMP | USER |

PUBLISHER )

| string

| global variable

| [ - ] number

| ( constant-expression )

| built-in-function ( constant-expression )

| AUTOINCREMENT

| NULL

| TIMESTAMP

| LAST USER

| USER

drop-object:

{ column-name

| CHECK constraint-name

| CONSTRAINT

| UNIQUE ( index-columns-list )

| PRIMARY KEY

| FOREIGN KEY fkey-name

| [ PARTITION ] range-partition-name

}

rename-object:

SQL Statements

Reference: Statements and Options 53

new-table-name

| column-name TO new-column-name

| CONSTRAINT constraint-name TO new-constraint-name

| [ PARTITION ] range-partition-name TO new-range-partition-name

move-clause:

{ ALTER column-name

MOVE

{ PARTITION ( range-partition-name TO new-dbspace-name)

| TO new-dbspace-name }

}

| MOVE PARTITION range-partition-name TO new-dbspace-name

| MOVE TO new-dbspace-name

| MOVE METADATA TO new-dbspace-name

}

range-partitioning-scheme:

RANGE( partition-key )

( range-partition-decl [,range-partition-decl ...] )

partition-key:

column-name

range-partition-decl:

range-partition-name VALUES <= ( {constant | MAX } ) [ IN dbspace-

name ]

Parameters

•

{ ENABLE | DISABLE } RLV STORE – registers this table with the RLV store for real-

time in-memory updates. Not supported for IQ temporary tables. This value overrides the

value of the database option BASE_TABLES_IN_RLV. Requires the CREATE TABLE

system privilege and CREATE permissions on the RLV store dbspace to set this value to

ENABLE.

•

ADD column-definition [ column-constraint ] – add a new column to the table.

The table must be empty to specify NOT NULL. The table might contain data when you

add an IDENTITY or DEFAULT AUTOINCREMENT column. If the column has a default

IDENTITY value, all rows of the new column are populated with sequential values. You

can also add FOREIGN constraint as a column constraint for a single column key. The

value of the IDENTITY/DEFAULT AUTOINCREMENT column uniquely identifies every

row in a table.

The IDENTITY/DEFAULT AUTOINCREMENT column stores sequential numbers that

are automatically generated during inserts and updates. DEFAULT AUTOINCREMENT

columns are also known as IDENTITY columns. When using IDENTITY/DEFAULT

AUTOINCREMENT, the column must be one of the integer data types, or an exact numeric

type, with scale 0. See

CREATE TABLE Statement

for more about column constraints and

IDENTITY/DEFAULT AUTOINCREMENT columns.

IQ UNIQUE constraint – Defines the expected cardinality of a column and determines

whether the column loads as Flat FP or NBit FP. An IQ UNIQUE(

) value explicitly set to

SQL Statements

54 SAP Sybase IQ

0 loads the column as Flat FP. Columns without an IQ UNIQUE constraint implicitly load

as NBit up to the limits defined by the FP_NBIT_AUTOSIZE_LIMIT,

FP_NBIT_LOOKUP_MB, and FP_NBIT_ROLLOVER_MAX_MB options.

Using IQ UNIQUE with an

value less than the FP_NBIT_AUTOSIZE_LIMIT is not

necessary. Auto-size functionality automatically sizes all low or medium cardinality

columns as NBit. Use IQ UNIQUE in cases where you want to load the column as Flat FP

or when you want to load a column as NBit when the number of distinct values exceeds the

FP_NBIT_AUTOSIZE_LIMIT.

Note:

• Consider memory usage when specifying high IQ UNIQUE values. If machine

resources are limited, avoid loads with FP_NBIT_ENFORCE_LIMITS='OFF'

(default).

Prior to SAP Sybase IQ 16.0, an IQ UNIQUE

value > 16777216 would rollover to

Flat FP. In 16.0, larger IQ UNIQUE values are supported for tokenization, but may

require significant memory resource requirements depending on cardinality and

column width.

• BIT, BLOB,and CLOB data types do not support NBit dictionary compression. If

FP_NBIT_IQ15_COMPATIBILITY=’OFF’, a non-zero IQ UNIQUE column

specification in a CREATE TABLE or ALTER TABLE statement that includes these

data types returns an error.

•

ALTER column-name column-alteration – change the column definition:

• SET DEFAULT

default-value

– Change the default value of an existing column in a

table. You can also use the MODIFY clause for this task, but ALTER is ISO/ANSI

SQL compliant, and MODIFY is not. Modifying a default value does not change any

existing values in the table.

• DROP DEFAULT – Remove the default value of an existing column in a table. You can

also use the MODIFY clause for this task, but ALTER is ISO/ANSI SQL compliant,

and MODIFY is not. Dropping a default does not change any existing values in the

table.

• ADD – Add a named constraint or a CHECK condition to the column. The new

constraint or condition applies only to operations on the table after its definition. The

existing values in the table are not validated to confirm that they satisfy the new

constraint or condition.

• CONSTRAINT

column-constraint-name

– The optional column constraint name lets

you modify or drop individual constraints at a later time, rather than having to modify

the entire column constraint.

• [ CONSTRAINT

constraint-name

] CHECK (

condition

) – Use this clause to add a

CHECK constraint on the column.

SQL Statements

Reference: Statements and Options 55

• SET COMPUTE (

expression

) – Change the expression associated with a computed

column. The values in the column are recalculated when the statement is executed, and

the statement fails if the new expression is invalid.

• DROP COMPUTE – Change a column from being a computed column to being a non-

computed column. This statement does not change any existing values in the table.

•

ADD table-constraint – add a constraint to the table.

You can also add a foreign key constraint as a table constraint for a single-column or

multicolumn key. If PRIMARY KEY is specified, the table must not already have a

primary key created by the CREATE TABLE statement or another ALTER TABLE

statement. See

CREATE TABLE Statement

for a full explanation of table constraints.

Note: You cannot MODIFY a table or column constraint. To change a constraint,

DELETE the old constraint and ADD the new constraint.

•

DROP

drop-object – drops a table object:

• DROP

column-name

– Drop the column from the table. If the column is contained in

any multicolumn index, uniqueness constraint, foreign key, or primary key, then the

index, constraint, or key must be deleted before the column can be deleted. This does

not delete CHECK constraints that refer to the column. An IDENTITY/DEFAULT

AUTOINCREMENT column can only be deleted if IDENTITY_INSERT is turned off

and the table is not a local temporary table.

• DROP CHECK – Drop all check constraints for the table. This includes both table check

constraints and column check constraints.

• DROP CONSTRAINT

constraint-name

– Drop the named constraint for the table or

specified column.

• DROP UNIQUE (

column-name, ...

) – Drop the unique constraints on the specified

column(s). Any foreign keys referencing the unique constraint (rather than the primary

key) are also deleted. Reports an error if there are associated foreign-key constraints.

Use ALTER TABLE to delete all foreign keys that reference the primary key before

you delete the primary key constraint.

• DROP PRIMARY KEY – Drop the primary key. All foreign keys referencing the primary

key for this table are also deleted. Reports an error if there are associated foreign key

constraints. If the primary key is unenforced, DELETE returns an error if associated

unenforced foreign key constraints exist.

• DROP FOREIGN KEY

role-name

– Drop the foreign key constraint for this table with

the given role name. Retains the implicitly created non-unique HG index for the

foreign key constraint. Users can explicitly remove the HG index with the DROP

INDEX statement.

• DROP [ PARTITION ] – Drop the specified partition. The rows in partition P1 are

deleted and the partition definition is dropped. You cannot drop the last partition

because dropping the last partition would transform a partitioned table to a non-

partitioned table. (To merge a partitioned table, use an UNPARTITION clause

instead.) For example:

SQL Statements

56 SAP Sybase IQ

CREATE TABLE foo (c1 INT, c2 INT)

PARTITION BY RANGE (c1)

(P1 VALUES <= (100) IN dbsp1,

P2 VALUES <= (200) IN dbsp2,

P3 VALUES <= (MAX) IN dbsp3

) IN dbsp4);

LOAD TABLE ….

ALTER TABLE DROP PARTITION P1;

•

RENAME rename-object – renames an object in the table:

• RENAME

new-table-name

– Change the name of the table to the

new-table-name

. Any

applications using the old table name must be modified. Also, any foreign keys that

were automatically assigned the same name as the old table name do not change

names.

• RENAME

column-name

new-column-name

– Change the name of the column to

new-column-name

. Any applications using the old column name must be modified.

• RENAME [ PARTITION ] – Rename an existing partition.

• RENAME

constraint-name

new-constraint-name

– Change the name of the

constraint to

new-constraint-name

. Any applications using the old constraint name

must be modified.

•

MOVE clause – moves a table object. A table object can only reside in one dbspace. Any

type of ALTER MOVE blocks any modification to the table for the entire duration of the

move.

• MOVE TO – Move all table objects including columns, indexes, unique constraints,

primary key, foreign keys, and metadata resided in the same dbspace as the table is

mapped to the new dbspace. The ALTER Column MOVE TO clause cannot be

requested on a partitioned table.

• MOVE TABLE METADATA – Move the metadata of the table to a new dbspace. For a

partitioned table, MOVE TABLE METADATA also moves metadata that is shared

among partitions.

• MOVE PARTITION – Move the specified partition to the new dbspace.

•

PARTITION BY RANGE – maps data to partitions based on a range of partition keys

established for each partition.

A non-partitioned table can be partitioned if all existing rows belong to the first partition.

You can specify a different dbspace for the first partition than the dbspace of the column or

table. But existing rows are not moved. Instead, the proper dbspace for the column/

partition is kept in SYS.ISYSIQPARTITIONCOLUMN for existing columns. Only the

default or max identity column(s) that are added later for the first partition are stored in the

specified dbspace for the first partition.

Note: ALTER TABLE does not support hash partitioning, hash-range partitioning, or sub-

partitioning.

SQL Statements

Reference: Statements and Options 57

•

MERGE PARTITION – merge

partition-name-1

into

partition-name-2

. Two partitions can

be merged if they are adjacent partitions and the data resides on the same dbspace. You can

only merge a partition with a lower partition value into the adjacent partition with a higher

partition value. Note that the server does not check CREATE permission on the dbspace

into which the partition is merged. For an example of how to create adjacent partitions, see

CREATE TABLE Statement examples.

•

RENAME PARTITION – rename an existing PARTITION.

•

UNPARTITION – remove partitions from a partitioned table. Each column is placed in a

single dbspace. Note that the server does not check CREATE permission on the dbspace to

which data of all partitions is moved. ALTER TABLE UNPARTITION blocks all database

activities.

•

ALTER OWNER – change the owner of a table. The ALTER OWNER clause may not be used

in conjunction with any other [alter-clause] clauses of the ALTER TABLE statement.

• [

PRESERVE

DROP ] PERMISSIONS

– If you do not want the new owner to have the

same privileges as the old owner, use the DROP permissions clause (default) to drop all

explicitly-granted privileges that allow a user access to the table. Implicitly-granted

privileges given to the owner of the table are given to the new owner and dropped from

the old owner.

• [ PRESERVE | DROP ] FOREIGN KEYS – If you want to prevent the new owner from

accessing data in referenced tables, use the DROP FOREIGN KEYS clause (default) to

drop all foreign keys within the table, as well as all foreign keys referring to the table.

Use of the PRESERVE FOREIGN KEYS clause with the DROP PERMISSIONS

clause fails unless all referencing tables are owned by the new owner.

The ALTER TABLE ALTER OWNER statement fails if:

• Another table with the same name as the original table exists and is owned by the new

user.

• The PRESERVE FOREIGN KEYS and PRESERVE PERMISSIONS clauses are both

specified and there is a foreign key owned by a user other than the new table owner

referencing the table that relies on implicitly-granted permissions (such as those given

to the owner of a table). To avoid this failure, explicitly grant SELECT permissions to

the referring table's original owner, or drop the foreign keys.

• The PRESERVE FOREIGN KEYS clause is specified, but the PRESERVE

PERMISSIONS clause is NOT, and there is a foreign key owned by a user other than

the new table owner referencing the table. To avoid this failure, drop the foreign keys.

• The PRESERVE FOREIGN KEYS clause is specified and the table contains a foreign

key that relies on implicitly-granted permissions (such as those given to the owner of a

table). To avoid this failure, explicitly GRANT SELECT permissions to the new owner

on the referenced table, or drop the foreign keys.

• The table contains a column with a default value that refers to a sequence, and the

USAGE permission of the sequence generator relies on implicitly-granted permissions

SQL Statements

58 SAP Sybase IQ

(such as those given to the owner of a sequence). To avoid this failure, explicitly grant

USAGE permission on the sequence generator to the new owner of the table.

• Enabled materialized views that depend on the original table exist.

Examples

•

Example 1 – adds a new column to the Employees table showing which office they work

in:

ALTER TABLE Employees

ADD office CHAR(20)

•

Example 2 – drops the office column from the Employees table:

ALTER TABLE Employees

DROP office

•

Example 3 – Adds a column to the Customers table assigning each customer a sales

contact:

ALTER TABLE Customers

ADD SalesContact INTEGER

REFERENCES Employees (EmployeeID)

•

Example 4 – adds a new column CustomerNum to the Customers table and assigns a

default value of 88:

ALTER TABLE Customers

ADD CustomerNum INTEGER DEFAULT 88

•

Example 5 – moves FP indexes for c2, c4, and c5, from dbspace Dsp3 to Dsp6. FP

index for c1 remains in Dsp1. FP index for c3 remains in Dsp2. The primary key for c5

remains in Dsp4. DATE index c4_date remains in Dsp5.

CREATE TABLE foo (

c1 INT IN Dsp1,

c2 VARCHAR(20),

c3 CLOB IN Dsp2,

c4 DATE,

c5 BIGINT,

PRIMARY KEY (c5) IN Dsp4) IN Dsp3);

CREATE DATE INDEX c4_date ON foo(c4) IN Dsp5;

ALTER TABLE foo

MOVE TO Dsp6;

•

Example 6 – moves only FP index c1 from dbspace Dsp1 to Dsp7:

ALTER TABLE foo ALTER c1 MOVE TO Dsp7

•

Example 7 – uses many ALTER TABLE clauses to move, split, rename, and merge

partitions.

Create a partitioned table:

CREATE TABLE bar (

c1 INT,

SQL Statements

Reference: Statements and Options 59

c2 DATE,

c3 VARCHAR(10))

PARTITION BY RANGE(c2)

(p1 VALUES <= ('2005-12-31') IN dbsp1,

p2 VALUES <= ('2006-12-31') IN dbsp2,

P3 VALUES <= ('2007-12-31') IN dbsp3,

P4 VALUES <= ('2008-12-31') IN dbsp4);

INSERT INTO bar VALUES(3, '2007-01-01', 'banana nut');

INSERT INTO BAR VALUES(4, '2007-09-09', 'grape jam');

INSERT INTO BAR VALUES(5, '2008-05-05', 'apple cake');

Move partition p2 to dbsp5:

ALTER TABLE bar MOVE PARTITION p2 TO DBSP5;

Split partition p4 into 2 partitions:

ALTER TABLE bar SPLIT PARTITION p4 INTO

(P41 VALUES <= ('2008-06-30') IN dbsp4,

P42 VALUES <= ('2008-12-31') IN dbsp4);

This

SPLIT PARTITION

reports an error, as it requires data movement. Not all existing rows

are in the same partition after split.

ALTER TABLE bar SPLIT PARTITION p3 INTO

(P31 VALUES <= ('2007-06-30') IN dbsp3,

P32 VALUES <= ('2007-12-31') IN dbsp3);

This error is reported:

No data move is allowed, cannot split partition p3.

This SPLIT PARTITION reports an error, because it changes the partition boundary value:

ALTER TABLE bar SPLIT PARTITION p2 INTO

(p21 VALUES <= ('2006-06-30') IN dbsp2,

P22 VALUES <= ('2006-12-01') IN dbsp2);

This error is reported:

Boundary value for the partition p2 cannot be changed.

Merge partition p3 into p2. An error is reported as a merge from a higher boundary value

partition into a lower boundary value partition is not allowed.

ALTER TABLE bar MERGE PARTITION p3 into p2;

This error is reported:

Partition 'p2' is not adjacent to or before partition 'p3'.

Merge partition p2 into p3:

ALTER TABLE bar MERGE PARTITION p2 INTO P3;

Rename partition p1 to p1_new:

ALTER TABLE bar RENAME PARTITION p1 TO p1_new;

SQL Statements

60 SAP Sybase IQ

Unpartition table bar:

ALTER TABLE bar UNPARTITION;

Partition table bar. This command reports an error, because all rows must be in the first

partition.

ALTER TABLE bar PARTITION BY RANGE(c2)

(p1 VALUES <= ('2005-12-31') IN dbsp1,

P2 VALUES <= ('2006-12-31') IN DBSP2,

P3 VALUES <= ('2007-12-31') IN dbsp3,

P4 VALUES <= ('2008-12-31') IN dbsp4);

This error is reported:

All rows must be in the first partition.

Partition table bar:

ALTER TABLE bar PARTITION BY RANGE(c2)

(p1 VALUES <= ('2008-12-31') IN dbsp1,

P2 VALUES <= ('2009-12-31') IN dbsp2,

P3 VALUES <= ('2010-12-31') IN dbsp3,

P4 VALUES <= ('2011-12-31') IN dbsp4);

•

Example 8 – changes a table tab1 so that it is no longer registered for in-memory real-

time updates in the RLV store.

ALTER TABLE tab1 DISABLE RLV STORE

Usage

The ALTER TABLE statement changes table attributes (column definitions and constraints)

in a table that was previously created. The syntax allows a list of alter clauses; however, only

one table constraint or column constraint can be added, modified, or deleted in each ALTER

TABLE statement. ALTER TABLE is prevented whenever the statement affects a table that is

currently being used by another connection. ALTER TABLE can be time consuming, and the

server does not process requests referencing the same table while the statement is being

processed.

Note: You cannot alter local temporary tables, but you can alter global temporary tables when

they are in use by only one connection.

SAP Sybase IQ enforces REFERENCES and CHECK constraints. Table and/or column check

constraints added in an ALTER TABLE statement are evaluated, only if they are defined on

one of the new columns added, as part of that alter table operation. For details about CHECK

constraints, see

CREATE TABLE Statement

If SELECT

is used in a view definition and you alter a table referenced by the SELECT

then you must run ALTER VIEW

RECOMPILE to ensure that the view definition

is correct and to prevent unexpected results when querying the view.

Side effects:

SQL Statements

Reference: Statements and Options 61

• Automatic commit. The ALTER and DROP options close all cursors for the current

connection. The Interactive SQL data window is also cleared.

• A checkpoint is carried out at the beginning of the ALTER TABLE operation.

• Once you alter a column or table, any stored procedures, views or other items that refer to

the altered column no longer work.

Standards

• SQL – Vendor extension to ISO/ANSI SQL grammar.

• Sybase – Some clauses are supported by Adaptive Server Enterprise.

Permissions

Syntax 1

Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privilege

• ALTER privilege on the table

• You own the table

Syntax 2

The system privileges required for syntax 1 varies depending upon the clause used.

SQL Statements

62 SAP Sybase IQ

Clause Privilege Required

Add Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER privilege on the underlying ta-

ble

• You own the underlying table

UNIQUE, PRIMARY KEY, FOREIGN

KEY, or IQ UNIQUE column constraint –

Requires above along with REFERENCE

privilege on the underlying table.

FOREIGN KEY table constraint requires

above along with one of:

• CREATE ANY INDEX system privi-

lege

• CREATE ANY OBJECT system priv-

ilege

• REFERENCE privilege on the base ta-

ble

PARTITION BY RANGE requires above

along with one of:

• CREATE ANY OBJECT system priv-

ilege

• CREATE permission on the dbspaces

where the partitions are being created

Alter Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER permission on the table

• You own the table.

To alter a primary key or unique constraint,

also requires REFERENCE permission on

the table.

SQL Statements

Reference: Statements and Options 63

Clause Privilege Required

Drop Drop a column with no constraints – Re-

quires one of:

• ALTER ANY OBJECT system privi-

lege

• ALTER ANY TABLE system privilege

• ALTER permission on the underlying

table

• You own the underlying table

Drop a column or table with a constraint

requires above along with REFERENCE

permission if using ALTER permission.

Drop a partition on table owned by self –

None required.

Drop a partition on table owned by other

users – Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER permission on the table

RENAME Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER permission on the table

• You own the table

SQL Statements

64 SAP Sybase IQ

Clause Privilege Required

Move Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• MANAGE ANY DBSPACE system

privilege

• ALTER privilege on the underlying ta-

ble

• You own the underlying table

Also requires one of the following:

• CREATE ANY OBJECT system priv-

ilege

• CREATE privilege on the dbspace to

which the partition is being moved

Split Partition Partition on table owned by self – None

required.

Partition on table owned by other users –

Requires one of:

• SELECT ANY TABLE system privi-

lege

• SELECT privilege on table

Also requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER privilege on the table

Merge Partition,

Unpartition

Table owned by self – None required.

Table owned by other users – Requires one

of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER privilege on the table

SQL Statements

Reference: Statements and Options 65

Clause Privilege Required

Partition By Requires one of:

• CREATE ANY OBJECT system priv-

ilege

• CREATE permission on the dbspaces

where the partitions are being created

Also requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

• ALTER permission on the table

• You own the table

Enable or disable

RLV store

Requires one of:

• ALTER ANY TABLE system privilege

• ALTER ANY OBJECT system privi-

lege

See also

•

CREATE TABLE Statement

on page 205

•

DROP Statement

on page 255

•

IDENTITY_INSERT Option

on page 551

•

FP_NBIT_AUTOSIZE_LIMIT Option

on page 536

•

FP_NBIT_ENFORCE_LIMITS Option

on page 538

•

FP_NBIT_LOOKUP_MB Option

on page 540

•

FP_NBIT_ROLLOVER_MAX_MB Option

on page 542

ALTER TEXT INDEX Statement

Renames, moves or alters the definition of a TEXT index.

Note: This statement requires the Unstructured Data Analytics (IQ_UDA) license.

Syntax

ALTER TEXT INDEX [ owner.]text-index-name

ON [ owner.]table-name

alter-clause

alter-clause:

rename-object | move-object

SQL Statements

66 SAP Sybase IQ

rename-object:

RENAME { AS | TO } new-name

move-object:

MOVE TO dbspace-name

Parameters

•

RENAME – rename the TEXT index.

•

MOVE – move the TEXT index to the specified dbspace.

Examples

•

Example – creates a TEXT index, MyTextIndex, defining it as IMMEDIATE

REFRESH, rename the TEXT index to Text_index_daily, and move the TEXT

index to a dbspace named tispace:

CREATE TEXT INDEX MyTextIndex ON Customers ( CompanyName )

IMMEDIATE REFRESH;

ALTER TEXT INDEX MyTextIndex ON Customers RENAME AS

Text_index_daily;

ALTER TEXT INDEX Text_Index_Daily ON Customers MOVE TO tispace;

Usage

Side Effects:

• Automatic commit.

Permissions

move-object clause – Requires one of:

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• REFERENCE permission on the underlying table.

• You own the underlying table

rename-object clause – Requires one of:

• ALTER ANY INDEX system privilege.

• ALTER ANY OBJECT system privilege.

• MANAGE ANY DBSPACE

• One of the following:

• You own the underlying table being indexed.

• REFERENCE privilege on the table along with one of the following:

• CREATE ANY OBJECT system privilege.

SQL Statements

Reference: Statements and Options 67

• CREATE privilege on the target dbspace.

ALTER TEXT CONFIGURATION Statement

Alters a text configuration object.

Note: This statement requires the Unstructured Data Analytics (IQ_UDA) license.

Syntax

ALTER TEXT CONFIGURATION [ owner.]config-name

STOPLIST stoplist

| DROP STOPLIST

| { MINIMUM | MAXIMUM } TERM LENGTH integer

| TERM BREAKER

{ GENERIC

[ EXTERNAL NAME library-and-entry-point-name-string ]

| NGRAM }

| PREFILTER EXTERNAL NAME library-and-entry-point-name-string

| DROP PREFILTER

Parameters

•

stoplist – a string-expression used to create or replace the list of terms to ignore when

building a TEXT index. Terms specified in this list are also ignored in a query. Separate

stoplist terms with spaces.

Stoplist terms cannot contain whitespace and should not contain non-alphanumeric

characters. Non-alphanumeric characters are interpreted as spaces and break the term into

multiple terms. For example, “and/or” is interpreted as the two terms “and” and “or”. The

maximum number of stoplist terms is 7999.

•

DROP STOPLIST – use to drop the stoplist for a text configuration object.

•

MINIMUM TERM LENGTH – specifies the minimum length, in characters, of a term to

include in the TEXT index. The value specified in the MINIMUM TERM LENGTH

clause is ignored when using NGRAM TEXT indexes.

Terms that are shorter than this setting are ignored when building or refreshing the TEXT

index. The value of this option must be greater than 0. If you set this option to be higher

than MAXIMUM TERM LENGTH, the value of MAXIMUM TERM LENGTH is

automatically adjusted to be the same as the new MINIMUM TERM LENGTH value.

•

MAXIMUM TERM LENGTH – with GENERIC TEXT indexes, specifies the

maximum length, in characters, of a term to include in the TEXT index. Terms that are

longer than this setting are ignored when building or refreshing the TEXT index.

The value of MAXIMUM TERM LENGTH must be less than or equal to 60. If you set this

option to be lower than MINIMUM TERM LENGTH, the value of MINIMUM TERM

SQL Statements

68 SAP Sybase IQ

LENGTH is automatically adjusted to be the same as the new MAXIMUM TERM

LENGTH value.

•

TERM BREAKER – specifies the name of the algorithm to use for separating column

values into terms. The choices for IN SYSTEM tables are GENERIC (the default) or

NGRAM. The GENERIC algorithm treats any string of one or more alphanumerics,

separated by non-alphanumerics, as a term.

The NGRAM algorithm breaks strings into n-grams. An n-gram is an n-character

substring of a larger string. The NGRAM term breaker is required for fuzzy (approximate)

matching, or for documents that do not use whitespace or non-alphanumeric characters to

separate terms. NGRAM is supported for IN SYSTEM tables.

NGRAM term breaker is built on TEXT indexes, so use text configuration object settings

to define whether to use an NGRAM or GENERIC TEXT index.

TERM BREAKER can include the specification for the external term breaker library using

EXTERNAL NAME and the library entry point.

•

library-and-entry-point-name-string –

[operating-system:]function-name@library

•

PREFILTER EXTERNAL NAME – specifies the entry_point and the library name of

the external pre-filter library provided by external vendors.

•

DROP PREFILTER – drops the external prefilter and sets NULL to the prefilter columns

in ISYSTEXTCONFIG table.

Examples

•

Example 1 – creates a text configuration object, maxTerm16, and then change the

maximum term length to 16:

CREATE TEXT CONFIGURATION maxTerm16 FROM default_char;

ALTER TEXT CONFIGURATION maxTerm16 MAXIMUM TERM LENGTH 16;

•

Example 2 – adds stoplist terms to the maxTerm16 configuration object:

ALTER TEXT CONFIGURATION maxTerm16

STOPLIST 'because about therefore only';

•

Example 3 – updates the text configuration object, my_text_config, to use the entry

point my_term_breaker in the external library mytermbreaker.dll for breaking

the text:

CREATE TEXT CONFIGURATION my_text_config FROM default_char;

ALTER TEXT CONFIGURATION my_text_config

TERM BREAKER GENERIC EXTERNAL NAME

'platform:my_term_breaker@mytermbreaker';

•

Example 4 – updates the text configuration object, my_text_config, to use the entry

point my_prefilter in the external library myprefilter.dll for prefiltering the

documents:

SQL Statements

Reference: Statements and Options 69

ALTER TEXT CONFIGURATION my_text_config

PREFILTER EXTERNAL NAME 'platform:my_prefilter@myprefilter';

Usage

TEXT indexes are dependent on a text configuration object. SAP Sybase IQ TEXT indexes

use immediate refresh, and cannot be truncated; you must drop the indexes before you can

alter the text configuration object. To view the settings for text configuration objects, query the

SYSTEXTCONFIG system view.

Side Effects:

• Automatic commit.

Permissions

TERM BREAKER or PREFILTER EXTERNAL NAME clause – Requires the CREATE ANY

EXTERNAL REFERENCE system privilege, along with one of:

• ALTER ANY TEXT CONFIGURATION system privilege.

• ALTER ANY OBJECT system privilege.

• You own the text configuration object.

All other clauses – Requires the ALTER ANY TEXT CONFIGURATION system privilege,

regardless of whether the user is the owner of the configuration object.

ALTER TRIGGER statement

Replaces a trigger definition with a modified version. You must include the entire new trigger

definition in the ALTER TRIGGER statement.

Syntax 1 - Change the definition of a trigger

ALTER TRIGGER trigger-name trigger-definition

trigger-definition : CREATE TRIGGER syntax

Syntax 2 - Obfuscate a trigger definition

ALTER TRIGGER trigger-name ON [owner.] table-name SET HIDDEN

Remarks

•

Syntax 1 – The ALTER TRIGGER statement is identical in syntax to the CREATE

TRIGGER statement except for the first word.

Either the Transact-SQL or Watcom SQL form of the CREATE TRIGGER syntax can be

used.

SQL Statements

70 SAP Sybase IQ

•

Syntax 2 – You can use SET HIDDEN to obfuscate the definition of the associated trigger

and cause it to become unreadable. The trigger can be unloaded and reloaded into other

databases.

Note: The SET HIDDEN operation is irreversible.

Privileges

You must be the owner of the underlying table, or have the one of the following privileges:

ALTER privilege on the underlying table with the CREATE ANY OBJECT system

privilege

ALTER ANY TRIGGER system privilege

ALTER ANY OBJECT system privilege

To alter a trigger on a view owned by someone else, you must have either the ALTER ANY

TRIGGER and ALTER ANY VIEW system privileges, or you must have the ALTER ANY

OBJECT system privilege.

Side effects

Automatic commit.

Standards and compatibility

•

SQL/2008 – Vendor extension.

ALTER USER Statement

Changes user settings.

Syntax

Syntax 1 – Change the definition of a database user

ALTER USER user-name

| [ IDENTIFIED BY password ]

| [ LOGIN POLICY policy-name ]

| [ FORCE PASSWORD CHANGE { ON | OFF } ]

Syntax 2 – Refresh the Distinguished Name (DN) for an LDAP user

ALTER USER user-name

REFRESH DN

Syntax 3 – Revert a user's login policy to the original values

ALTER USER user-name

RESET LOGIN POLICY

Syntax 4 – Change a user's password when CHANGE_PASSWORD_DUAL_CONTROL is

enabled in a user's login policy.

SQL Statements

Reference: Statements and Options 71

ALTER USER user-name

IDENTIFIED [ FIRST | LAST ] BY password_part

Parameters

•

user-name – name of the user.

•

IDENTIFIED BY – the password for the user. Clause is not supported (ERROR) when

CHANGE_PASSWORD_DUAL_CONTROL option is enabled in a user's login policy

•

IDENTIFIED[ FIRST | LAST ] BY – clause mandatory when

CHANGE_PASSWORD_DUAL_CONTROL option is enabled in a target user's login

policy. FIRST | LAST keyword specifies the part of the dual password part being defined.

•

policy-name – name of the login policy to assign the user. No change is made if you do not

specify a login policy. No change is made if the LOGIN POLICY clause is not specified.

•

FORCE PASSWORD CHANGE – controls whether the user must specify a new

password upon logging in. This setting overrides the

PASSWORD_EXPIRY_ON_NEXT_LOGIN option setting in the user's login policy.

Note: This functionality is not currently implemented when logging in to Sybase Control

Center. A user will not be prompted to change their password. He or she will be prompted,

however, when logging in to SAP Sybase IQ outside of Sybase Control Center (for

example, using Interactive SQL).

•

RESET LOGIN POLICY – reverts the settings of the user's login to the original values in

the login policy. This usually clears all locks that are implicitly set due to the user

exceeding the failed logins or exceeding the maximum number of days since the last login.

When you reset a login policy, a user can access an account that has been locked for

exceeding a login policy option limit such as MAX_FAILED_LOGIN_ATTEMPTS or

MAX_DAYS_SINCE_LOGIN.

•

REFRESH DN – clears the saved DN and timestamp for a user, which is used during

LDAP authentication.

Examples

•

Example 1 – alters a user named SQLTester. The password is set to welcome. The

SQLTester user is assigned to the Test1 login policy and the password does not expire

on the next login:

ALTER USER SQLTester

IDENTIFIED BY welcome

FORCE PASSWORD CHANGE OFF

•

Example 2 – clears the distinguished name (DN) and timestamp for a user named Mary

used for LDAP authentication:

SQL Statements

72 SAP Sybase IQ

ALTER USER Mary REFRESH DN

•

Example 3 – sets the password for user3 to PassPart1PassPart2. This assumes that user1

and user2 have the CHANGE PASSWORD system privilege and the

change_password_dual_control option is enabled (ON) in the login policy for user3:

User1 enters:

ALTER USER user3 IDENTIFIED FIRST BY PassPart1

User2 enters:

ALTER USER user3 IDENTIFIED LAST BY PassPart2

Once set, user3 logs on by entering the password PassPart1PassPart2.

Usage

User IDs and passwords cannot:

• Begin with white space, single quotes, or double quotes

• End with white space

• Contain semicolons

Passwords cannot exceed 255 characters.

If you set the PASSWORD_EXPIRY_ON_NEXT_LOGIN value to ON, the passwords of all

users assigned to this login policy expire immediately when he or she next logs in. You can use

the ALTER USER and LOGIN POLICY clauses to force users to change their passwords at the

next login.

If the CHANGE_PASSWORD_DUAL CONTROL login policy option is disable (OFF)

during the dual password change process:

• the target user will be unable to log in with the single password part already defined. The

ALTER USER command must be reissued using single password control syntax.

• If the option is disabled after the dual password change process is complete, but before the

target user logs in, there is no impact on the target user. The target user must log in using

both password parts.

If the target user is already logged in when the dual password change process occurs, the user

cannot change their password in the current session until both parts of the new password are

set. Once the dual password change process is complete, the target user can use GRANT

CONNECT, ALTER USER, sp_password, or sp_iqpassword to the password without first

logging out. The prompt to enter the current password, use the new dual control password, not

the password originally entered for the current session.

The GRANT CONNECT statement is not supported during for the dual password change

process to set either password part. However, once the dual password change process is

complete, the target user can use the GRANT CONNECT statement, ALTER USER,

sp_password, or sp_iqpassword to change their password without first logging out.

SQL Statements

Reference: Statements and Options 73

As soon as both parts of the password are successfully specified by users with the CHANGE

PASSWORD system privilege, the password for the target user is automatically expired. This

forces the target user to change the password the next time he or she logs in.

The encryption algorithm used for hashing the user passwords is FIPS-certified encryption

support:

• The DLL is called dbfips10.dll

• The HASH function accepts the algorithms: SHA1_FIPS SHA256_FIPS

• If the -fips server option is specified and an algorithm that is not FIPS-certified is given to

the HASH function, the database server uses SHA1_FIPS instead of SHA1, SHA256_FIPS

instead of SHA256, and returns an error if MD5 is used (MD5 is not a FIPS-certified

algorithm).

• If the -fips option is specified, the database server uses SHA256_FIPS for password

hashing.

Standards

• SQL – Vendor extension to ISO/ANSI SQL grammar.

• Sybase – Not supported by Adaptive Server Enterprise.

Permissions

• To change own password – None required.

• To change the password of any user – Requires the CHANGE PASSWORD system

privilege.

• To use the LOGIN POLICY, FORCE PASSWORD CHANGE, RESET LOGIN POLICY, or

REFRESH DN clauses requires the MANAGE ANY USER system privilege.

See also

•

COMMENT Statement

on page 96

•

CREATE LOGIN POLICY Statement

on page 155

•

CREATE USER Statement

on page 230

•

DROP LOGIN POLICY Statement

on page 263

•

DROP USER Statement

on page 275

•

ALTER LOGIN POLICY Statement

on page 24

•

GRANT ROLE Statement

on page 312

•

GRANT System Privilege Statement

on page 319

•

REVOKE System Privilege Statement

on page 408

•

REVOKE ROLE Statement

on page 404

SQL Statements

74 SAP Sybase IQ

ALTER VIEW Statement

Replaces a view definition with a modified version.

Syntax

Syntax 1 – Alter the structure of the view

ALTER VIEW

… [ owner.]view-name [ ( column-name [ , … ] ) ]

… AS select-statement

… [ WITH CHECK OPTION ]

Syntax 2 – Change attributes for the view

ALTER VIEW

… [ owner.]view-name

… { SET HIDDEN | RECOMPILE | DISABLE | ENABLE }

Parameters

•

AS – the SELECT statement on which the view is based must not contain an ORDER BY

clause, a subquery in the SELECT list, or a TOP or FIRST qualification. It may have a

GROUP BY clause and may be a UNION.

•

WITH CHECK OPTION – rejects any updates and inserts to the view that do not meet

the criteria of the views as defined by its SELECT statement. However, SAP Sybase IQ

currently ignores this option (it supports the syntax for compatibility reasons).

•

SET HIDDEN – obfuscate the definition of the view and cause the view to become hidden

from view, for example in Sybase Control Center. Explicit references to the view still

work.

Warning! The SET HIDDEN operation is irreversible.

When you use SET HIDDEN, you can unload and reload the view into other databases.

Debugging using the debugger does not show the view definition, nor is it available

through procedure profiling. If you need to change the definition of a hidden view, you

must drop the view and create it again using the CREATE VIEW statement.

•

RECOMPILE – recreate the column definitions for the view. Identical in functionality to

the ENABLE clause, except you can use it on a view that is not disabled.

•

DISABLE – disable the view from use by the database server.

When you use the DISABLE clause, the view is no longer available for use by the database

server to answer queries. Disabling a view is similar to dropping one, except that the view

definition remains in the database. Disabling a view also disables any dependent views.

SQL Statements

Reference: Statements and Options 75

Therefore, the DISABLE clause requires exclusive access, not only to the view being

disabled, but to any dependent views, which are also disabled.

•

ENABLE – enable a disabled view, which causes the database server to recreate the

column definitions for the view. Before you enable a view, you must enable any views on

which it depends.

Usage

When you alter a view, existing permissions on the view are maintained and do not require

reassignment. Instead of using the ALTER VIEW statement, you could also drop the view and

recreate it using DROP VIEW and CREATE VIEW, respectively. If you do this, view

permissions must be reassigned.

After completing the view alteration using Syntax 1, the database server recompiles the view.

Depending on the type of change you made, if there are dependent views, the database server

attempts to recompile them. If you made changes that impact a dependent view, that view may

become invalid, requiring you to alter the definition for the dependent view.

Warning! If the SELECT statement defining the view contains an asterisk (*), the number of

the columns in the view could change if columns were added or deleted from the underlying

tables. The names and data types of the view columns could also change.

Altering the structure of a view requires that you replace the entire view definition with a new

definition, much as you would when creating the view using the CREATE VIEW statement.

Side effects:

• Automatic commit

• All procedures and triggers are unloaded from memory, so that any procedure or trigger

that references the view reflects the new view definition. The unloading and loading of

procedures and triggers can have a performance impact if you regularly alter views.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

RECOMPILE or ENABLE clause – For view requires one of:

• ALTER ANY VIEW system privilege.

• ALTER ANY OBJECT system privilege.

• You own the view.

• Also require one of:

• SELECT ANY TABLE system privilege.

SQL Statements

76 SAP Sybase IQ

• SELECT privilege on the underlying tables of the view.

For materialized view requires one of:

• ALTER ANY MATERIALNESS VIEW system privilege.

• ALTER ANY OBJECT system privilege.

• You own the materialized view.

• Also require one of:

• SELECT ANY TABLE system privilege.

• SELECT privilege on the underlying tables of the materialized view.

DISABLE clause – For view requires one of:

• ALTER ANY VIEW system privilege.

• ALTER ANY OBJECT system privilege.

• You own the view.

For materialized view requires one of:

• ALTER ANY MATERIALIZED VIEW system privilege.

• ALTER ANY OBJECT system privilege.

• You own the materialized view.

All other clauses require one of:

• ALTER ANY OBJECT system privilege.

• You own the view.

See also

•

CREATE VIEW Statement

on page 234

•

DROP Statement

on page 255

•

Identifying and Fixing Invalid Dependent Views

on page 77

Identifying and Fixing Invalid Dependent Views

Check for, and correct, any dependent views that become invalid due to changes to their

underlying tables.

Under most circumstances the database server automatically recompiles views to keep them

valid if the underlying tables change. However, if your table alteration removes or materially

changes something referenced by the view definition, then the dependent view becomes

invalid. For example, if you remove a column referenced in the view definition, then the

dependent view is no longer valid. Correct the view definition and manually recompile the

view.

Run sa_dependent_views to get the list of dependent views.

SQL Statements

Reference: Statements and Options 77

Perform the DDL operation that alters the table. The server automatically disables

dependent views, and attempts to recompile them once the DDL is complete.

Check that all the views listed by sa_dependent_views are valid. For example, perform a

simple test such as SELECT * FROM myview.

If a view is invalid, it is likely you will need to alter the view definition to resolve the issue.

Examine the view definition against the DDL change that you made and make the

necessary changes. Run ALTER VIEW RECOMPILE to correct the view definition.

Test the corrected view to make sure it works. For example, perform a simple test such as

SELECT * FROM myview.

The sa_dependent_views system procedure returns the list of all dependent views for a given

table or view.

See also

•

ALTER VIEW Statement

on page 75

BACKUP Statement

Backs up an SAP Sybase IQ database on one or more archive devices.

Syntax

BACKUP DATABASE

[ backup-option… ]

TO archive_device [ archive-option... ]

… [ WITH COMMENT string ]

backup-option:

{ READWRITE FILES ONLY |

READONLY dbspace-or-file [, … ] }

CRC { ON | OFF }

ATTENDED { ON | OFF }

BLOCK FACTOR integer

{ FULL | INCREMENTAL | INCREMENTAL SINCE FULL }

VIRTUAL { DECOUPLED |

ENCAPSULATED ‘shell_command’ }

WITH COMMENT comment

dbspace-or-file:

{ DBSPACES identifier-list | FILES identifier-list }

identifier-list:

identifier [, … ]

archive-option:

SIZE integer STACKER integer

SQL Statements

78 SAP Sybase IQ

Parameters

•

TO – specify the name of the archive_device to be used for backup, delimited with single

quotation marks. The archive_device is a file name or tape drive device name for the

archive file. If you use multiple archive devices, specify them using separate TO clauses.

(A comma-separated list is not allowed.) Archive devices must be distinct. The number of

TO clauses determines the amount of parallelism SAP Sybase IQ attempts with regard to

output devices.

•

WITH COMMENT – specify an optional comment recorded in the archive file and in the

backup history file. Maximum length is 32KB. If you do not specify a value, a NULL

string is stored.

•

READWRITE FILES ONLY – restricts FULL, INCREMENTAL, and

INCREMENTAL SINCE FULL backups to only the set of read-write files in the database.

The read-write dbspaces/files must be SAP Sybase IQ dbspaces.

If READWRITE FILES ONLY clause is used with an INCREMENTAL or

INCREMENTAL SINCE FULL backup, the backup will not back up data on read-only

dbspaces or dbfiles that has changed since the depends-on backup. If READWRITE

FILES ONLY is not specified for an INCREMENTAL or INCREMENTAL SINCE FULL

backup, the backup backs up all database pages that have changed since the depends-on

backup, both on read-write and read-only dbspaces.

•

CRC – activates 32-bit cyclical redundancy checking on a per block basis (in addition to

whatever error detection is available in the hardware). When you specify this clause, the

numbers computed on backup are verified during any subsequent RESTORE operation,

affecting performance of both commands. The default is ON.

•

ATTENDED – applies only when backing up to a tape device. If ATTENDED ON clause

(the default) is used, a message is sent to the application that issued the BACKUP statement

if the tape drive requires intervention. This might happen, for example, when a new tape is

required. If you specify OFF, BACKUP does not prompt for new tapes. If additional tapes

are needed and OFF has been specified, SAP Sybase IQ gives an error and aborts the

BACKUP command. However, a short delay is included to account for the time an

automatic stacker drive requires to switch tapes.

•

BLOCK FACTOR integer – specify the number of blocks to write at one time. The value

must be greater than 0, or SAP Sybase IQ generates an error message. Its default is 25 for

UNIX systems and 15 for Windows systems (to accommodate the smaller fixed tape block

sizes). This clause effectively controls the amount of memory used for buffers. The actual

amount of memory is this value times the block size times the number of threads used to

extract data from the database. Set BLOCK FACTOR to at least 25.

•

FULL | INCREMENTAL | INCREMENTAL SINCE FULL –

•

FULL – specify a full backup; all blocks in use in the database are saved to the archive

devices. This is the default action.

SQL Statements

Reference: Statements and Options 79

•

INCREMENTAL – specify an incremental backup; all blocks changed since the last

backup of any kind are saved to the archive devices. The keyword INCREMENTAL is

not allowed with READONLY FILES.

•

INCREMENTAL SINCE FULL – specify an incremental backup; all blocks

changed since the last full backup are saved to the archive devices.

•

VIRTUAL DECOUPLED – specify a decoupled virtual backup. For the backup to be

complete, you must copy the SAP Sybase IQ dbspaces after the decoupled virtual backup

finishes, and then perform a nonvirtual incremental backup.

•

VIRTUAL ENCAPSULATED – specify an encapsulated virtual backup. The ‘shell-

command’ argument can be a string or variable containing a string that is executed as part

of the encapsulated virtual backup. The shell commands execute a system-level backup of

the IQ store as part of the backup operation. For security reasons, it is recommended that an

absolute path be specified in the 'shell-command,' and file protections on that directory be

in place to prevent execution of an unintended program.

•

SIZE clause – Specify maximum tape or file capacity per output device (some platforms

do not reliably detect end-of-tape markers). No volume used on the corresponding device

should be shorter than this value. This value applies to both tape and disk files but not

third-party devices. Units are kilobytes (KB), although in general, less than 1GB is

inappropriate. For example, for a 3.5GB tape, specify 3500000. Defaults are by platform

and medium. The final size of the backup file will not be exact, because backup writes in

units of large blocks of data.

Table 1. BACKUP default sizes

Platform Default SIZE for Tape Default SIZE for Disk

UNIX none 2GB

Windows 1.5GB

SIZE must be a multiple of 64. Other val-

ues are rounded down to a multiple of 64.

1.5GB

The SIZE parameter is per output device. SIZE does not limit the number of bytes per

device; SIZE limits the file size. Each output device can have a different SIZE parameter.

During backup, when the amount of information written to a given device reaches the

value specified by the SIZE parameter, BACKUP does one of the following:

• If the device is a file system device, BACKUP closes the current file and creates

another file of the same name, with the next ascending number appended to the file

name, for example, bkup1.dat1.1, bkup1.dat1.2, bkup1.dat1.3.

• If the device is a tape unit, BACKUP closes the current tape and you need to mount

another tape.

•

STACKER – specify that the device is automatically loaded, and specifies the number of

tapes with which it is loaded. This value is not the tape position in the stacker, which could

be zero. When ATTENDED is OFF and STACKER is ON, SAP Sybase IQwaits for a

predetermined amount of time to allow the next tape to be autoloaded. The number of tapes

SQL Statements

80 SAP Sybase IQ

supplied along with the SIZE clause are used to determine whether there is enough space to

store the backed-up data. Do not use this clause with third-party media management

devices.

Examples

•

Example 1 – this UNIX example backs up the iqdemo database onto tape devices /

dev/rmt/0 and /dev/rmt/2 on a Sun Solaris platform. On Solaris, the letter n after

the device name specifies the “no rewind on close” feature. Always specify this feature

with BACKUP, using the naming convention appropriate for your UNIX platform

(Windows does not support this feature). This example backs up all changes to the

database since the last full backup:

BACKUP DATABASE

INCREMENTAL SINCE FULL

TO '/dev/rmt/0n' SIZE 10000000

TO '/dev/rmt/2n' SIZE 15000000

Note: Size units are kilobytes (KB), although in most cases, size of less than 1GB are

inappropriate. In this example, the specified sizes are 10GB and 15GB.

•

Example 2 – these BACKUP commands specify read-only files and dbspaces:

BACKUP DATABASE READONLY DBSPACES dsp1

TO '/dev/rmt/0'

BACKUP DATABASE READONLY FILES dsp1_f1, dsp1_f2

TO 'bkp.f1f2'

BACKUP DATABASE READONLY DBSPACES dsp2, dsp3

READONLY FILES dsp4_f1, dsp5_f2

TO 'bkp.RO'

Usage

The SAP Sybase IQ database might be open for use by many readers and writers when you

execute a BACKUP command. It acts as a read-only user and relies on the Table Level

Versioning feature of SAP Sybase IQ to achieve a consistent set of data.

BACKUP implicitly issues a CHECKPOINT prior to commencing, and then it backs up the

catalog tables that describe the database (and any other tables you have added to the catalog

store). During this first phase, SAP Sybase IQ does not allow any metadata changes to the

database (such as adding or dropping columns and tables). Correspondingly, a later RESTORE

of the backup restores only up to that initial CHECKPOINT.

The BACKUP command lets you specify full or incremental backups. You can choose two

kinds of incremental backups. INCREMENTAL backsup only those blocks that have changed

and committed since the last BACKUP of any type (incremental or full). INCREMENTAL

SINCE FULL backs up all of the blocks that have changed since the last full backup. The first

type of incremental backup can be smaller and faster to do for BACKUP commands, but slower

and more complicated for RESTORE commands. The opposite is true for the other type of

SQL Statements

Reference: Statements and Options 81

incremental backup. The reason is that the first type generally results in N sets of incremental

backup archives for each full backup archive. If a restore is required, a user with the SERVER

OPERATOR system privilege must RESTORE the full backup archive first, and then each

incremental archive in the proper order. (SAP Sybase IQ keeps track of which ones are

needed.) The second type requires the user with the SERVER OPERATOR system privilege to

restore only the full backup archive and the last incremental archive.

Incremental virtual backup is supported using the VIRTUAL DECOUPLED and VIRTUAL

ENCAPSULATED parameters of the BACKUP statement.

Although you can perform an OS-level copy of tablespaces to make a virtual backup of one or

more read-only dbspaces, use the virtual backup statement, because it records the backup in

the SAP Sybase IQ system tables.

BACKUP and RESTORE write your SAP Sybase IQ data in parallel to or from all of the archive

devices you specify. The catalog store is written serially to the first device. Faster backups and

restores result from greater parallelism.

SAP Sybase IQ supports a maximum of 36 hardware devices for backup. For faster backups,

specifying one or two devices per core will help to avoid hardware and IO contention. Set the

SIZE parameter on the BACKUP command to avoid creating multiple files per backup device

and consider the value used in the BLOCK FACTOR clause on the BACKUP command.

BACKUP overwrites existing archive files unless you move the old files or use a different

archive_device

name or path.

The backup API DLL implementation lets you specify arguments to pass to the DLL when

opening an archive device. For third-party implementations, the archive_device string has this

format:

'DLLidentifier::vendor_specific_information'

A specific example:

'spsc::workorder=12;volname=ASD002'

The

archive_device

string length can be up to 1023 bytes. The

DLLidentifier

portion must be 1

to 30 bytes in length and can contain only alphanumeric and underscore characters. The

vendor_specific_information

portion of the string is passed to the third-party implementation

without checking its contents. Do not specify the SIZE or STACKER clauses of the BACKUP

command when using third-party implementations, as that information should be encoded in

the

vendor_specific_information

portion of the string.

Note: Only certain third-party products are certified with SAP Sybase IQ using this syntax.

See the

Release Bulletin

for additional usage instructions or restrictions. Before using any

third-party product to back up your SAP Sybase IQ database in this way, make sure it is

certified. See the

Release Bulletin

, or see the SAP Sybase Certification Reports for the SAP

Sybase IQ product in

Technical Documents at http://www.sybase.com/support/techdocs/

SQL Statements

82 SAP Sybase IQ

For the Sybase implementation of the backup API, you need to specify only the tape device

name or file name. For disk devices, you should also specify the SIZE value, or SAP Sybase IQ

assumes that each created disk file is no larger than 2GB on UNIX, or 1.5GB on Windows.

An example of an archive device for the SAP Sybase API DLL that specifies a tape device for

certain UNIX systems is:

'/dev/rmt/0'

It is your responsibility to mount additional tapes if needed, or to ensure that the disk has

enough space to accommodate the backup.

When multiple devices are specified, BACKUP distributes the information across all devices.

Other issues for BACKUP include:

• BACKUP does not support raw devices as archival devices.

• Windows systems support only fixed-length I/O operations to tape devices (for more

information about this limitation, see your

Installation and Configuration Guide

Although Windows supports tape partitioning, SAP Sybase IQ does not use it, so do not

use another application to format tapes for BACKUP. Windows has a simpler naming

strategy for its tape devices, where the first tape device is

\\.\tape0

, the second is

\\.\tape1

and so on.

Warning! For backup (and for most other situations) SAP Sybase IQ treats the leading

backslash in a string as an escape character, when the backslash precedes an n, an x, or

another backslash. For this reason, when you specify backup tape devices, you must

double each backslash required by the Windows naming convention. For example,

indicate the first Windows tape device you are backing up to as '\\\\.\\tape0', the

second as '\\\\.\\tape1', and so on. If you omit the extra backslashes, or otherwise

misspell a tape device name, and write a name that is not a valid tape device on your

system, SAP Sybase IQ interprets this name as a disk file name.

• SAP Sybase IQ does not rewind tapes before using them. You must ensure the tapes used

for BACKUP or RESTORE are at the correct starting point before putting them in the tape

device. SAP Sybase IQ does rewind tapes after using them on rewinding devices.

• During BACKUP and RESTORE operations, if SAP Sybase IQ cannot open the archive

device (for example, when it needs the media loaded) and the ATTENDED clause is ON, it

waits for ten seconds and tries again. It continues these attempts indefinitely until either it

is successful or the operation is terminated with a Ctrl+C.

• If you enter Ctrl+C, BACKUP fails and returns the database to the state it was in before the

backup started.

• If disk striping is used, such as on a RAID device, the striped disks are treated as a single

device.

Side effects:

• Automatic commit

SQL Statements

Reference: Statements and Options 83

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires one of:

• BACK UP DATABASE system privilege.

• You own the database.

See also

•

RESTORE DATABASE Statement

on page 389

BEGIN … END Statement

Groups SQL statements together.

Syntax

[ statement-label : ]

… BEGIN [ [ NOT ] ATOMIC ]

… [ local-declaration ; … ]

… statement-list

… [ EXCEPTION [ exception-case … ] ]

… END [ statement-label ]

local-declaration:

{ variable-declaration

| cursor-declaration

| exception-declaration

| temporary-table-declaration }

variable-declaration:

DECLARE variable-name [ , … ] data-type

[{ = | DEFAULT} initial-value]

initial-value:

special-value

| string

| [ - ] number

| ( constant-expression )

| built-in-function ( constant-expression )

| NULL

special-value:

CURRENT {

DATABASE

| DATE

| PUBLISHER

SQL Statements

84 SAP Sybase IQ

| TIME

| TIMESTAMP

| USER

| UTC TIMESTAMP }

| USER

Parameters

•

statement-label – if specified, it must match the beginning

statement-label

. You can use

the LEAVE statement to resume execution at the first statement after the compound

statement. The compound statement that is the body of a procedure has an implicit label

that is the same as the name of the procedure.

•

initial-value – if specified, the variable is set to that value and the data type must match the

type defined by

data-type

. If you do not specify an initial-value, the variable contains the

NULL value until a

SET

statement assigns a different value.

Examples

•

Example 1 – the body of a procedure is a compound statement:

CREATE PROCEDURE TopCustomer (OUT TopCompany CHAR(35), OUT

TopValue INT)

BEGIN

DECLARE err_notfound EXCEPTION FOR

SQLSTATE '02000' ;

DECLARE curThisCust CURSOR FOR

SELECT CompanyName, CAST(

sum(SalesOrderItems.Quantity *

Products.UnitPrice) AS INTEGER) VALUE

FROM Customers

LEFT OUTER JOIN Salesorders

LEFT OUTER JOIN SalesOrderItems

LEFT OUTER JOIN Products

GROUP BY CompanyName ;

DECLARE ThisValue INT ;

DECLARE ThisCompany CHAR(35) ;

SET TopValue = 0 ;

OPEN curThisCust ;

CustomerLoop:

LOOP

FETCH NEXT curThisCust

INTO ThisCompany, ThisValue ;

IF SQLSTATE = err_notfound THEN

LEAVE CustomerLoop ;

END IF ;

IF ThisValue > TopValue THEN

SET TopValue = ThisValue ;

SET TopCompany = ThisCompany ;

END IF ;

END LOOP CustomerLoop ;

SQL Statements

Reference: Statements and Options 85

CLOSE curThisCust ;

END

Usage

The body of a procedure is a compound statement. Compound statements can also be used in

control statements within a procedure.

A compound statement allows one or more SQL statements to be grouped together and treated

as a unit. A compound statement starts with BEGIN and ends with END. Immediately after

BEGIN, a compound statement can have local declarations that exist only within the

compound statement. A compound statement can have a local declaration for a variable, a

cursor, a temporary table, or an exception. Local declarations can be referenced by any

statement in that compound statement, or in any compound statement nested within it. Local

declarations are invisible to other procedures that are called from within a compound

statement.

An atomic statement is a statement executed completely or not at all. For example, an UPDATE

statement that updates thousands of rows might encounter an error after updating many rows.

If the statement does not complete, all changes revert back to their original state. Similarly, if

you specify that the BEGIN statement is atomic, the statement is executed either in its entirety

or not at all.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Adaptive Server Enterprise. This does not mean that all statements

inside a compound statement are supported.

BEGIN and END keywords are not required in Transact-SQL.

BEGIN and END are used in Transact-SQL to group a set of statements into a single

compound statement, so that control statements such as IF … ELSE, which affect the

performance of only a single SQL statement, can affect the performance of the whole

group. The ATOMIC keyword is not supported by Adaptive Server Enterprise.

In Transact-SQL. DECLARE statements need not immediately follow BEGIN, and the

cursor or variable that is declared exists for the duration of the compound statement. You

should declare variables at the beginning of the compound statement for compatibility.

Permissions

None

See also

•

DECLARE LOCAL TEMPORARY TABLE Statement

on page 246

•

DECLARE CURSOR Statement [ESQL] [SP]

on page 240

•

LEAVE Statement

on page 342

SQL Statements

86 SAP Sybase IQ

•

RESIGNAL Statement

on page 388

•

SIGNAL Statement

on page 437

BEGIN PARALLEL IQ … END PARALLEL IQ Statement

Groups CREATE INDEX statements together for execution at the same time.

Syntax

... BEGIN PARALLEL IQ

statement-list

... END PARALLEL IQ

Parameters

•

statement-list – a list of CREATE INDEX statements

Examples

•

Example 1 – this statement executes atomically. If one command fails, the entire

statement rolls back:

BEGIN PARALLEL IQ

CREATE HG INDEX c1_HG on table1 (col1);

CREATE HNG INDEX c12_HNG on table1 (col12);

CREATE LF INDEX c1_LF on table1 (col1);

CREATE HNG INDEX c2_HNG on table1 (col2);

END PARALLEL IQ

Usage

The BEGIN PARALLEL IQ … END PARALLEL IQ statement lets you execute a group of

CREATE INDEX statements as though they are a single DDL statement, creating indexes on

multiple IQ tables at the same time. While this statement is executing, you and other users

cannot issue other DDL statements.

Note:

• This statement does not support RLV-enabled tables.

• This statement does not support TEXT indexes.

Side effects:

• Automatic commit

SQL Statements

Reference: Statements and Options 87

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise. For support of statements inside

the statement, see

CREATE INDEX Statement

Permissions

None

See also

•

CREATE INDEX Statement

on page 142

BEGIN TRANSACTION Statement [T-SQL]

Use this statement to begin a user-defined transaction.

Note: BEGIN TRANSACTION is a T-SQL construct and must contain only valid T-SQL

commands. You cannot mix T-SQL and non-T-SQL commands.

Syntax

BEGIN TRAN[SACTION] [ transaction-name ]

Examples

•

Example 1 – reports successive values of @@trancount as 0, 1, 2, 1, 0 and prints the

values on the server window:

PRINT @@trancount

BEGIN TRANSACTION

PRINT @@trancount

BEGIN TRANSACTION

PRINT @@trancount

COMMIT TRANSACTION

PRINT @@trancount

COMMIT TRANSACTION

PRINT @@trancount

Do not rely on the value of @@trancount for more than keeping track of the number of

explicit BEGIN TRANSACTION statements that have been issued.

When Adaptive Server Enterprise starts a transaction implicitly, the @@trancount

variable is set to 1. SAP Sybase IQ does not set the @@trancount value to 1 when a

transaction is started implicitly. So, the SAP Sybase IQ @@trancount variable has a value

of zero before any BEGIN TRANSACTION statement (even though there is a current

transaction), while in Adaptive Server Enterprise (in chained mode) it has a value of 1.

For transactions starting with a BEGIN TRANSACTION statement, @@trancount has a

value of 1 in both SAP Sybase IQ and Adaptive Server Enterprise after the first BEGIN

SQL Statements

88 SAP Sybase IQ

TRANSACTION statement. If a transaction is implicitly started with a different statement,

and a BEGIN TRANSACTION statement is then executed, @@trancount has a value of 2 in

both SAP Sybase IQ, and Adaptive Server Enterprise after the BEGIN TRANSACTION

statement.

Usage

The optional parameter

transaction-name

is the name assigned to this transaction. It must be a

valid identifier. Use transaction names only on the outermost pair of nested BEGIN/COMMIT

or BEGIN/ROLLBACK statements.

When executed inside a transaction, the BEGIN TRANSACTION statement increases the

nesting level of transactions by one. The nesting level is decreased by a COMMIT statement.

When transactions are nested, only the outermost COMMIT makes the changes to the database

permanent.

Both Adaptive Server Enterprise and SAP Sybase IQ have two transaction modes.

The default Adaptive Server Enterprise transaction mode, called unchained mode, commits

each statement individually, unless an explicit BEGIN TRANSACTION statement is executed

to start a transaction. In contrast, the ISO SQL/2003 compatible chained mode only commits a

transaction when an explicit COMMIT is executed or when a statement that carries out an

autocommit (such as data definition statements) is executed.

You can control the mode by setting the chained database option. The default setting for

ODBC and embedded SQL connections in SAP Sybase IQ is On, in which case SAP Sybase

IQ runs in chained mode. (ODBC users should also check the AutoCommit ODBC setting).

The default for TDS connections is Off.

In unchained mode, a transaction is implicitly started before any data retrieval or modification

statement. These statements include: DELETE, INSERT, OPEN, FETCH, SELECT, and

UPDATE. You must still explicitly end the transaction with a COMMIT or ROLLBACK

statement.

You cannot alter the chained option within a transaction.

Note: When calling a stored procedure, you should ensure that it operates correctly under the

required transaction mode.

The current nesting level is held in the global variable @@trancount. The @@trancount

variable has a value of zero before the first BEGIN TRANSACTION statement is executed, and

only a COMMIT executed when @@trancount is equal to one makes changes to the database

permanent.

A ROLLBACK statement without a transaction or savepoint name always rolls back statements

to the outermost BEGIN TRANSACTION (explicit or implicit) statement, and cancels the entire

transaction.

SQL Statements

Reference: Statements and Options 89

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Adaptive Server Enterprise.

Permissions

None

See also

•

COMMIT Statement

on page 102

•

ROLLBACK TRANSACTION Statement [T-SQL]

on page 414

•

SAVE TRANSACTION Statement [T-SQL]

on page 416

•

ISOLATION_LEVEL Option

on page 561

CALL Statement

Invokes a procedure.

Syntax

Syntax 1

[ variable = ] CALL procedure-name ( [ expression ] [ , … ] )

Syntax 2

[ variable = ] CALL procedure-name ( [ parameter-name = expression ]

[ , … ] )

Examples

•

Example 1 – calls the sp_customer_list procedure. This procedure has no

parameters, and returns a result set:

CALL sp_customer_list()

•

Example 2 – creates a procedure to return the number of orders placed by the customer

whose ID is supplied, creates a variable to hold the result, calls the procedure, and displays

the result:

CREATE PROCEDURE OrderCount (IN CustomerID INT, OUT Orders INT)

BEGIN

SELECT COUNT("DBA".SalesOrders.ID)

INTO Orders

FROM "DBA".Customers

KEY LEFT OUTER JOIN "DBA".SalesOrders

WHERE "DBA".Customers.ID = CustomerID ;

END

SQL Statements

90 SAP Sybase IQ

-- Create a variable to hold the result

CREATE VARIABLE Orders INT

-- Call the procedure, FOR customer 101

-- -----------------------------

CALL OrderCount ( 101, Orders)

--------------------------------

-- Display the result

SELECT Orders FROM DUMMY

Usage

CALL invokes a procedure that has been previously created with a CREATE PROCEDURE

statement. When the procedure completes, any INOUT or OUT parameter values are copied

back.

You can specify the argument list by position or by using keyword format. By position,

arguments match up with the corresponding parameter in the parameter list for the procedure.

By keyword, arguments match the named parameters.

Procedure arguments can be assigned default values in the CREATE PROCEDURE statement,

and missing parameters are assigned the default value, or, if no default is set, NULL.

Inside a procedure, CALL can be used in a DECLARE statement when the procedure returns

result sets.

Note: You cannot reference a Table UDF in a CALL SQL statement.

Procedures can return an integer value (as a status indicator, say) using the RETURN

statement. You can save this return value in a variable using the equality sign as an assignment

operator:

CREATE VARIABLE returnval INT ;

returnval = CALL proc_integer ( arg1 = val1, ... )

Note: Use of this statement to invoke a function is deprecated. To call functions, use an

assignment statement to invoke the function and assign its result to a variable. For example:

DECLARE varname INT;

SET varname=test( );

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise. For an alternative that is

supported, see

EXECUTE Statement [ESQL]

SQL Statements

Reference: Statements and Options 91

Permissions

Requires one of:

• EXECUTE ANY PROCEDURE system privilege.

• EXECUTE permission for the procedure

• You own the procedure

See also

•

CREATE PROCEDURE Statement

on page 165

•

EXECUTE Statement [ESQL]

on page 276

•

GRANT EXECUTE Statement

on page 310

CASE Statement

The CASE statement is a control statement that lets you choose a list of SQL statements to

execute based on the value of an expression.

Syntax

CASE value-expression

…WHEN [ constant | NULL ] THEN statement-list …

… [ WHEN [ constant | NULL ] THEN statement-list ] …

…ELSE statement-list

… END

Examples

•

Example 1 – classifies the products listed in the Products table of the demo database

into one of shirt, hat, shorts, or unknown:

CREATE PROCEDURE ProductType (IN product_id INT, OUT type

CHAR(10))

BEGIN

DECLARE prod_name CHAR(20) ;

SELECT name INTO prod_name FROM "GROUPO"."Products"

WHERE ID = product_id;

CASE prod_name

WHEN 'Tee Shirt' THEN

SET type = 'Shirt'

WHEN 'Sweatshirt' THEN

SET type = 'Shirt'

WHEN 'Baseball Cap' THEN

SET type = 'Hat'

WHEN 'Visor' THEN

SET type = 'Hat'

WHEN 'Shorts' THEN

SET type = 'Shorts'

ELSE

SET type = 'UNKNOWN'

SQL Statements

92 SAP Sybase IQ

END CASE ;

END

Usage

If a WHEN clause exists for the value of

value-expression

, the

statement-list

in the WHEN

clause is executed. If no appropriate WHEN clause exists, and an ELSE clause exists, the

statement-list

in the ELSE clause is executed. Execution resumes at the first statement after the

END.

Note: The ANSI standard allows two forms of CASE statements. Although SAP Sybase IQ

allows both forms, when CASE is in the predicate, for best performance you must use the form

shown here.

If you require the other form (also called ANSI syntax) for compatibility with SQL Anywhere,

use this syntax:

CASE

WHEN [ search-condition | NULL] THEN statement-list ...

[ WHEN [ search-condition | NULL] THEN statement-list ] ...

[ ELSE statement-list ]

END [ CASE ]

With this ANSI syntax form, the statements are executed for the first satisfied search-

condition in the CASE statement. The ELSE clause is executed if none of the

search-

conditions

are met. If the expression can be NULL, use the following syntax for the first

search-condition

WHEN search-condition IS NULL THEN statement-list

Attention: Do not confuse the syntax of the CASE statement with that of the CASE

expression.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

None

See also

•

BEGIN … END Statement

on page 84

SQL Statements

Reference: Statements and Options 93

CHECKPOINT Statement

Checkpoints the database.

Syntax

CHECKPOINT

Usage

CHECKPOINT forces the database server to execute a checkpoint. Checkpoints are also

performed automatically by the database server according to an internal algorithm.

Applications do not normally need to issue CHECKPOINT.

SAP Sybase IQ uses checkpoints differently than OLTP databases such as SQL Anywhere.

OLTP databases tend to have short transactions that affect only a small number of rows.

Writing entire pages to disk would be very expensive for them. Instead, OLTP databases

generally write to disk at checkpoints, and write only the changed data rows. SAP Sybase IQ is

an OLAP database. A single OLAP transaction can change thousands or millions of rows of

data. For this reason, the database server does not wait for a checkpoint to occur to perform

physical writes. It writes updated data pages to disk after each transaction commits. For an

OLAP database, writing full pages of data to disk is much more effective than writing small

amounts of data at arbitrary checkpoints.

Adjusting the checkpoint time or issuing explicit checkpoints may be unnecessary.

Controlling checkpoints is less important in SAP Sybase IQ than in OLTP database products,

because SAP Sybase IQ writes the actual data pages after each transaction commits.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Adaptive Server Enterprise.

Permissions

Requires the CHECKPOINT system privilege.

CLEAR Statement [Interactive SQL]

Closes any open result sets in Interactive SQL (dbisql).

Syntax

CLEAR

SQL Statements

94 SAP Sybase IQ

Usage

Closes any open result sets and leaves the contents of the SQL Statements pane unchanged

Side effects:

The CLEAR statement closes the cursor associated with the data being cleared.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not applicable.

Permissions

None

See also

•

EXIT Statement [Interactive SQL]

on page 282

CLOSE Statement [ESQL] [SP]

Closes a named cursor.

Syntax

CLOSE cursor-name

cursor-name:

{ identifier | host-variable }

Examples

•

Example 1 – closes cursors in Embedded SQL:

EXEC SQL CLOSE employee_cursor;

EXEC SQL CLOSE :cursor_var;

•

Example 2 – uses a cursor:

CREATE PROCEDURE TopCustomer (OUT TopCompany CHAR(35), OUT

TopValue INT)

BEGIN

DECLARE err_notfound EXCEPTION

FOR SQLSTATE '02000' ;

DECLARE curThisCust CURSOR FOR

SELECT CompanyName,

CAST( sum(SalesOrderItems.Quantity *

Products.UnitPrice) AS INTEGER) VALUE

FROM Customers

LEFT OUTER JOIN SalesOrders

SQL Statements

Reference: Statements and Options 95

LEFT OUTER JOIN SalesOrderItems

LEFT OUTER JOIN Products

GROUP BY CompanyName ;

DECLARE ThisValue INT ;

DECLARE ThisCompany CHAR(35) ;

SET TopValue = 0 ;

OPEN curThisCust ;

CustomerLoop:

LOOP

FETCH NEXT curThisCust

INTO ThisCompany, ThisValue ;

IF SQLSTATE = err_notfound THEN

LEAVE CustomerLoop ;

END IF ;

IF ThisValue > TopValue THEN

SET TopValue = ThisValue ;

SET TopCompany = ThisCompany ;

END IF ;

END LOOP CustomerLoop ;

CLOSE curThisCust ;

END

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Supported by Adaptive Server Enterprise.

Permissions

The cursor must have been previously opened.

See also

•

DECLARE CURSOR Statement [ESQL] [SP]

on page 240

•

OPEN Statement [ESQL] [SP]

on page 369

•

PREPARE Statement [ESQL]

on page 375

COMMENT Statement

Stores a comment, in the system tables, about a database object.

Syntax

COMMENT ON

{ COLUMN [ owner.]table-name.column-name

| DBSPACE dbspace-name

| EVENT event-name

| EXTERNAL [ENVIRONMENT] OBJECT object-name

| EXTERNAL ENVIRONMENT environment-name

| EXTERNAL OBJECT object-name

| FOREIGN KEY [owner.]table-name.role-name

SQL Statements

96 SAP Sybase IQ

| INDEX [ [owner.]table.]index-name

| INTEGRATED LOGIN integrated-login-id

| JAVA CLASS java-class-name

| JAVA JAR java-jar-name

| KERBEROS LOGIN “client-Kerberos-principal”

| LDAP SERVER ldap-server-name

| LOGICAL SERVER logical-server-name

| LOGIN POLICY policy-name

| LS POLICY ls-policy-name

| MATERIALIZED VIEW [owner.]materialized-view-name

| PRIMARY KEY ON [owner.]table-name

| PROCEDURE [owner.]table-name

| ROLE role-name

| SERVICE web-service-name

| SEQUENCE [owner.]sequence-name

| SPATIAL REFERENCE SYSTEM srs-name

| SPATIAL UNIT OF MEASURE uom-identifier

| TABLE [ owner.]table-name

| TEXT CONFIGURATION [ owner.]text-config-name

| TEXT INDEX text-index-name

| TRIGGER [[owner.]table-name.]trigger-name

| USER userid

| VIEW [ owner.]view-name

}

IS comment

environment-name:

comment:

{ string | NULL }

Examples

•

Example 1 – adds a comment to the Employees table:

COMMENT

ON TABLE Employees

IS "Employee information"

•

Example 2 – removes the comment from the Employees table:

COMMENT

ON TABLE Employees

IS NULL

Usage

The COMMENT statement updates remarks in the ISYSREMARK system table. You can

remove a comment by setting it to NULL. The owner of a comment on an index or trigger is the

owner of the table on which the index or trigger is defined.

The COMMENT ON DBSPACE, COMMENT ON JAVA JAR, and COMMENT ON JAVA CLASS

statements allow you to set the Remarks column in the SYS.ISYSREMARK system table.

Remove a comment by setting it to NULL.

SQL Statements

Reference: Statements and Options 97

You cannot add comments for local temporary tables.

Note: Materialized views are supported only for SQL Anywhere tables in the IQ catalog

store.

Standards

• SQL – Vendor extension to ISO/ANSI SQL grammar.

• Sybase – Not supported by Adaptive Server Enterprise.

Permissions

Clause Privilege Required

COLUMN Any one of:

• You own the table

• CREATE ANY TABLE system privilege

• ALTER ANY TABLE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

DBSPACE MANAGE ANY DBSPACE system privilege

EVENT Any one of:

• MANAGE ANY EVENT

• CREATE ANY OBJECT

• ALTER ANY OBJECT

• COMMENT ANY OBJECT

EXTERNAL [ENVIRONMENT]

OBJECT

MANAGE ANY EXTERNAL OBJECT system privilege

EXTERNAL ENVIRONMENT MANAGE ANY EXTERNAL ENVIRONMENT system privi-

lege

FOREIGN KEY Any one of:

• You own the table

• CREATE ANY TABLE system privilege

• ALTER ANY TABLE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

SQL Statements

98 SAP Sybase IQ

Clause Privilege Required

INDEX Any one of:

• You own the index

• CREATE ANY INDEX system privilege

• ALTER ANY INDEX system privilege

• COMMENT ANY OBJECT system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

INTEGRATED LOGIN MANAGE ANY USER system privilege

JAVA CLASS or JAVA JAR MANAGE ANY EXTERNAL OBJECT system privilege

KERBEROS LOGIN MANAGE ANY USER system privilege

LDAP SERVER MANAGE ANY LDAP SERVER system privilege

LOGICAL SERVER MANAGE MULTIPLEX system privilege

LS POLICY MANAGE MULTIPLEX system privilege

MATERIALIZE VIEW Any one of:

• You own the view

• CREATE ANY MATERIALIZED VIEW system privilege

• ALTER ANY MATERIALIZED VIEW system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

PRIMARY KEY ON Any one of:

• You own the table

• CREATE ANY TABLE system privilege

• ALTER ANY TABLE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

SQL Statements

Reference: Statements and Options 99

Clause Privilege Required

PROCEDURE Any one of:

• You own the procedure

• CREATE ANY PROCEDURE system privilege

• ALTER ANY PROCEDURE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

SEQUENCE Any one of:

• You own the sequence

• CREATE ANY SEQUENCE system privilege

• ALTER ANY SEQUENCE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

SERVICE MANAGE ANY WEB SERVICE system privilege

SPATIAL REFERENCE SYS-

TEM

Any one of:

• COMMENT ANY OBJECT

• CREATE ANY OBJECT

• ALTER ANY OBJECT

• MANAGE ANY SPATIAL OBJECT

SPATIAL UNIT OF MEASURE Any one of:

• COMMENT ANY OBJECT

• CREATE ANY OBJECT

• ALTER ANY OBJECT

• MANAGE ANY SPATIAL OBJECT

ROLE System role – administrative privilege over the role being com-

mented on.

User-defined role – MANAGE ROLES system privilege or ad-

ministrative privilege over the role being commented on.

SQL Statements

100 SAP Sybase IQ

Clause Privilege Required

TABLE Any one of:

• You own the table

• CREATE ANY TABLE system privilege

• ALTER ANY TABLE system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

TEXT CONFIGURATION Any one of:

• You created the text configuration

• CREATE ANY TEXT CONFIGURATION system privilege

• ALTER ANY TEXT CONFIGURATION system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

TEXT INDEX Any one of:

• You created the text index

• CREATE ANY INDEX system privilege

• ALTER ANY INDEX system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

TRIGGER Any one of:

• You created the trigger

• CREATE ANY TRIGGER system privilege

• ALTER ANY TRIGGER system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

USER MANAGE ANY USER system privilege

SQL Statements

Reference: Statements and Options 101

Clause Privilege Required

VIEW Any one of:

• You own the view

• CREATE ANY VIEW system privilege

• ALTER ANY VIEW system privilege

• CREATE ANY OBJECT system privilege

• ALTER ANY OBJECT system privilege

• COMMENT ANY OBJECT system privilege

COMMIT Statement

Makes changes to the database permanent, or terminates a user-defined transaction.

Syntax

Syntax 1 – To end a transaction and makes all changes permanent

COMMIT [ WORK ]

Syntax 2 – To construct nested transactions

COMMIT TRAN[SACTION ] [ transaction-name ]

Examples

•

Example 1 – commits the current transaction:

COMMIT

•

Example 2 – this Transact-SQL batch reports successive values of @@trancount as 0,

1, 2, 1, 0:

PRINT @@trancount

BEGIN TRANSACTION

PRINT @@trancount

BEGIN TRANSACTION

PRINT @@trancount

COMMIT TRANSACTION

PRINT @@trancount

COMMIT TRANSACTION

PRINT @@trancount

Usage

•

Syntax 1 – Data definition statements carry out commits automatically. For information,

see the

Side effects

listing for each SQL statement.

COMMIT fails if the database server detects any invalid foreign keys. This makes it

impossible to end a transaction with any invalid foreign keys. Usually, foreign key

SQL Statements

102 SAP Sybase IQ

integrity is checked on each data manipulation operation. However, if the database option

WAIT_FOR_COMMIT is set ON or a particular foreign key was defined with a CHECK ON

COMMIT clause, the database server delays integrity checking until the COMMIT statement

is executed.

•

Syntax 2 – Nested transactions are similar to savepoints. When executed as the outermost

of a set of nested transactions, the statement makes changes to the database permanent.

When executed inside a transaction, COMMIT TRANSACTION decreases the nesting level

of transactions by one. When transactions are nested, only the outermost COMMIT makes

the changes to the database permanent.

The optional parameter

transaction-name

is the name assigned to this transaction. It must

be a valid identifier. Use transaction names only on the outermost pair of nested BEGIN/

COMMIT or BEGIN/ROLLBACK statements.

You can use a set of options to control the detailed behavior of the COMMIT statement. See

COOPERATIVE_COMMIT_TIMEOUT Option

COOPERATIVE_COMMITS Option

DELAYED_COMMITS Option

, and

DELAYED_COMMIT_TIMEOUT Option

. You

can use the Commit connection property to return the number of commits on the current

connection.

Side effects:

• Closes all cursors except those opened WITH HOLD.

• Deletes all rows of declared temporary tables on this connection, unless they were

declared using ON COMMIT PRESERVE ROWS.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Supported by Adaptive Server Enterprise. Syntax 2 is a Transact-SQL extension

to ISO/ANSI SQL grammar.

Permissions

Must be connected to the database.

See also

•

BEGIN TRANSACTION Statement [T-SQL]

on page 88

•

CONNECT Statement [ESQL] [Interactive SQL]

on page 104

•

DISCONNECT Statement [Interactive SQL]

on page 254

•

ROLLBACK Statement

on page 413

•

SAVEPOINT Statement

on page 415

•

SET CONNECTION Statement [ESQL] [Interactive SQL]

on page 429

•

COOPERATIVE_COMMIT_TIMEOUT Option

on page 506

•

COOPERATIVE_COMMITS Option

on page 507

SQL Statements

Reference: Statements and Options 103

•

DELAYED_COMMITS Option

on page 525

•

DELAYED_COMMIT_TIMEOUT Option

on page 525

CONFIGURE Statement [Interactive SQL]

Activates the Interactive SQL (dbisql) configuration window.

Syntax

CONFIGURE

Usage

The dbisql configuration window displays the current settings of all dbisql options. It does not

display or let you modify database options.

If you select Permanent, the options are written to the SYSOPTION table in the database and

the database server performs an automatic COMMIT. If you do not choose Permanent, and

instead click OK, options are set temporarily and remain in effect for the current database

connection only.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

None

See also

•

SET OPTION Statement

on page 431

CONNECT Statement [ESQL] [Interactive SQL]

Establishes a connection to the database identified by

database-name

running on the server

identified by

engine-name

Syntax

Syntax 1

CONNECT

… [ TO engine-name ]

…[ DATABASE database-name ]

SQL Statements

104 SAP Sybase IQ

…[ AS connection-name ]

…[ USER ] userid [ IDENTIFIED BY ]

Syntax 2

CONNECT USING connect-string

Parameters

•

engine-name – identifier, string, or host-variable

•

database-name – identifier, string, or host-variable

•

connection-name – identifier, string, or host-variable

•

userid – identifier, string, or host-variable

•

password – identifier, string, or host-variable

•

connect-string – a list of parameter settings of the form keyword=

value

, and must be

enclosed in single quotes.

•

AS – connection can optionally be named by specifying the clause. This allows multiple

connections to the same database, or multiple connections to the same or different

database servers, all simultaneously. Each connection has its own associated transaction.

You might even get locking conflicts between your transactions if, for example, you try to

modify the same record in the same database from two different connections.

Examples

•

Example 1 – CONNECT usage within Embedded SQL:

EXEC SQL CONNECT AS :conn_name

USER :userid IDENTIFIED BY :password;

EXEC SQL CONNECT USER "dba" IDENTIFIED BY "sql";

•

Example 2 – CONNECT usage from dbisql:

Connect to a database from dbisql. Prompts display for user ID and password:

CONNECT

Connect to the default database as DBA, from dbisql. A password prompt displays:

CONNECT USER "DBA"

Connect to the demo database as the DBA, from dbisql,where

<machine>_iqdemo

is the

engine name:

CONNECT

TO <machine>_iqdemo

USER "DBA"

IDENTIFIED BY sql

Connect to the demo database using a connect string, from dbisql:

SQL Statements

Reference: Statements and Options 105

CONNECT

USING 'UID=DBA;PWD=sql;DBN=iqdemo'

Usage

•

Embedded SQL behavior – in Embedded SQL, if no

engine-name

is specified, the

default local database server is assumed (the first database server started). If no

database-

name

is specified, the first database on the given server is assumed.

The WHENEVER statement, SET SQLCA, and some DECLARE statements do not generate

code and thus might appear before the CONNECT statement in the source file. Otherwise,

no statements are allowed until a successful CONNECT statement has been executed.

The user ID and password are used for permission checks on all dynamic SQL statements.

By default, the password is case-sensitive; the user ID is not. You can connect without a

password by using a host variable for the password and setting the value of the host

variable to be the null pointer.

•

dbisql behavior – if no database or server is specified in the CONNECT statement, dbisql

remains connected to the current database, rather than to the default server and database. If

a database name is specified without a server name,

dbisql

attempts to connect to the

specified database on the current server. You must specify the database name defined in the

-n database switch, not the database file name. If a server name is specified without a

database name, dbisql connects to the default database on the specified server. For

example, if this batch is executed while connected to a database, the two tables are created

in the same database.

CREATE TABLE t1( c1 int );

CONNECT DBA IDENTIFIED BY sql;

CREATE TABLE t2 (c1 int );

No other database statements are allowed until a successful CONNECT statement has been

executed.

The user ID and password are used for checking the permissions on SQL statements. If the

password or the user ID and password are not specified, the user is prompted to type the

missing information. By default, the password is case-sensitive; the user ID is not.

Multiple connections are managed through the concept of a current connection. After a

successful connect statement, the new connection becomes the current one. To switch to a

different connection, use SET CONNECTION. Executing a CONNECT statement does not

close the existing connection (if any). Use DISCONNECT to drop connections.

Static SQL statements use the user ID and password specified with the -l option on the SQLPP

statement line. If no -l option is given, then the user ID and password of the CONNECT

statement are used for static SQL statements also.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

SQL Statements

106 SAP Sybase IQ

• Sybase—Open Client Embedded SQL supports a different syntax for the CONNECT

statement.

Permissions

None

See also

•

DISCONNECT Statement [Interactive SQL]

on page 254

•

GRANT CONNECT Statement

on page 306

•

SET CONNECTION Statement [ESQL] [Interactive SQL]

on page 429

CREATE DATABASE Statement

Creates a database consisting of several operating system files.

Syntax

CREATE DATABASE db-name

… [ [ TRANSACTION ] { LOG ON [ log-file-name ]

[ MIRROR mirror-file-name ] } ]

… [ CASE { RESPECT | IGNORE } ]

… [ PAGE SIZE catalog-page-size ]

… [ COLLATION collation-label[( collation-tailoring-string ) ] ]

… [ ENCRYPTED {algorithm-key-spec | OFF } ]

… [ BLANK PADDING ON ]

… [ JCONNECT { ON | OFF } ]

… [ IQ PATH iq-file-name ]

… [ IQ SIZE iq-file-size ]

… [ IQ PAGE SIZE iq-page-size ]

… [ BLOCK SIZE block-size ]

… [ IQ RESERVE sizeMB ]

… [ TEMPORARY RESERVE sizeMB ]

… [ MESSAGE PATH message-file-name ]

… [ TEMPORARY PATH temp-file-name ]

… [ TEMPORARY SIZE temp-db-size ]

… [ DBA USER userid ]

… [ DBA PASSWORD password ]

… [ SYSTEM PROCEDURE AS DEFINER {ON | OFF} ]

file-name:

db-name

| log-file-name

| mirror-file-name

| iq-file-name

| message-file-name

| temp-file-name

catalog-page-size (bytes):

{ 4096 | 8192 | 16384 | 32768 }

SQL Statements

Reference: Statements and Options 107

iq-page-size (bytes):

{ 65536 | 131072 | 262144 | 524288 }

block-size (bytes):

{ 4096 | 8192 | 16384 | 32768 }

collation-label:

string

collation-tailoring-string:

keyword=value

collation-tailoring-string:

keyword=value

algorithm-key-spec:

| [ ON ] KEY key [ ALGORITHM AES-algorithm ]

| [ ON ] ALGORITHM AES-algorithm KEY key

| [ ON ] ALGORITHM ‘SIMPLE’

AES-algorithm:

‘AES’ | ‘AES256’ | ‘AES_FIPS’ | ‘AES256_FIPS’

key:

quoted string

Parameters

•

TRANSACTION LOG – a file where the database server logs all changes made to the

database. The transaction log plays a key role in system recovery. If you do not specify any

TRANSACTION LOG clause, or if you omit a path for the file name, it is placed in the

same directory as the .db file. However, you should place it on a different physical device

from the .db and .iq. It cannot be created on a raw partition

•

MIRROR – an identical copy of a transaction log, usually maintained on a separate

device, for greater protection of your data. By default, SAP Sybase IQ does not use a

mirrored transaction log. If you do want to use a transaction log mirror, you must provide a

file name. If you use a relative path, the transaction log mirror is created relative to the

directory of the catalog store (db-name.db). Tip: Always create a mirror copy of the

transaction log.

•

CASE – for databases created with CASE RESPECT, all affected values are case-sensitive

in comparisons and string operations. Database object names such as columns,

procedures, or user IDs, are unaffected. Dbspace names are always case-insensitive,

regardless of the CASE specification. The default (RESPECT) is that all comparisons are

case-sensitive. CASE RESPECT provides better performance than CASE IGNORE.

•

PAGE SIZE – page size for the SQL Anywhere segment of the database (containing the

catalog tables) can be 4096, 8192, 16384, or 32768 bytes. Normally, use the default, 4096

(4KB). Large databases might need a larger page size than the default and may see

performance benefits as a result. The smaller values might limit the number of columns

SQL Statements

108 SAP Sybase IQ

your database can support. If you specify a page size smaller than 4096, SAP Sybase IQ

uses a page size of 4096.

•

COLLATION – the collation sequence used for sorting and comparison of character data

types in the database. The collation provides character comparison and ordering

information for the encoding (character set) being used. If the COLLATION clause is not

specified, SAP Sybase IQ chooses a collation based on the operating system language and

encoding. For most operating systems, the default collation sequence is ISO_BINENG,

which provides the best performance. In ISO_BINENG, the collation order is the same as

the order of characters in the ASCII character set. All uppercase letters precede all

lowercase letters (for example, both ‘A’ and ‘B’ precede ‘a’).

You can choose the collation from a list of supported collations. For SQL Anywhere

databases created on an SAP Sybase IQ server, the collation can also be the Unicode

Collation Algorithm (UCA). If UCA is specified, also specify the ENCODING clause.

SAP Sybase IQ does not support any of the UCA-based collations for IQ databases. If a

UCA-based collation is specified in the CREATE DATABASE statement for a database, the

server returns the error UCA collation is not supported and database creation

fails. A collation sequence cannot be changed after the database is created.

Optionally, you can specify collation tailoring options (

collation-tailoring-string

) for

additional control over the sorting and comparing of characters. These options take the

form of keyword=value pairs, assembled in parentheses, following the collation name.

Collation tailoring options for SAP Sybase IQ

contains the supported keyword, allowed

alternate forms, and allowed values for the collation tailoring option (

collation-tailoring-

string

) for an SAP Sybase IQ database.

Table 2. Collation Tailoring Option for SAP Sybase IQ

Keyword Colla-

tion

Alternate

Forms

Allowed Values

CaseSensi-

tivity

All suppor-

ted colla-

tions

CaseSensi-

tive, Case

•

respect – respect case differences between let-

ters. For the UCA collation, this is equivalent to

UpperFirst. For other collations, the value of

respect depends on the collation itself.

•

ignore – ignore case differences between let-

ters.

•

UpperFirst – always sort upper case first (Aa).

•

LowerFirst – always sort lowercase first (aA).

Note: Several collation tailoring options are supported when you specify the UCA

collation for a SQL Anywhere database created on an SAP Sybase IQ server. For all other

collations and for SAP Sybase IQ, only case sensitivity tailoring is supported. Also,

SQL Statements

Reference: Statements and Options 109

databases created with collation tailoring options cannot be started using a pre-15.0

database server.

•

ENCRYPTED – makes the data stored in your physical database file unreadable. Use the

CREATE DATABASE ENCRYPTED keyword without the TABLE keyword to encrypt

the entire database. Use the ENCRYPTED TABLE clause to enable only table encryption

for SQL Anywhere tables. Table-level encryption is not supported for SAP Sybase IQ

tables. Enabling table encryption means that the tables that are subsequently created or

altered using the ENCRYPTED clause are encrypted using the settings you specified at

database creation.

There are two levels of database encryption: simple and strong.

• Simple encryption is equivalent to obfuscation. The data is unreadable, but someone

with cryptographic expertise could decipher the data. For simple encryption, specify

the

CREATE DATABASE

clause

ENCRYPTED ON ALGORITHM ‘SIMPLE’

ENCRYPTED ALGORITHM ‘SIMPLE’

, or specify the

ENCRYPTED ON

clause without

specifying an algorithm or key.

• Strong encryption is achieved through the use of a 128-bit algorithm and a security key.

The data is unreadable and virtually undecipherable without the key. For strong

encryption, specify the

CREATE DATABASE

clause

ENCRYPTED ON ALGORITHM

with a 128-bit or 256-bit AES algorithm and use the

KEY

clause to specify an

encryption key. You should choose a value for your key that is at least 16 characters

long, contains a mix of uppercase and lowercase, and includes numbers, letters, and

special characters.

This encryption key is required each time you start the database.

You can specify encryption only during database creation. To introduce encryption to an

existing database requires a complete unload, database re-creation, and reload of all data.

If the ENCRYPTED clause is used but no algorithm is specified, the default is AES. By

default, encryption is OFF.

Warning! Protect your encryption key! Store a copy of your key in a safe location. A lost

key results in a completely inaccessible database from which there is no recovery.

•

BLANK PADDING – trailing blanks are ignored for comparison purposes (BLANK

PADDING ON), and Embedded SQL programs pad strings that are fetched into character

arrays. This option is provided for compatibility with the ISO/ANSI SQL standard.

CREATE DATABASE no longer supports BLANK PADDING OFF.

•

JCONNECT – to use the SAP Sybase jConnect for JDBC driver to access system catalog

information, install jConnect support. Set JCONNECT to OFF to exclude the jConnect

system objects (the default is ON). You can still use JDBC, as long as you do not access

system information.

•

IQ PATH – the path name of the main segment file containing the SAP Sybase IQ data.

You can specify an operating system file or a raw partition of an I/O device. (The

Installation and Configuration Guide guide for your platform describes the format for

SQL Statements

110 SAP Sybase IQ

specifying a raw partition.) SAP Sybase IQ automatically detects which type based on the

path name you specify. If you use a relative path, the file is created relative to the directory

of the catalog store (the .db file).

If you omit the IQ PATH clause, specifying any of these options generates an error: IQ

SIZE, IQ PAGE SIZE, BLOCK SIZE, MESSAGE PATH, TEMPORARY PATH, and

TEMPORARY SIZE.

•

IQ SIZE – the size in MB of either the raw partition or the operating system file you

specify with the IQ PATH clause. For raw partitions, you should always take the default by

not specifying IQ SIZE, which allows SAP Sybase IQ to use the entire raw partition; if you

specify a value for IQ SIZE, the value must match the size of the I/O device or SAP Sybase

IQ returns an error. For operating system files, you can specify a value from the minimum

in the following table up to a maximum of 4TB.

The default size for an operating system file depends on IQ PAGE SIZE:

Table 3. Default and Minimum Sizes of IQ and Temporary Store Files

IQ PAGE

SIZE

IQ SIZE De-

fault

TEMPORARY

SIZE Default

Minimum

Explicit IQ

SIZE

Minimum Ex-

plicit TEMPO-

RARY SIZE

65536 4096000 2048000 4MB 2MB

131072 8192000 4096000 8MB 4MB

262144 16384000 8192000 16MB 8MB

524288 32768000 16384000 32MB 16MB

•

IQ PAGE SIZE – the page size, in bytes, for the SAP Sybase IQ segment of the database

(containing the IQ tables and indexes). The value must be a power of 2, from 65536 to

524288 bytes. The default is 131072 (128KB). Other values for the size are changed to the

next larger size. The IQ page size determines the default I/O transfer block size and

maximum data compression for your database.

For best performance, use these minimum page sizes:

• 64KB (IQ PAGE SIZE 65536) for databases whose largest table contains up to 1 billion

rows, or a total size less than 8TB. This is the absolute minimum for a new database. On

32-bit platforms, a 64KB IQ page size gives the best performance.

• 128KB (IQ PAGE SIZE 131072) for databases on a 64-bit platform whose largest table

contains more than 1 billion rows and fewer than 4 billion rows, or might grow to a total

size of 8TB or greater. 128KB is the default IQ page size.

• 256KB (IQ PAGE SIZE 262144) for databases on a 64-bit platform whose largest table

contains more than 4 billion rows, or might grow to a total size of 8TB or greater.

•

BLOCK SIZE – the I/O transfer block size, in bytes, for the SAP Sybase IQ segment of

the database. The value must be less than IQ PAGE SIZE, and must be a power of two

SQL Statements

Reference: Statements and Options 111

between 4096 and 32768. Other values for the size are changed to the next larger size. The

default value depends on the value of the IQ PAGE SIZE clause. For most applications, the

default value is optimum.

•

IQ RESERVE – size, in megabytes, of space to reserve for the main IQ store

(IQ_SYSTEM_MAIN dbspace), so that the dbfile can be increased in size in the future.

The sizeMB parameter can be any number greater than 0. You cannot change the reserve

after the dbspace is created. When IQ RESERVE is specified, the database uses more

space for internal (free list) structures. If reserve size is too large, the space needed for the

internal structures can be larger than the specified size, which results in an error.

•

TEMPORARY RESERVE – size, in megabytes, of space to reserve for the temporary IQ

store (IQ_SYSTEM_TEMP dbspace), so that the dbfile can be increased in size in the

future. The sizeMB parameter can be any number greater than 0. You cannot change the

reserve after the dbspace is created. When TEMPORARY RESERVE is specified, the

database uses more space for internal (free list) structures. If reserve size is too large, the

space needed for the internal structures can be larger than the specified size, which results

in an error.

Note: Reserve and mode for temporary dbspaces are lost if the database is restored from a

backup.

•

MESSAGE PATH – path name of the segment containing the SAP Sybase IQ messages

trace file. You must specify an operating system file; the message file cannot be on a raw

partition. If you use a relative path or omit the path, the message file is created relative to

the directory of the .db file.

•

TEMPORARY SIZE – size, in megabytes, of either the raw partition or the operating

system file you specify with the TEMPORARY PATH clause. For raw partitions, always

use the default by not specifying TEMPORARY SIZE, which allows SAP Sybase IQ to

use the entire raw partition. The default for operating system files is always one-half the

value of IQ SIZE. If the IQ store is on a raw partition and the temporary store is an

operating system file, the default TEMPORARY SIZE is half the size of the IQ store raw

partition.

•

DBA USER – user name for the default user account granted the

SYS_AUTH_DBA_ROLE system role. If you do not specify this clause, SAP Sybase IQ

creates a default DBA user ID.

•

DBA PASSWORD – password for the default user account granted the

SYS_AUTH_DBA_ROLE system role.

•

SYSTEM PROCEDURE AS DEFINER – defines whether a privileged system

procedure runs with the privileges of the invoker (the person executing the procedure) or

the definer (the owner of the procedure). OFF (default), or not specified, means all

privileged system procedures execute with the privileges of the invoker. Use

sp_proc_priv() to identify the system privileges required to run a system procedure.

SQL Statements

112 SAP Sybase IQ

ON means that pre-16.0 privileged system procedures execute with the privileges of the

definer. 16.0 or later privileged system procedures execute with the privileges of the

invoker.

Examples

•

Example 1 – this Windows example creates an SAP Sybase IQ database named mydb

with its corresponding mydb.db, mydb.iq, mydb.iqtmp, and mydb.iqmsg files in

the C:\s1\data directory:

CREATE DATABASE 'C:\\s1\\data\\mydb'

BLANK PADDING ON

IQ PATH 'C:\\s1\\data'

IQ SIZE 2000

IQ PAGE SIZE 131072

•

Example 2 – this UNIX command creates an SAP Sybase IQ database with raw devices

for IQ PATH and TEMPORARY PATH. The default IQ page size of 128KB applies.

CREATE DATABASE '/s1/data/bigdb'

IQ PATH '/dev/md/rdsk/bigdb'

MESSAGE PATH '/s1/data/bigdb.iqmsg'

TEMPORARY PATH '/dev/md/rdsk/bigtmp'

•

Example 3 – this Windows command creates an SAP Sybase IQ database with a raw

device for IQ PATH. Note the doubled backslashes in the raw device name (a Windows

requirement):

CREATE DATABASE 'company'

IQ PATH '\\\\.\\E:'

JCONNECT OFF

IQ SIZE 40

•

Example 4 – this UNIX example creates a strongly encrypted SAP Sybase IQ database

using the AES encryption algorithm with the key “is!seCret.”

CREATE DATABASE 'marvin.db'

BLANK PADDING ON

CASE RESPECT

COLLATION 'ISO_BINENG'

IQ PATH '/filesystem/marvin.main1'

IQ SIZE 6400

IQ PAGE SIZE 262144

TEMPORARY PATH '/filesystem/marvin.temp1'

TEMPORARY SIZE 3200

ENCRYPTED ON KEY 'is!seCret' ALGORITHM 'AES'

Usage

Creates a database with the supplied name and attributes. The IQ PATH clause is required for

creating the SAP Sybase IQ database; otherwise, you create a standard SQL Anywhere

database.

SQL Statements

Reference: Statements and Options 113

When SAP Sybase IQ creates a database, it automatically generates four database files to store

different types of data that constitute a database. Each file corresponds to a dbspace, the

logical name by which SAP Sybase IQ identifies database files:

•

db-name.db

is the file that holds the catalog dbspace, SYSTEM. It contains the system

tables and stored procedures describing the database and any standard SQL Anywhere

database objects you add. If you do not include the .db extension, SAP Sybase IQ adds it.

This initial dbspace contains the catalog store, and you can later add dbspaces to increase

its size. It cannot be created on a raw partition.

•

db-name.iq

is the default name of the file that holds the main data dbspace,

IQ_SYSTEM_MAIN, which contains the IQ tables and indexes. You can specify a

different file name with the IQ PATH clause. This initial dbspace contains the IQ store.

Warning! IQ_SYSTEM_MAIN is a special dbspace that contains all structures necessary

for the database to open: the IQ db_identity blocks, the IQ checkpoint log, the IQ

rollforward/rollback bitmaps of each committed transaction and each active checkpointed

transaction, the incremental backup bitmaps, and the freelist root pages.

IQ_SYSTEM_MAIN is always online when the database is open.

The administrator can allow user tables to be created in IQ_SYSTEM_MAIN, especially

if these tables are small, important tables. However, it is more common that immediately

after creating the database, the administrator creates a second main dbspace, revokes

create privilege in dbspace IQ_SYSTEM_MAIN from all users, grants create privilege on

the new main dbspace to selected users, and sets PUBLIC.default_dbspace to the new

main dbspace.

•

db-name.iqtmp

is the default name of the file that holds the initial temporary dbspace,

IQ_SYSTEM_TEMP. It contains the temporary tables generated by certain queries. The

required size of this file can vary depending on the type of query and amount of data. You

can specify a different name using the TEMPORARY PATH clause. This initial dbspace

contains the temporary store.

•

db-name.iqmsg

is the default name of the file that contains the messages trace dbspace,

IQ_SYSTEM_MSG. You can specify a different file name using the MESSAGE PATH

clause.

In addition to these files, a database has a transaction log file (db-name.log), and might

have a transaction log mirror file.

File names and the CREATE DATABASE statement:

The file names (

db-name

log-file-name

mirror-file-name

iq-file-name

message-file-name

temp-file-name

) are strings containing operating system file names. As literal strings, they

must be enclosed in single quotes.

• In Windows, if you specify a path, any backslash characters (\) must be doubled if they are

followed by an n or an x. This prevents them being interpreted as a newline character (\n) or

as a hexadecimal number (\x), according to the rules for strings in SQL. It is safer to always

double the backslash. For example:

SQL Statements

114 SAP Sybase IQ

CREATE DATABASE 'c:\\sybase\\mydb.db'

LOG ON 'e:\\logdrive\\mydb.log'

JCONNECT OFF

IQ PATH 'c:\\sybase\\mydb'

IQ SIZE 40

• If you specify no path, or a relative path:

• The catalog store file (

db-name.db

) is created relative to the working directory of the

server.

• The IQ store, temporary store, and message log files are created in the same directory

as, or relative to, the catalog store.

Relative path names are recommended.

Warning! The database file, temporary dbspace, and transaction log file must be located on

the same physical machine as the database server. Do not place database files and transaction

log files on a network drive. The transaction log should be on a separate device from its mirror,

however.

On UNIX-like operating systems, you can create symbolic links, which are indirect pointers

that contain the path name of the file to which they point. You can use symbolic links as

relative path names. There are several advantages to creating a symbolic link for the database

file name:

• Symbolic links to raw devices can have meaningful names, while the actual device name

syntax can be obscure.

• A symbolic name might eliminate problems restoring a database file that was moved to a

new directory since it was backed up.

To create a symbolic link, use the ln -s command. For example:

ln -s /disk1/company/iqdata/company.iq company_iq_store

Once you create this link, you can specify the symbolic link in commands like CREATE

DATABASE or RESTORE instead of the fully qualified path name.

When you create a database or a dbspace, the path for every dbspace file must be unique. If

your CREATE DATABASE command specifies the identical path and file name for these two

stores, you receive an error.

You can create a unique path in any of these ways:

• Specify a different extension for each file (for example, mydb.iq and mydb.iqtmp)

• Specify a different file name (for example, mydb.iq and mytmp.iq)

• Specify a different path name (for example, /iqfiles/main/iq and /iqfiles/

temp/iq) or different raw partitions

• Omit TEMPORARY PATH when you create the database. In this case, the temporary store

is created in the same path as the catalog store, with the default name and extension

dbname.iqtmp, where

dbname

is the database name.

SQL Statements

Reference: Statements and Options 115

Warning! To maintain database consistency on UNIX-like operating systems, you must

specify file names that are links to different files. SAP Sybase IQ cannot detect the target

where linked files point. Even if the file names in the command differ, make sure they do not

point to the same operating system file.

Character strings inserted into tables are always stored in the case they are entered, regardless

of whether the database is case-sensitive or not. If the string Value is inserted into a character

data type column, the string is always stored in the database with an uppercase V and the

remainder of the letters lowercase. SELECT statements return the string as Value. If the

database is not case-sensitive, however, all comparisons make Value the same as value,

VALUE, and so on. The SAP Sybase IQ server may return results in any combination of

lowercase and uppercase, so you cannot expect case-sensitive results in a database that is

case-insensitive (CASE IGNORE).

For example, given this table and data:

CREATE TABLE tb (id int NOT NULL,

string VARCHAR(30) NOT NULL);

INSERT INTO tb VALUES (1, ‘ONE’);

SELECT * FROM tb WHERE string = ‘oNe’;

The result of the

SELECT

can be “oNe” (as specified in the WHERE clause) and not

necessarily “ONE” (as stored in the database).

Similarly, the result of:

SELECT * FROM tb WHERE string = ‘One’;

can be “One” and the result of:

SELECT * FROM tb WHERE string = ‘ONe’;

can be “ONe”.

All databases are created with at least one user ID:

DBA

and password:

sql

In new databases, all passwords are case-sensitive, regardless of the case-sensitivity of the

database. The user ID is unaffected by the CASE RESPECT setting.

When you start a database, its page size cannot be larger than the page size of the current

server. The server page size is taken from the first set of databases started or is set on the server

command line using the -gp command line option.

Command line length for any statement is limited to the catalog page size. The 4KB default is

large enough in most cases; however, in a few cases, a larger PAGE SIZE value is needed to

accommodate very long commands, such as RESTORE commands that reference numerous

dbspaces. A larger page size might also be needed to execute queries involving large numbers

of tables or views.

SQL Statements

116 SAP Sybase IQ

Because the default catalog page size is 4KB, this is a problem only when the connection is to a

database such as utility_db, which has a page size of 1024. This restriction may cause

RESTORE commands that reference numerous dbspaces to fail. To avoid the problem, make

sure the length of SQL command lines is less than the catalog page size.

Alternatively, start the engine with -gp 32768 to increase catalog page size.

Side effects:

• Automatic commit

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Adaptive Server Enterprise provides a CREATE DATABASE statement, but with

different options.

Permissions

The permissions required to execute this statement are set using the -gu server command line

option, as follows:

•

NONE – No user can issue this statement.

•

DBA – Requires the SERVER OPERATOR system privilege.

•

UTILITY_DB – Only those users who can connect to the utility_db database can

issue this statement.

The account under which the server is running must have write permissions on the directories

where files are created.

See also

•

CREATE DBSPACE Statement

on page 117

•

DROP DATABASE Statement

on page 260

CREATE DBSPACE Statement

Creates a new dbspace and the associated dbfiles for the IQ main store, catalog store, or RLV

store.

Syntax

Syntax 1 – Use for catalog store dbspaces only (SQL Anywhere (SA) dbspaces).

CREATE DBSPACE dbspace-name AS file-path CATALOG STORE

Syntax 2 – Use for IQ main store dbspaces.

SQL Statements

Reference: Statements and Options 117

CREATE DBSPACE dbspace-name USING file-specification

[ IQ STORE ] iq-dbspace-opts

Syntax 3 – Use for RLV dbspaces.

CREATE DBSPACE dbspace-name USING file-specification

IQ RLV STORE

file-specification:

{ single-path-spec | new-file-spec [, ...] }

single-path-spec:

'file-path' | iq-file-opts

new-file-spec:

FILE logical-file-name | 'file-path' iq-file-opts

iq-file-opts:

[ [ SIZE ] file-size ]

…[ KB | MB | GB | TB ] ]

[ RESERVE size

…[ KB | MB | GB | TB ] ]

iq-dbspace-opts:

[ STRIPING ] {ON | OFF} ] …[ STRIPESIZEKB sizeKB ]

Parameters

•

new-file-spec – creates a dbspace for the IQ main store. You can specify one or more

dbfiles for the IQ main store. The dbfile name and physical file path are required for each

file, and must be unique.

•

RESERVE – specifies the size in kilobytes (KB), megabytes (MB), gigabytes (GB), or

terabytes (TB) of space to reserve, so that the dbspace can be increased in size in the future.

The

size

parameter can be any number greater than 0; megabytes is the default. You cannot

change the reserve after the dbspace dbfile is created.

When RESERVE is specified, the database uses more space for internal (free list)

structures. If reserve size is too large, the space needed for the internal structures can be

larger than the specified size, which results in an error.

•

dbspace-name and dbfile-name – internal names for dbspaces and dbfiles. A database

can have as many as (32KB - 1) dbspaces, including the initial dbspaces created when you

create the database. However, your operating system might limit the number of dbfiles per

database.

•

file-path – the actual operating system file name of the dbfile, with a preceding path where

necessary.

file-path

without an explicit directory is created in the same directory as the

catalog store of the database. Any relative directory is relative to the catalog store.

•

SIZE – specifies the size, from 0 to 4 terabytes, of the operating system file specified in

file-path

. The default depends on the store type and block size. For the IQ main store, the

default number of bytes equals 1000* the block size. You cannot specify the SIZE clause

SQL Statements

118 SAP Sybase IQ

for the catalog store. A SIZE value of 0 creates a dbspace of minimum size, which is 8MB

for the IQ main store.

For raw partitions, do not explicitly specify SIZE. SAP Sybase IQ automatically sets this

parameter to the maximum raw partition size, and returns an error if you attempt to specify

another size.

•

STRIPESIZEKB – specifies the number of kilobytes (KB) to write to each file before the

disk striping algorithm moves to the next stripe for the specified dbspace.

If you do not specify striping or stripe size, the default values of the options

DEFAULT_DISK_STRIPING and DEFAULT_KB_PER_STRIPE apply.

Examples

•

Example 1 – creates a dbspace called DspHist for the IQ main store with two dbfiles on

a UNIX system. Each dbfile is 1GB in size and can grow 500MB:

CREATE DBSPACE DspHist USING FILE

FileHist1 '/History1/data/file1'

SIZE 1000 RESERVE 500,

FILE FileHist2 '/History1/data/file2'

SIZE 1000 RESERVE 500;

•

Example 2 – creates a second catalog dbspace called DspCat2:

CREATE DBSPACE DspCat2 AS

'catalog_file2'

CATALOG STORE;

•

Example 3 – creates an IQ main dbspace called EmpStore1 for the IQ store (three

alternate syntax examples):

CREATE DBSPACE EmpStore1

USING FILE EmpStore1

'EmpStore1.IQ' SIZE 8 MB IQ STORE;

CREATE DBSPACE EmpStore1

USING FILE EmpStore1

'EmpStore1.IQ' 8 IQ STORE;

CREATE DBSPACE EmpStore1

USING FILE EmpStore1

'EmpStore1.IQ' 8;

•

Example 4 – creates a RLV store dbspace called d1:

CREATE DBSPACE d1

USING FILE f1

'f1.iq' SIZE 100 IQ RLV STORE;

SQL Statements

Reference: Statements and Options 119

Usage

CREATE DBSPACE creates a new dbspace for the IQ main store, catalog store, or RLV store.

The dbspace you add can be on a different disk device than the initial dbspace, allowing you to

create stores that are larger than one physical device.

Syntax 1 creates a dbspace for the catalog store, where both dbspace and dbfile have the same

logical name. Each dbspace in the catalog store has a single file.

The dbspace name and dbfile names are always case-insensitive. The physical file paths have

the case sensitivity of the operating system if the database is CASE RESPECT, and are case-

insensitive if the database is CASE IGNORE.

You cannot create a dbspace for an IQ temporary store. A single temporary dbspace,

IQ_SYSTEM_TEMP, is created when you create a new database or upgrade one that was

created in a version earlier than SAP Sybase IQ 15.3. You can add additional files to the

IQ_SYSTEM_TEMP dbspace using the ALTER DBSPACE ADD FILE syntax.

Note: Creating a RLV dbspace containing a minimum of one file is a prerequisite for RLV

storage. Before enabling RLV storage on a simplex server, check that the RLV dbspace exists.

You can create a unique path in any of these ways:

• Specify a different extension for each file (for example, mydb.iq)

• Specify a different file name (for example, mydb2.iq)

• Specify a different path name (for example, /iqfiles/main/iq) or different raw

partitions

Warning! On UNIX platforms, to maintain database consistency, specify file names that are

links to different files. SAP Sybase IQ cannot detect the target where linked files point. Even if

the file names in the command differ, make sure they do not point to the same operating system

file.

Side effects:

• Automatic commit

• Automatic checkpoint.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires the MANAGE ANY DBSPACE system privilege.

SQL Statements

120 SAP Sybase IQ

See also

•

CREATE DATABASE Statement

on page 107

•

DROP Statement

on page 255

CREATE DOMAIN Statement

Creates a user-defined data type in the database.

Syntax

CREATE { DOMAIN | DATATYPE } domain-name data-type

… [ NOT ] NULL ]

… [ DEFAULT ]

default-value:

special-value

| string

| global variable

| [ - ] number

| ( constant-expression )

| built-in-function( constant-expression )

| AUTOINCREMENT

| CURRENT DATABASE

| CURRENT REMOTE USER

| NULL

| TIMESTAMP

| LAST USER

special-value:

CURRENT

{ DATE

| TIME

| TIMESTAMP

| USER

| PUBLISHER }

| USER

Parameters

•

data-type – built-in data type, with precision and scale

Examples

•

Example 1 – create a data type named address, which holds a 35-character string, and

which may be NULL:

CREATE DOMAIN address CHAR( 35 ) NULL

SQL Statements

Reference: Statements and Options 121

Usage

User-defined data types are aliases for built-in data types, including precision and scale

values, where applicable. They improve convenience and encourage consistency in the

database.

Note: Use CREATE DOMAIN, rather than CREATE DATATYPE, as CREATE DOMAIN is the

ANSI/ISO SQL3 term.

The user who creates a data type is automatically made the owner of that data type. No owner

can be specified in the CREATE DATATYPE statement. The user-defined data type name must

be unique, and all users can access the data type without using the owner as prefix.

User-defined data types are objects within the database. Their names must conform to the

rules for identifiers. User-defined data type names are always case-insensitive, as are built-in

data type names.

By default, user-defined data types allow NULLs unless the allow_nulls_by_default database

option is set to OFF. In this case, new user-defined data types by default do not allow NULLs.

The nullability of a column created on a user-defined data type depends on the setting of the

definition of the user-defined data type, not on the setting of the allow_nulls_by_default

option when the column is referenced. Any explicit setting of NULL or NOT NULL in the

column definition overrides the user-defined data type setting.

The CREATE DOMAIN statement allows you to specify DEFAULT values on user-defined data

types. The DEFAULT value specification is inherited by any column defined on the data type.

Any DEFAULT value explicitly specified on the column overrides that specified for the data

type.

The CREATE DOMAIN statement lets you incorporate a rule, called a CHECK condition, into

the definition of a user-defined data type.

SAP Sybase IQ enforces CHECK constraints for base, global temporary. local temporary

tables, and user-defined data types.

To drop the data type from the database, use the DROP statement. You must be either the owner

of the data type or have the CREATE DATATYPE or CREATE ANY OBJECT system

privilege in order to drop a user-defined data type.

Side effects:

• Automatic commit

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Not supported by Adaptive Server Enterprise. Transact-SQL provides similar

functionality using the sp_addtype system procedure and the CREATE DEFAULT and

CREATE RULE statements.

SQL Statements

122 SAP Sybase IQ

Permissions

Requires one of:

• CREATE DATATYPE system privilege.

• CREATE ANY OBJECT system privilege.

See also

•

DROP Statement

on page 255

CREATE EVENT Statement

Defines an event and its associated handler for automating predefined actions. Also defines

scheduled actions.

Syntax

CREATE EVENT event-name

[ TYPE event-type

[ WHERE trigger-condition [ AND trigger-condition ], ...]

| SCHEDULE schedule-spec, … ]

…[ ENABLE | DISABLE ]

…[ AT { CONSOLIDATED | REMOTE | ALL } ]

…[ HANDLER

BEGIN

…

END ]

event-type:

BackupEnd

| “Connect”

| ConnectFailed

| DatabaseStart

| DBDiskSpace

| “Disconnect”

| GlobalAutoincrement

| GrowDB

| GrowLog

| GrowTemp

| IQMainDBSpaceFree

| IQTempDBSpaceFree

| LogDiskSpace

| “RAISERROR”

| ServerIdle

| TempDiskSpace

trigger-condition:

event_condition( condition-name )

{ =

SQL Statements

Reference: Statements and Options 123

| <

| >

| !=

| <=

| >= } value

schedule-spec:

[ schedule-name ]

{ START TIME start-time | BETWEEN start-time AND end-time }

[ EVERY period { HOURS | MINUTES | SECONDS } ]

[ ON { ( day-of-week, … ) | ( day-of-month, … ) } ]

[ START DATE start-date ]

Parameters

•

event-name – an event has a creator, which is the user creating the event, and the event

handler executes with the permissions of that creator. This is the same as stored procedure

execution. You cannot create events owned by other users. You can list event names by

querying the system table SYSEVENT. For example:

SELECT event_id, event_name FROM SYS.SYSEVENT

•

event-type – one of a set of system-defined event types. The event types are case-

insensitive. To specify the conditions under which this

event-type

triggers the event, use

the WHERE clause.

• DiskSpace – if the database contains an event handler for one of the DiskSpace types,

the database server checks the available space on each device associated with the

relevant file every 30 seconds.

In the event the database has more than one dbspace, on separate drives, DBDiskSpace

checks each drive and acts depending on the lowest available space.

• LogDiskSpace – checks the location of the transaction log and any mirrored

transaction log, and reports based on the least available space.

• Globalautoincrement – fires when the GLOBAL AUTOINCREMENT default value

for a table is within one percent of the end of its range. A typical action for the handler

could be to request a new value for the GLOBAL_DATABASE_ID clause.

You can use the EVENT_CONDITION function with RemainingValues as an argument

for this event type.

• ServerIdle – if the database contains an event handler for the ServerIdle type, the server

checks for server activity every 30 seconds.

•

WHERE clause – the trigger condition determines the condition under which an event is

fired. For example, to take an action when the disk containing the transaction log becomes

more than 80% full, use this triggering condition:

...

WHERE event_condition( 'LogDiskSpacePercentFree' ) < 20

...

SQL Statements

124 SAP Sybase IQ

The argument to the EVENT_CONDITION function must be valid for the event type. You

can use multiple AND conditions to make up the WHERE clause, but you cannot use OR

conditions or other conditions.

•

SCHEDULE – specifies when scheduled actions are to take place. The sequence of times

acts as a set of triggering conditions for the associated actions defined in the event

handler.You can create more than one schedule for a given event and its associated handler.

This permits complex schedules to be implemented. While it is compulsory to provide a

schedule name when there is more than one schedule, it is optional if you provide only a

single schedule.

You can list schedule names by querying the system table SYSSCHEDULE. For example:

SELECT event_id, sched_name FROM SYS.SYSSCHEDULE

Each event has a unique event ID. Use the event_id columns of SYSEVENT and

SYSSCHEDULE to match the event to the associated schedule.

When a nonrecurring scheduled event has passed, its schedule is deleted, but the event

handler is not deleted.

Scheduled event times are calculated when the schedules are created, and again when the

event handler completes execution. The next event time is computed by inspecting the

schedule or schedules for the event, and finding the next schedule time that is in the future.

If an event handler is instructed to run every hour between 9:00 and 5:00, and it takes 65

minutes to execute, it runs at 9:00, 11:00, 1:00, 3:00, and 5:00. If you want execution to

overlap, you must create more than one event.

The subclauses of a schedule definition are as follows:

• START DATE – the date on which scheduled events are to start occurring. The default is

the current date.

• START TIME – the first scheduled time for each day on which the event is scheduled. If

a START DATE is specified, the START TIME refers to that date. If no START DATE

is specified, the START TIME is on the current day (unless the time has passed) and

each subsequent day.

• BETWEEN … AND – a range of times during the day outside of which no scheduled

times occur. If a START DATE is specified, the scheduled times do not occur until that

date.

• EVERY – an interval between successive scheduled events. Scheduled events occur

only after the START TIME for the day, or in the range specified by BETWEEN …

AND.

• ON – a list of days on which the scheduled events occur. The default is every day. These

can be specified as days of the week or days of the month.

Days of the week are Monday, Tuesday, and so on. The abbreviated forms of the day,

such as Mon, Tue, and so on, may also be used. The database server recognizes both

full-length and abbreviated day names in any of the languages supported by SAP

Sybase IQ.

SQL Statements

Reference: Statements and Options 125

Days of the month are integers from 0 to 31. A value of 0 represents the last day of any

month.

Each time a scheduled event handler is completed, the next scheduled time and date is

calculated.

• If the EVERY clause is used, find whether the next scheduled time falls on the current

day, and is before the end of the BETWEEN …AND range. If so, that is the next

scheduled time.

• If the next scheduled time does not fall on the current day, find the next date on which

the event is to be executed.

• Find the START TIME for that date, or the beginning of the BETWEEN … AND

range.

•

ENABLE | DISABLE – by default, event handlers are enabled. When DISABLE is

specified, the event handler does not execute even when the scheduled time or triggering

condition occurs. A TRIGGER EVENT statement does not cause a disabled event handler

to be executed

•

AT – to execute events at remote or consolidated databases in a SQL Remote setup, use this

clause to restrict the databases at which the event is handled. By default, all databases

execute the event.

•

HANDLER – each event has one handler. Like the body of a stored procedure, the handler

is a compound statement. There are some differences, though: you can use an

EXCEPTION clause within the compound statement to handle errors, but not the ON

EXCEPTION RESUME clause provided within stored procedures.

Examples

•

Example 1 – instructs the database server to carry out an automatic incremental backup

daily at 1 a.m.:

CREATE EVENT IncrementalBackup

SCHEDULE

START TIME '1:00AM' EVERY 24 HOURS

HANDLER

BEGIN

BACKUP DATABASE INCREMENTAL

TO 'backups/daily.incr'

END

•

Example 2 – instructs the database server to call the system stored procedure

sp_iqspaceused every 10 minutes, then store in a table the returned current date and

time, the current number of connections to the database, and current information about the

use of main and temporary IQ store:

CREATE TABLE mysummary(dt DATETIME,

users INT, mainKB UNSIGNED BIGINT,

mainPC UNSIGNED INT,

SQL Statements

126 SAP Sybase IQ

tempKB UNSIGNED BIGINT,

tempPC UNSIGNED INT) ;

CREATE EVENT mysummary

SCHEDULE sched_mysummary

START TIME '00:01 AM' EVERY 10 MINUTES

HANDLER

BEGIN

DECLARE mt UNSIGNED BIGINT;

DECLARE mu UNSIGNED BIGINT;

DECLARE tt UNSIGNED BIGINT;

DECLARE tu UNSIGNED BIGINT;

DECLARE conncount UNSIGNED INT;

SET conncount = DB_PROPERTY('ConnCount');

CALL SP_IQSPACEUSED(mt,mu,tt,tu);

INSERT INTO mysummary VALUES( NOW(),

conncount, mu, (mu*100)/mt, tu,

(tu*100)/tt );

END;

•

Example 3 – posts a message to the server log when free disk space on the device

containing the transaction log file falls below 30 percent, but execute the handler no more

than once every 300 seconds.

CREATE EVENT LowTxnLogDiskSpace

TYPE DBDiskSpace

WHERE event_condition( 'DBFreePercent' ) < 30

AND event_condition( 'Interval' ) >= 300

HANDLER

BEGIN

message 'Disk space for Transaction Log is low.';

END;

Usage

Events can be used in two main ways:

• Scheduling actions – the database server carries out a set of actions on a schedule of times.

You can use this capability to schedule backups, validity checks, queries to fill up reporting

tables, and so on.

• Event handling actions – the database server carries out a set of actions when a predefined

event occurs. The events that can be handled include disk space restrictions (when a disk

fills beyond a specified percentage), when the server is idle, and so on.

An event definition includes two distinct pieces. The trigger condition can be an occurrence,

such as a disk filling up beyond a defined threshold. A schedule is a set of times, each of which

acts as a trigger condition. When a trigger condition is satisfied, the event handler executes.

The event handler includes one or more actions specified inside a compound statement

(BEGIN... END).

If no trigger condition or schedule specification is supplied, only an explicit TRIGGER EVENT

statement can trigger the event. During development, you might want to develop and test event

SQL Statements

Reference: Statements and Options 127

handlers using TRIGGER EVENT and add the schedule or WHERE clause once testing is

complete.

Event errors are logged to the database server console.

When event handlers are triggered, the server makes context information, such as the

connection ID that caused the event to be triggered, available to the event handler using the

EVENT_PARAMETER function.

Note: Although statements that return result sets are disallowed in events, you can allow an

event to call a stored procedure and insert the procedure results into a temporary table.

Side Effects:

• Automatic commit.

• The actions of an event handler are committed if no error is detected during execution, and

rolled back if errors are detected.

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires one of:

• MANAGE ANY EVENT system privilege.

• CREATE ANY OBJECT system privilege.

Event handlers execute on a separate connection, with the privileges of the event owner. To

execute with privileges other than MANAGE ANY EVENT system privilege, you can call a

procedure from within the event handler: the procedure executes with the permissions of its

owner. The separate connection does not count towards the ten-connection limit of the

personal database server.

See also

•

ALTER EVENT Statement

on page 14

•

BEGIN … END Statement

on page 84

•

COMMENT Statement

on page 96

•

DROP Statement

on page 255

•

TRIGGER EVENT Statement

on page 443

SQL Statements

128 SAP Sybase IQ

CREATE EXISTING TABLE Statement

Creates a new proxy table that represents an existing table on a remote server.

Syntax

CREATE EXISTING TABLE [owner.]table_name

[ ( column-definition, … ) ]

AT 'location-string'

column-definition:

column-name data-type [ NOT NULL ]

location-string:

remote-server-name.[db-name].[owner].object-name | remote-server-

name;[db-name];[owner];object-name

Parameters

•

column-definition – if you do not specify column definitions, SAP Sybase IQ derives the

column list from the metadata it obtains from the remote table. If you do specify column

definitions, SAP Sybase IQ verifies them. When SAP Sybase IQ checks column names,

data types, lengths, and null properties:

• Column names must match identically (although case is ignored).

• Data types in CREATE EXISTING TABLE must match or be convertible to the data types

of the column on the remote location. For example, a local column data type is defined

as NUMERIC, whereas the remote column data type is MONEY. You may encounter

some errors, if you select from a table in which the data types do not match or other

inconsistencies exist.

• Each column’s NULL property is checked. If the local column’s NULL property is not

identical to the remote column’s NULL property, a warning message is issued, but the

statement is not aborted.

• Each column’s length is checked. If the lengths of CHAR, VARCHAR, BINARY,

DECIMAL, and NUMERIC columns do not match, a warning message is issued, but the

command is not aborted. You might choose to include only a subset of the actual

remote column list in your CREATE EXISTING statement.

•

AT – specifies the location of the remote object. The AT clause supports the semicolon (;)

as a delimiter. If a semicolon is present anywhere in the location string, the semicolon is the

field delimiter. If no semicolon is present, a period is the field delimiter. This allows you to

use file names and extensions in the database and owner fields. Semicolon field delimiters

are used primarily with server classes that are not currently supported; however, you can

also use them where a period would also work as a field delimiter.

SQL Statements

Reference: Statements and Options 129

For example, this statement maps the table proxy_a1 to the SQL Anywhere database

mydb on the remote server myasa:

CREATE EXISTING TABLE

proxy_a1

AT 'myasa;mydb;;a1'

Examples

•

Example 1 – create a proxy table named nation for the nation table at the remote

server server_a:

CREATE EXISTING TABLE nation

( n_nationkey int,

n_name char(25),

n_regionkey int,

n_comment char(152))

AT 'server_a.db1.joe.nation'

•

Example 2 – create a proxy table named blurbs for the blurbs table at the remote

server server_a. SAP Sybase IQ derives the column list from the metadata it obtains

from the remote table:

CREATE EXISTING TABLE blurbs

AT 'server_a.db1.joe.blurbs'

•

Example 3 – create a proxy table named rda_employee for the Employees table at

the SAP Sybase IQ remote server remote_iqdemo_srv:

CREATE EXISTING TABLE rda_employee

AT 'remote_iqdemo_srv..dba.Employees'

Usage

CREATE EXISTING TABLE is a variant of the CREATE TABLE statement. The EXISTING

keyword is used with CREATE TABLE to specify that a table already exists remotely, and that

its metadata is to be imported into SAP Sybase IQ. This establishes the remote table as a

visible entity to its users. SAP Sybase IQ verifies that the table exists at the external location

before it creates the table.

Tables used as proxy tables cannot have names longer than 30 characters.

If the object does not exist (either as a host data file or remote server object), the statement is

rejected with an error message.

Index information from the host data file or remote server table is extracted and used to create

rows for the system table sysindexes. This defines indexes and keys in server terms and

enables the query optimizer to consider any indexes that might exist on this table.

Referential constraints are passed to the remote location when appropriate.

SQL Statements

130 SAP Sybase IQ

In a simplex environment, you cannot create a proxy table that refers to a remote table on the

same node. In a multiplex environment, you cannot create a proxy table that refers to the

remote table defined within the multiplex.

For example, in a simplex environment, if you try to create proxy table proxy_e, which

refers to base table Employees defined on the same node, the CREATE EXISTING TABLE

statement is rejected with an error message. In a multiplex environment, the CREATE

EXISTING TABLE statement is rejected if you create proxy table proxy_e from any node

(coordinator or secondary) that refers to remote table Employees defined within a

multiplex.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Supported by Open Client/Open Server.

Permissions

For table to be owned by self – Requires one of:

• CREATE ANY TABLE system privilege.

• CREATE ANY OBJECT system privilege.

For table to be owned by any user – Requires the CREATE ANY TABLE system privilege.

See also

•

CREATE TABLE Statement

on page 205

CREATE EXTERNLOGIN Statement

Assigns an alternate login name and password to be used when communicating with a remote

server.

Syntax

CREATE EXTERNLOGIN login-name

TO remote-server

REMOTE LOGIN remote-user

[ IDENTIFIED BY remote-password ]

Parameters

•

name

is the database user to which the Windows user ID is mapped.

•

TO – specifies the name of the remote server.

SQL Statements

Reference: Statements and Options 131

•

REMOTE LOGIN – specifies the user account on

remote-server

for the local user

name

•

IDENTIFIED BY – specifies that

remote-password

is the password for

remote-user

. If

you omit the IDENTIFIED BY clause, the password is sent to the remote server as NULL.

If you specify IDENTIFIED BY " " (an empty string), the password sent is the empty

string.

Examples

•

Example 1 – maps the local user named DBA to the user sa with password 4TKNOX when

connecting to the server sybase1:

CREATE EXTERNLOGIN dba

TO sybase1

REMOTE LOGIN sa

IDENTIFIED BY 4TKNOX

Usage

Changes made by

CREATE EXTERNLOGIN

do not take effect until the next connection to the

remote server.

By default, SAP Sybase IQ uses the names and passwords of its clients whenever it connects to

a remote server on behalf of those clients. CREATE EXTERNLOGIN assigns an alternate login

name and password to be used when communicating with a remote server. It stores the

password internally in encrypted form.

The

remote_server

must be known to the local server by an entry in the ISYSSERVER system

table. For more information, see the

CREATE SERVER Statement

Creating a remote login with the CREATE EXTERNLOGIN statement and defining a remote

server with a CREATE SERVER statement sets up an external login and password for the

INSERT...LOCATION such that any user can use the login and password in any context. This

avoids possible errors due to inaccessibility of the login or password, and is the recommended

way to connect to a remote server.

Note: If you rely on the user ID and password of the current connection, and a user changes the

password, you must stop and restart the server before the new password takes effect on the

remote server. Remote logins created with CREATE EXTERNLOGIN are unaffected by

changes to the password for the default user ID.

Sites with automatic password expiration should plan for periodic updates of passwords for

external logins.

CREATE EXTERNLOGIN cannot be used from within a transaction.

The

remote-user

and

remote-password

combination must be valid on

remote-server

Side Effects

SQL Statements

132 SAP Sybase IQ

• Automatic commit

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Supported by Open Client/Open Server.

Permissions

Requires the MANAGE ANY USER system privilege.

See also

•

DROP EXTERNLOGIN Statement

on page 261

•

INSERT Statement

on page 327

•

CREATE SERVER Statement

on page 192

CREATE FUNCTION Statement

Creates a user-defined function in the database. A function can be created for another user by

specifying an owner name. Subject to permissions, a user-defined function can be used in

exactly the same way as other non-aggregate functions.

Syntax

Syntax 1

CREATE [ OR REPLACE ] [ TEMPORARY ] FUNCTION [ owner.]function-name

( [ parameter, … ] )

[ SQL SECURITY { INVOKER | DEFINER } ]

RETURNS data-type ON EXCEPTION RESUME

| [ NOT ] DETERMINISTIC

{ compound-statement | AS tsql-compound-statement

| EXTERNAL NAME library-call

| EXTERNAL NAME java-call LANGUAGE JAVA }

parameter:

IN parameter-name data-type [ DEFAULT expression ]

routine-characteristics:

ON EXCEPTION RESUME | [ NOT ] DETERMINISTIC

tsql-compound-statement:

sql-statement

sql-statement …

library-call:

'[ operating-system:]function-name@library; …'

operating-system:

SQL Statements

Reference: Statements and Options 133

UNIX

java-call:

'[ package-name.]class-name.method-name method-signature'

method-signature:

( [ field-descriptor, ….] ) return-descriptor

field-descriptor and return-descriptor:

Z | B | S | I | J | F | D | C | V | [ descriptor | L class-name;

Syntax 2

CREATE FUNCTION [ owner.]function-name ( [ parameter, … ] )

RETURNS data-type

URL url-string

[ HEADER header-string ]

[ SOAPHEADER soap-header-string ]

[ TYPE { 'HTTP[:{ GET | POST } ] ' | 'SOAP[:{ RPC | DOC } ]' } ]

[ NAMESPACE namespace-string ]

[ CERTIFICATE certificate-string ]

[ CLIENTPORT clientport-string ]

[ PROXY proxy-string ]

url-string:

' { HTTP | HTTPS | HTTPS_FIPS }://[user:password@]hostname[:port][/

path] '

parameter:

IN parameter-name data-type [ DEFAULT expression ]

Parameters

•

CREATE [ OR REPLACE ] – parameter names must conform to the rules for database

identifiers. They must have a valid SQL data type and be prefixed by the keyword IN,

signifying that the argument is an expression that provides a value to the function.

The CREATE clause creates a new function, while the OR REPLACE clause replaces an

existing function with the same name. When a function is replaced, the definition of the

function is changed but the existing permissions are preserved. You cannot use the OR

REPLACE clause with temporary functions.

•

TEMPORARY – the function is visible only by the connection that created it, and that it is

automatically dropped when the connection is dropped. Temporary functions can also be

explicitly dropped. You cannot perform ALTER, GRANT, or REVOKE operations on them,

and unlike other functions, temporary functions are not recorded in the catalog or

transaction log.

Temporary functions execute with the permissions of their creator (current user), and can

only be owned by their creator. Therefore, do not specify owner when creating a temporary

function. They can be created and dropped when connected to a read-only database.

SQL Statements

134 SAP Sybase IQ

•

SQL SECURITY – defines whether the function is executed as the INVOKER, the user

who is calling the function, or as the DEFINER, the user who owns the function. The

default is DEFINER.

When INVOKER is specified, more memory is used because annotation must be done for

each user that calls the procedure. Also, name resolution is done as the invoker as well.

Therefore, take care to qualify all object names (tables, procedures, and so on) with their

appropriate owner.

•

data-type – LONG BINARY and LONG VARCHAR are not permitted as return-value

data types.

•

compound-statement – a set of SQL statements bracketed by BEGIN and END, and

separated by semicolons. See

BEGIN … END Statement

•

tsql-compound-statement – a batch of Transact-SQL statements.

•

external-name – a wrapper around a call to a function in an external library and can have

no other clauses following the RETURNS clause. The library name may include the file

extension, which is typically .dll on Windows and .so on UNIX. In the absence of the

extension, the software appends the platform-specific default file extension for libraries.

The external-name clause is not supported for temporary functions.

•

LANGUAGE JAVA – a wrapper around a Java method. For information on calling Java

procedures, see

CREATE PROCEDURE Statement

•

ON EXCEPTION RESUME – uses Transact-SQL-like error handling. See

CREATE

PROCEDURE Statement

•

[NOT] DETERMINISTIC – function is re-evaluated each time it is called in a query. The

results of functions not specified in this manner may be cached for better performance, and

re-used each time the function is called with the same parameters during query evaluation.

Functions that have side effects, such as modifying the underlying data, should be declared

as NOT DETERMINISTIC. For example, a function that generates primary key values

and is used in an INSERT … SELECT statement should be declared NOT

DETERMINISTIC:

CREATE FUNCTION keygen( increment INTEGER )

RETURNS INTEGER

NOT DETERMINISTIC

BEGIN

DECLARE keyval INTEGER;

UPDATE counter SET x = x + increment;

SELECT counter.x INTO keyval FROM counter;

RETURN keyval

END

INSERT INTO new_table

SELECT keygen(1), ...

FROM old_table

CREATE FUNCTION keygen( increment INTEGER )

RETURNS INTEGER

SQL Statements

Reference: Statements and Options 135

NOT DETERMINISTIC

BEGIN

DECLARE keyval INTEGER;

UPDATE counter SET x = x + increment;

SELECT counter.x INTO keyval FROM counter;

RETURN keyval

END

INSERT INTO new_table

SELECT keygen(1), ...

FROM old_table

Functions may be declared as DETERMINISTIC if they always return the same value for

given input parameters. All user-defined functions are treated as deterministic unless they

are declared NOT DETERMINISTIC. Deterministic functions return a consistent result

for the same parameters and are free of side effects. That is, the database server assumes

that two successive calls to the same function with the same parameters will return the

same result without unwanted side-effects on the semantics of the query.

•

URL – for use only when defining an HTTP or SOAP web services client function.

Specifies the URL of the web service. The optional user name and password parameters

provide a means of supplying the credentials needed for HTTP basic authentication. HTTP

basic authentication base-64 encodes the user and password information and passes it in

the “Authentication” header of the HTTP request.

For web service client functions, the return type of SOAP and HTTP functions must one of

the character data types, such as VARCHAR. The value returned is the body of the HTTP

response. No HTTP header information is included. If more information is required, such

as status information, use a procedure instead of a function.

Parameter values are passed as part of the request. The syntax used depends on the type of

request. For HTTP:GET, the parameters are passed as part of the URL; for HTTP:POST

requests, the values are placed in the body of the request. Parameters to SOAP requests are

always bundled in the request body.

•

HEADER – when creating HTTP web service client functions, use this clause to add or

modify HTTP request header entries. Only printable ASCII characters can be specified for

HTTP headers, and they are case-insensitive. For more information about how to use this

clause, see the HEADER clause of the

CREATE PROCEDURE Statement

•

SOAPHEADER – when declaring a SOAP Web service as a function, use this clause to

specify one or more SOAP request header entries. A SOAP header can be declared as a

static constant, or can be dynamically set using the parameter substitution mechanism

(declaring IN, OUT, or INOUT parameters for hd1, hd2, and so on). A web service

function can define one or more IN mode substitution parameters, but cannot define an

INOUT or OUT substitution parameter.

•

TYPE – specifies the format used when making the web service request. If SOAP is

specified or no type clause is included, the default type SOAP:RPC is used. HTTP implies

SQL Statements

136 SAP Sybase IQ

HTTP:POST. Since SOAP requests are always sent as XML documents, HTTP:POST is

always used to send SOAP requests.

•

NAMESPACE – applies to SOAP client functions only and identifies the method

namespace usually required for both SOAP:RPC and SOAP:DOC requests. The SOAP

server handling the request uses this namespace to interpret the names of the entities in the

SOAP request message body. The namespace can be obtained from the WSDL description

of the SOAP service available from the web service server. The default value is the

procedure's URL, up to but not including the optional path component.

•

CERTIFICATE – to make a secure (HTTPS) request, a client must have access to the

certificate used by the HTTPS server. The necessary information is specified in a string of

semicolon-separated key/value pairs. The certificate can be placed in a file and the name of

the file provided using the file key, or the whole certificate can be placed in a string, but not

both. These keys are available:

Key Abbreviation Description

file File name of certificate

certificate cert The certificate

company co Company specified in the certificate

unit Company unit specified in the certificate

name Common name specified in the certificate

Certificates are required only for requests that are either directed to an HTTPS server or

can be redirected from an insecure to a secure server.

•

CLIENTPORT – identifies the port number on which the HTTP client procedure

communicates using TCP/IP. It is provided for and recommended only for connections

across firewalls, as firewalls filter according to the TCP/UDP port. You can specify a single

port number, ranges of port numbers, or a combination of both; for example,

CLIENTPORT '85,90-97'.

•

PROXY – specifies the URI of a proxy server. For use when the client must access the

network through a proxy. Indicates that the procedure is to connect to the proxy server and

send the request to the web service through it.

Examples

•

Example 1 – concatenates a firstname string and a lastname string:

CREATE FUNCTION fullname (

firstname CHAR(30),

lastname CHAR(30) )

RETURNS CHAR(61)

BEGIN

DECLARE name CHAR(61);

SQL Statements

Reference: Statements and Options 137

SET name = firstname || ' ' || lastname;

RETURN (name);

END

This example illustrates the use of the fullname function.

• Return a full name from two supplied strings:

SELECT fullname ('joe','smith')

fullname('joe', 'smith')

joe smith

• List the names of all employees:

SELECT fullname (givenname, surname)

FROM Employees

fullname (givenname, surname)

Fran Whitney

Matthew Cobb

Philip Chin

Julie Jordan

Robert Breault

...

•

Example 2 – uses Transact-SQL syntax:

CREATE FUNCTION DoubleIt ( @Input INT )

RETURNS INT

DECLARE @Result INT

SELECT @Result = @Input * 2

RETURN @Result

The statement SELECT DoubleIt( 5 ) returns a value of 10.

•

Example 3 – creates an external function written in Java:

CREATE FUNCTION dba.encrypt( IN name char(254) )

RETURNS VARCHAR

EXTERNAL NAME

'Scramble.encrypt (Ljava/lang/String;)Ljava/lang/String;'

LANGUAGE JAVA

Usage

To modify a user-defined function, or to hide the contents of a function by scrambling its

definition, use the ALTER FUNCTION statement.

SQL Statements

138 SAP Sybase IQ

When functions are executed, not all parameters need to be specified. If a default value is

provided in the CREATE FUNCTION statement, missing parameters are assigned the default

values. If an argument is not provided by the caller and no default is set, an error is given.

Side Effects

• Automatic commit

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

For function to be owned by self – Requires the CREATE PROCEDURE system privilege.

For function to be owned by any user – Requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

To create a function containing an external reference, regardless of whether or not they are the

owner of the function, also requires the CREATE EXTERNAL REFERENCE system

privilege.

See also

•

ALTER FUNCTION Statement

on page 16

•

BEGIN … END Statement

on page 84

•

CREATE PROCEDURE Statement

on page 165

•

DROP Statement

on page 255

•

RETURN Statement

on page 396

CREATE FUNCTION Statement (Java UDF)

Creates a new external Java table UDF function in the database.

Syntax

CREATE [ OR REPLACE | TEMPORARY ] FUNCTION [ owner.]function-name

( [ parameter, … ] )

[ SQL SECURITY { INVOKER | DEFINER } ]

RETURNS data-type

ON EXCEPTION RESUME

| [ NOT ] DETERMINISTIC

{ compound-statement | AS tsql-compound-statement

| EXTERNAL NAME 'java-call' LANGUAGE JAVA [ ALLOW | DISALLOW SERVER SIDE

REQUESTS ] environment-name}

SQL Statements

Reference: Statements and Options 139

parameter:

IN parameter-name data-type [ DEFAULT expression ]

tsql-compound-statement:

sql-statement

sql-statement …

java-call:

'[ package-name.]class-name.method-name method-signature'

method-signature:

( [ field-descriptor, ….] ) return-descriptor

field-descriptor and return-descriptor:

Z | B | S | I | J | F | D | C | V | [ descriptor | L class-name;

Parameters

•

CREATE [ OR REPLACE ] – parameter names must conform to the rules for database

identifiers. They must have a valid SQL data type and be prefixed by the keyword IN,

signifying that the argument is an expression that provides a value to the function.

The CREATE clause creates a new function, while the OR REPLACE clause replaces an

existing function with the same name. When a function is replaced, the definition of the

function is changed but the existing permissions are preserved. You cannot use the OR

REPLACE clause with temporary functions.

•

TEMPORARY – the function is visible only by the connection that created it, and that it is

automatically dropped when the connection is dropped. Temporary functions can also be

explicitly dropped. You cannot perform ALTER, GRANT, or REVOKE operations on them,

and unlike other functions, temporary functions are not recorded in the catalog or

transaction log.

Temporary functions execute with the permissions of their creator (current user), and can

only be owned by their creator. Therefore, do not specify owner when creating a temporary

function. They can be created and dropped when connected to a read-only database.

•

SQL SECURITY – defines whether the function is executed as the INVOKER, the user

who is calling the function, or as the DEFINER, the user who owns the function. The

default is DEFINER.

When INVOKER is specified, more memory is used because annotation must be done for

each user that calls the procedure. Also, name resolution is done as the invoker as well.

Therefore, take care to qualify all object names (tables, procedures, and so on) with their

appropriate owner.

•

data-type – LONG BINARY and LONG VARCHAR are not permitted as return-value

data types.

SQL Statements

140 SAP Sybase IQ

•

compound-statement – a set of SQL statements bracketed by BEGIN and END, and

separated by semicolons. See

BEGIN … END Statement

•

tsql-compound-statement – a batch of Transact-SQL statements.

•

[NOT] DETERMINISTIC – function is re-evaluated each time it is called in a query. The

results of functions not specified in this manner may be cached for better performance, and

re-used each time the function is called with the same parameters during query evaluation.

Functions that have side effects, such as modifying the underlying data, should be declared

as NOT DETERMINISTIC. For example, a function that generates primary key values

and is used in an INSERT … SELECT statement should be declared NOT

DETERMINISTIC:

CREATE FUNCTION keygen( increment INTEGER )

RETURNS INTEGER

NOT DETERMINISTIC

BEGIN

DECLARE keyval INTEGER;

UPDATE counter SET x = x + increment;

SELECT counter.x INTO keyval FROM counter;

RETURN keyval

END

INSERT INTO new_table

SELECT keygen(1), ...

FROM old_table

CREATE FUNCTION keygen( increment INTEGER )

RETURNS INTEGER

NOT DETERMINISTIC

BEGIN

DECLARE keyval INTEGER;

UPDATE counter SET x = x + increment;

SELECT counter.x INTO keyval FROM counter;

RETURN keyval

END

INSERT INTO new_table

SELECT keygen(1), ...

FROM old_table

Functions may be declared as DETERMINISTIC if they always return the same value for

given input parameters. All user-defined functions are treated as deterministic unless they

are declared NOT DETERMINISTIC. Deterministic functions return a consistent result

for the same parameters and are free of side effects. That is, the database server assumes

that two successive calls to the same function with the same parameters will return the

same result without unwanted side-effects on the semantics of the query.

•

LANGUAGE JAVA – a wrapper around a Java method. For information on calling Java

procedures, see

CREATE PROCEDURE Statement

•

environment-name – a wrapper around a Java method.

The DISALLOW clause is the default. The ALLOW clause indicates that server-side

connections are allowed.

SQL Statements

Reference: Statements and Options 141

Note: Do not specify the ALLOW clause unless necessary. ALLOW slows down certain

types of SAP Sybase IQ table joins. Do not use UDFs with both the ALLOW and

DISALLOW SERVER SIDE REQUESTS clauses in the same query.

Examples

•

Example 1 – creates an external function written in Java:

CREATE FUNCTION dba.encrypt( IN name char(254) )

RETURNS VARCHAR

EXTERNAL NAME

'Scramble.encrypt (Ljava/lang/String;)Ljava/lang/String;'

LANGUAGE JAVA

Usage

When functions are executed, not all parameters need to be specified. If a default value is

provided in the

CREATE FUNCTION

statement, missing parameters are assigned the default

values. If an argument is not provided by the caller and no default is set, an error is given.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

For function to be owned by self – Requires the CREATE PROCEDURE system privilege

For function to be owned by any user – Requires one of:

• CREATE ANY PROCEDURES system privilege.

• CREATE ANY OBJECT system privilege.

To create a function containing an external reference, regardless of whether or not they are the

owner of the function, also requires the CREATE EXTERNAL REFERENCE system

privilege.

CREATE INDEX Statement

Creates an index on a specified table, or pair of tables. Once an index is created, it is never

referenced in a SQL statement again except to delete it using the DROP INDEX statement.

Syntax

CREATE [ UNIQUE ] [ index-type ] INDEX [ IF NOT EXISTS ] index-name

…ON [ owner.]table-name

… ( column-name [ , column-name ] …)

SQL Statements

142 SAP Sybase IQ

…[ { IN | ON } dbspace-name ]

…[ NOTIFY integer ]

…[ DELIMITED BY ‘separators-string ‘ ]

…[ LIMIT maxwordsize-integer ]

index-type:

{ CMP | HG | HNG | LF | WD | DATE | TIME | DTTM }

Parameters

•

index-type – for columns in SAP Sybase IQ tables, you can specify an index-type of HG

(High_Group), HNG (High_Non_Group), LF (Low_Fast), WD (Word), DATE, TIME, or

DTTM (Datetime). If you do not specify an index-type, an HG index is created by default.

To create an index on the relationship between two columns in an IQ main store table, you

can specify an index-type of CMP (Compare). Columns must be of identical data type,

precision and scale. For a CHAR, VARCHAR, BINARY or VARBINARY column, precision

means that both columns have the same width.

For maximum query speed, the correct type of index for a column depends on:

• The number of unique values in the column

• How the column is going to be used in queries

• The amount of disk space available

You can specify multiple indexes on a column of an IQ main store table, but these must be

of different index types. CREATE INDEX does not let you add a duplicate index type. SAP

Sybase IQ chooses the fastest index available for the current query or portion of the query.

However, each additional index type might significantly add to the space requirements of

that table.

•

column-name – specifies the name of the column to be indexed. A column name is an

identifier preceded by an optional correlation name. (A correlation name is usually a table

name. For more information on correlation names, see

FROM Clause

.) If a column name

has characters other than letters, digits, and underscore, enclose it in quotation marks

(“”).

If you omit the UNIQUE clause, you can specify only an HG index. Foreign keys require

nonunique indexes and composite foreign keys require nonunique composite HG indexes.

The multicolumn composite key for both unique and nonunique HG indexes has a

maximum width of 5300 bytes. CHAR or VARCHAR data cannot be more than 255 bytes

when it is part of a composite key or single-column HG, LF, HNG, DATE, TIME, or

DTTM indexes.

•

UNIQUE – ensures that no two rows in the table have identical values in all the columns in

the index. Each index key must be unique or contain a NULL in at least one column. You

can create unique HG indexes with more than one column, but you cannot create

multicolumn indexes using other index types. You cannot specify UNIQUE with the CMP,

HNG, WD, DATE, TIME, or DTTM index types.

SQL Statements

Reference: Statements and Options 143

SAP Sybase IQ allows the use of NULL in data values on a user created unique

multicolumn HG index, if the column definition allows for NULL values and a constraint

(primary key or unique) is not being enforced. See “Multicolumn indexes” in

Notes

for

more information.

•

IF NOT EXISTS – if the named object already exists, no changes are made and an error is

not returned.

•

IN – specifies index placement. If you omit the IN clause, the index is created in the

dbspace where the table is created. An index is always placed in the same type of dbspace

(IQ store or temporary store) as its table. When you load the index, the data is spread across

any database files of that type with room available. SAP Sybase IQ ensures that any

dbspace-name

you specify is appropriate for the index. If you try to specify

IQ_SYSTEM_MAIN or other main dbspaces for indexes on temporary tables, or vice

versa, you receive an error. Dbspace names are always case-insensitive, regardless of the

CREATE DATABASE...CASE IGNORE or CASE RESPECT specification.

•

DELIMITED BY – specifies separators to use in parsing a column string into the words to

be stored in the WD index of that column. If you omit this clause or specify the value as an

empty string, SAP Sybase IQ uses the default set of separators. The default set of

separators is designed for the default collation order (ISO-BINENG). It includes all 7-bit

ASCII characters that are not 7-bit ASCII alphanumeric characters, except for the hyphen

and the single quotation mark. The hyphen and the single quotation mark are part of words

by default. There are 64 separators in the default separator set. For example, if the column

value is this string:

The cat is on the mat

and the database was created with the CASE IGNORE setting using default separators,

these words are stored in the WD index from this string:

cat is mat on the

If you specify multiple DELIMITED BY and LIMIT clauses, no error is returned, but only

the last clause of each type is used.

•

separators-string – must be a sequence of 0 or more characters in the collation order used

when the database was created. Each character in the separators string is treated as a

separator. If there are no characters in the separators string, the default set of separators is

used. (Each separator must be a single character in the collation sequence being used.)

There cannot be more than 256 characters (separators) in the separators string.

To specify tab as a delimiter, you can either type a <TAB> character within the separator

string, or use the hexadecimal ASCII code of the tab character, \x09. “\t” specifies two

separators, \ and the letter t. To specify newline as a delimiter, you can type a <RETURN>

character or the hexadecimal ASCII code \x0a.

For example, the clause DELIMITED BY ' :;.\/t' specifies these seven separators:

space : ; . \ / t

SQL Statements

144 SAP Sybase IQ

Table 4. Tab and Newline as Delimiters

For these delimiters Use this separators string in the DELIMI-

TED BY clause

tab ' ' (type <TAB>)or

'\x09'

newline ' ' (type <RETURN>) or '\x0a'

•

LIMIT – can be used for the creation of the WD index only. Specifies the maximum word

length that is permitted in the WD index. Longer words found during parsing causes an

error. The default is 255 bytes. The minimum permitted value is 1 and the maximum

permitted value is 255. If the maximum word length specified in the

CREATE INDEX

statement or determined by default exceeds the column width, the used maximum word

length is silently reduced to the column width. Using a lower maximum permitted word

length allows insertions, deletions, and updates to use less space and time. The empty word

(two adjacent separators) is silently ignored. After a WD index is created, any insertions

into its column are parsed using the separators and maximum word size determined at

create time. These separators and maximum word size cannot be changed after the index is

created.

•

NOTIFY – gives notification messages after n records are successfully added for the

index. The messages are sent to the standard output device. A message contains

information about memory usage, database space, and how many buffers are in use. The

default is 100,000 records. To turn off NOTIFY, set it to 0.

•

–

Examples

•

Example 1 – creates a Compare index on the projected_earnings and

current_earnings columns. These columns are decimal columns with identical

precision and scale.

CREATE CMP INDEX proj_curr_cmp

ON sales_data

( projected_earnings, current_earnings )

•

Example 2 – creates a High_Group index on the ID column of the SalesOrderItems

table. The data pages for this index are allocated from dbspace Dsp5.

CREATE HG INDEX id_hg

ON SalesOrderItems

( ID ) IN Dsp5

•

Example 3 – creates a High_Group index on the SalesOrderItems table for the

ProductID column:

SQL Statements

Reference: Statements and Options 145

CREATE HG INDEX item_prod_hg

ON Sales_OrderItems

( ProductID)

•

Example 4 – creates a Low_Fast index on the SalesOrderItems table for the same

ProductID column without any notification messages:

CREATE LF INDEX item_prod

ON SalesOrderItems

( ProductID)

NOTIFY 0

•

Example 5 – creates a WD index on the earnings_report table. Specify that the

delimiters of strings are space, colon, semicolon, and period. Limit the length of the strings

to 25.

CREATE WD INDEX earnings_wd

ON earnings_report_table(varchar)

DELIMITED BY ‘ :;.’

LIMIT 25

•

Example 6 – creates a DTTM index on the SalesOrders table for the OrderDate

column:

CREATE DTTM INDEX order_dttm

ON SalesOrders

( OrderDate )

Usage

• Index ownership—There is no way to specify the index owner in the CREATE INDEX

statement. Indexes are automatically owned by the owner of the table on which they are

defined. The index name must be unique for each owner.

• No indexes on views—Indexes cannot be created for views.

• Index name—The name of each index must be unique for a given table.

• Exclusive table use—CREATE INDEX is prevented whenever the statement affects a table

currently being modified by another connection. However, queries are allowed on a table

that is also adding an index.

• CHAR columns—After a WD index is created, any insertions into its column are parsed

using the separators, and maximum word size cannot be changed after the index is created.

For CHAR columns, specify a space as at least one of the separators or use the default

separator set. SAP Sybase IQ automatically pads CHAR columns to the maximum column

width. If your column contains blanks in addition to the character data, queries on WD

indexed data might return misleading results. For example, column CompanyName

contains two words delimited by a separator, but the second word is blank padded:

‘Concord’ ‘Farms ’

Suppose that a user entered this query:

SELECT COUNT(*)FROM Customers WHERE CompanyName contains (‘Farms’)

The parser determines that the string contains:

SQL Statements

146 SAP Sybase IQ

‘Farms ’

instead of:

‘Farms’

and returns 0 instead of 1. You can avoid this problem by using VARCHAR instead of CHAR

columns.

• Data types:

• You cannot use CREATE INDEX to create an index on a column with BIT data.

• Only the default index, CMP index, or WD index can be created on CHAR and

VARCHAR data with more than 255 bytes.

• Only the default and

index types can be created on LONG VARCHAR data.

• Only the default index,

CMP

index, and

TEXT

index types can be created on BINARY

and VARBINARY data with more than 255 bytes.

• An

HNG

index or a

CMP

index cannot be created on a column with FLOAT, REAL, or

DOUBLE data.

• A

TIME

index can be created only on a column having the data type TIME.

• A

DATE

index can be created only on a column having the data type DATE.

• A

DTTM

index can be created only on a column having the data type DATETIME or

TIMESTAMP.

• Multicolumn indexes—You can create a unique or nonunique HG index with more than

one column. SAP Sybase IQ implicitly creates a nonunique HG index on a set of columns

that makes up a foreign key.

HG and CMP are the only types of indexes that can have multiple columns. You cannot

create a unique HNG or LF index with more than one column, and you cannot create a

DATE, TIME, or DTTM index with more than one column.

The maximum width of a multicolumn concatenated key is 5KB (5300 bytes). The number

of columns allowed depends on how many columns can fit into 5KB. CHAR or VARCHAR

data greater than 255 bytes are not allowed as part of a composite key in single-column HG,

LF, HNG, DATE, TIME, or DTTM indexes.

An INSERT on a multicolumn index must include all columns of the index.

Queries with a single column in the ORDER BY clause run faster using multicolumn HG

indexes. For example:

SELECT abs (x) from t1

ORDER BY x

In the above example, the HG index vertically projects

in sorted order.

To enhance query performance, use multicolumn HG indexes to run ORDER BY operations

on more than one column (that can also include ROWID) in the SELECT or ORDER BY

clause with these conditions:

• All projected columns, plus all ordering columns (except ROWID), exist within the

index

SQL Statements

Reference: Statements and Options 147

• The ordering keys match the leading HG columns, in order

If more than one multicolumn HG index satisfies these conditions, the index with the

lowest distinct counts is used.

If a query has an ORDER BY clause, and the ORDER BY column list is a prefix of a

multicolumn index where all columns referenced in the SELECT list are present in a

multicolumn index, then the multicolumn index performs vertical projection; for example:

SELECT x,z,y FROM T

ORDER BY x,y

If expressions exist on base columns in the SELECT list, and all the columns referenced in

all the expressions are present in the multicolumn index, then the query will use a

multicolumn index; for example:

SELECT power(x,2), x+y, sin(z) FROM T

ORDER BY x,y

In addition to the two previous examples, if the

ROWID()

function is in the

SELECT

list

expressions, multicolumn indexes will be used. For example:

SELECT rowid()+x, z FROM T

ORDER BY x,y,z

In addition to the three previous examples, if ROWID() is present at the end of an ORDER

BY list, and if the columns of that list—except for ROWID()—use multicolumn indexes in

the exact order, multicolumn indexes will be used for the query. For example:

SELECT z,y FROM T

ORDER BY x,y,z,ROWID()

SAP Sybase IQ allows the use of NULL in data values on a user created unique

multicolumn HG index, if the column definition allows for NULL values and a constraint

(primary key or unique) is not being enforced. The rules for this feature are as follows:

• A NULL is treated as an undefined value.

• Multiple rows with NULL values in a unique index column or columns are allowed.

In a single column index, multiple rows with a NULL value in an index column are

allowed.

In a multicolumn index, multiple rows with a NULL value in index column or

columns are allowed, as long as non-NULL values in the rest of the columns

guarantee uniqueness in that index.

In a multicolumn index, multiple rows with NULL values in all columns

participating in the index are allowed.

These examples illustrate these rules. Given the table table1:

CREATE TABLE table1

(c1 INT NULL, c2 INT NULL, c3 INT NOT NULL);

Create a unique single column HG index on a column that allows NULLs:

CREATE UNIQUE HG INDEX c1_hg1 ON table1 (c1);

According to rule 1 above, you can insert a NULL value into an index column in multiple

rows:

SQL Statements

148 SAP Sybase IQ

INSERT INTO table1(c1,c2,c3) VALUES (NULL,1,1);

INSERT INTO table1(c1,c2,c3) VALUES (NULL,2,2);

Create a unique multicolumn HG index on a columns that allows NULLs:

CREATE UNIQUE HG INDEX c1c2_hg2 ON table1(c1,c2);

According to rule 2 above, you must guarantee uniqueness in the index. The following

INSERT does not succeed, since the multicolumn index c1c2_hg2 on row 1 and row 3

has the same value:

INSERT INTO table1(c1,c2,c3) VALUES (NULL,1,3);

These INSERT operations are successful, however, according to rules 1 and 3:

INSERT INTO table1(c1,c2,c3) VALUES (NULL,NULL,3);

INSERT INTO table1(c1,c2,c3) VALUES (NULL,NULL,4);

Uniqueness is preserved in the multicolumn index.

This

UPDATE

operation is successful, as rule 3 allows multiple rows with NULL values in

all columns in the multicolumn index:

UPDATE table1 SET c2=NULL WHERE c3=1

When a multicolumn HG index is governed by a unique constraint, a NULL value is not

allowed in any column participating in the index.

• Parallel index creation—You can use the BEGIN PARALLEL IQ … END PARALLEL IQ

statement to group CREATE INDEX statements on multiple IQ main store tables, so that

they execute as though they are a single DDL statement. See

BEGIN PARALLEL IQ …

END PARALLEL IQ Statement

for more information.

Warning! Using the CREATE INDEX command on a local temporary table containing

uncommitted data fails and generates the error message Local temporary table,

<tablename>, must be committed in order to create an index.

Commit the data in the local temporary table before creating an index.

Side Effects

• Automatic commit

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—Adaptive Server Enterprise has a more complex CREATE INDEX statement than

SAP Sybase IQ. While the Adaptive Server Enterprise syntax is permitted in SAP Sybase

IQ, some clauses and keywords are ignored. For the full syntax of the Adaptive Server

Enterprise CREATE INDEX statement, see the

Adaptive Server Enterprise Reference

Manual, Volume 2: Commands

Adaptive Server Enterprise indexes can be either

clustered

nonclustered

. A clustered index

almost always retrieves data faster than a nonclustered index. Only one clustered index is

permitted per table.

SQL Statements

Reference: Statements and Options 149

SAP Sybase IQ does not support clustered indexes. The CLUSTERED and

NONCLUSTERED keywords are allowed by SQL Anywhere, but are ignored by SAP Sybase

IQ. If no

index-type

is specified, SAP Sybase IQ creates an HG index on the specified

column(s).

SAP Sybase IQ does not permit the DESC keyword.

Index names must be unique on a given table for both SAP Sybase IQ and Adaptive Server

Enterprise.

Permissions

Requires CREATE privilege on the dbspace where the index is being created. Also requires

one of::

• CREATE ANY INDEX system privilege.

• CREATE ANY OBJECT system privilege.

• REFERENCE privilege on the underlying table of the index.

• You own the underlying table of the index.

See also

•

BEGIN PARALLEL IQ … END PARALLEL IQ Statement

on page 87

•

DROP Statement

on page 255

•

INDEX_PREFERENCE Option

on page 557

•

FROM Clause

on page 295

CREATE LDAP SERVER Statement

Creates a new LDAP server configuration object for LDAP user authentication. Parameters

defined during the creation of an LDAP server configuration object are stored in the

ISYSLDAPSERVER (system view SYSLDAPSERVER) system table.

Syntax

CREATE LDAP SERVER ldapua-server-name

[ ldapua-server-attribs ]

[ WITH ACTIVATE ]

ldapua-server-attribs:

SEARCH DN

URL { ‘URL_string’ | NULL }

| ACCESS ACCOUNT { ‘DN_string’ | NULL }

| IDENTIFIED BY ( ‘password’ | NULL }

| IDENTIFIED BY ENCRYPTED { encrypted-password | NULL }

| AUTHENTICATION URL { ‘URL_string’ | NULL }

| CONNECTION TIMEOUT timeout_value

| CONNECTION RETRIES retry_value

SQL Statements

150 SAP Sybase IQ

| TLS { ON | OFF }

Parameters

•

URL – identifies the host (by name or by IP address), port number, and the search to be

performed for the DN lookup for a given user ID. This value is validated for correct LDAP

URL syntax before it is stored in the ISYSLDAPSERVER system table. The maximum

size for this string is 1024 bytes.

•

ACCESS ACCOUNT – user created in the LDAP server for use by SAP Sybase IQ, not a

user within SAP Sybase IQ. The distinguished name (DN) for this user is used to connect

to the LDAP server. This user has permissions within the LDAP server to search for DNs

by user ID in the locations specified by the SEARCH DN URL. The maximum size for this

string is 1024 bytes.

•

IDENTIFIED BY – provides the password associated with the ACCESS ACCOUNT

user. The password is stored using symmetric encryption on disk. Use the value NULL to

clear the password and set it to none. The maximum size of a clear text password is 255

bytes.

•

IDENTIFIED BY ENCRYPTED – configures the password associated with the

ACCESS ACCOUNT distinguished name in an encrypted format. The binary value is the

encrypted password and is stored on disk as is. Use the value NULL to clear the password

and set it to none. The maximum size of the binary is 289 bytes. The encrypted key should

be a valid varbinary value. Do not enclose the encrypted key in quotation marks.

•

AUTHENTICATION URL – identifies the host (by name or IP address) and the port

number of the LDAP server to use for authentication of the user. This is the value defined

for URL_string and is validated for correct LDAP URL syntax before it is stored in

ISYSLDAPSERVER system table. The DN of the user obtained from a prior DN search

and the user password bind a new connection to the authentication URL. A successful

connection to the LDAP server is considered proof of the identity of the connecting user.

The maximum size for this string is 1024 bytes.

•

CONNECTION TIMEOUT – specifies the connection timeout from SAP Sybase IQ to

the LDAP server for both DN searches and authentication. This value is in milliseconds,

with a default value of 10 seconds.

•

CONNECTION RETRIES – specifies the number of retries on connections from SAP

Sybase IQ to the LDAP server for both DN searches and authentication. The valid range of

values is 1– 60, with a default value of 3.

•

TLS – defines whether the TLS or Secure LDAP protocol is used for connections to the

LDAP server for both DN searches and authentication. When set to ON, the TLS protocol

is used and the URL would being with "ldap://" When set to OFF (or not specified), Secure

LDAP protocol is used and the URL begins with “ldaps://”. When using the TLS protocol,

specify the database security option TRUSTED_CERTIFICATES_FILE with a file name

SQL Statements

Reference: Statements and Options 151

containing the certificate of the Certificate Authority (CA) that signed the certificate used

by the LDAP server.

•

WITH ACTIVATE – activates the LDAP server configuration object for immediate use

upon creation. This permits the definition and activation of LDAP User Authentication in

one statement. The LDAP server configuration object state changes to READY when

WITH ACTIVATE is used.

Examples

•

Example 1 – sets the search parameters, the authentication URL, and sets a three second

timeout, and activates the server so it can begin authenticating users. It connects to the

LDAP server without TLS or SECURE LDAP protocols.

SET OPTION PUBLIC.login_mode = ‘Standard,LDAPUA’

CREATE LDAP SERVER apps_primary

SEARCH DN

URL 'ldap://my_LDAPserver:389/dc=MyCompany,dc=com??sub?cn=*'

ACCESS ACCOUNT 'cn=aseadmin, cn=Users, dc=mycompany, dc=com'

IDENTIFIED BY 'Secret99Password'

AUTHENTICATION URL 'ldap://my_LDAPserver:389/'

CONNECTION TIMEOUT 3000

WITH ACTIVATE

•

Example 2 – uses the same search parameters as example 1, but specifies “ldaps” so that a

Secure LDAP connection is established with the LDAP server on host my_LDAPserver,

port 636. Only LDAP clients using the Secure LDAP protocol may now connect on this

port. The database security option TRUSTED_CERTIFICATE_FILE must be set with a

file name containing the certificate of the certificate authority (CA) that signed the

certificate used by the LDAP server at "ldaps://my_LDAPserver:636". During the

handshake with the LDAP server, the certificate presented by the LDAP server is checked

by the SAP Sybase IQ server (the LDAP client) to ensure that it is signed by one of the

certificates listed in the file. This establishes trust by the client that the server is who it says

it is. The ACCESS ACCOUNT and IDENTIFIED BY parameters establish trust by the

LDAP server that the client is who it says it is.

Note: The TLS parameter must be OFF when Secure LDAP is used instead of TLS

protocol.

SET OPTION PUBLIC.login_mode = ‘Standard,LDAPUA’

SET OPTION PUBLIC.trusted_certificates_file = ‘/mycompany/shared/

trusted.txt’

CREATE LDAP SERVER secure_primary

SEARCH DN

URL 'ldaps://my_LDPAserver:636/dc=MyCompany,dc=com??sub?

cn=*'

ACCESS ACCOUNT 'cn=aseadmin, cn=Users, dc=mycompany, dc=com'

IDENTIFIED BY 'Secret99Password'

AUTHENTICATION URL 'ldaps://my_LDAPserver:636/'

CONNECTION TIMEOUT 3000

SQL Statements

152 SAP Sybase IQ

TLS OFF

WITH ACTIVATE

•

Example 3 – establishes the TLS protocol on port 389. It also requires database security

option TRUSTED_CERTIFICATE_FILE to be set with a file name and provides the same

type of security as example 2. In this example, the TLS protocol is ON to facilitate wider

support by LDAP server vendors.

Note: Check the requirements of all your LDAP servers when deciding how to configure

Secure LDAP or TLS for an SAP Sybase IQ server.

SET OPTION PUBLIC.login_mode = ‘Standard,LDAPUA’

SET OPTION PUBLIC.trusted_certificates_file = ‘/mycompany/shared/

trusted.txt’

CREATE LDAP SERVER tls_primary

SEARCH DN

URL 'ldap://my_LDAPserver:389/dc=MyCompany,dc=com??sub?cn=*'

ACCESS ACCOUNT 'cn=aseadmin, cn=Users, dc=mycompany, dc=com'

IDENTIFIED BY 'Secret99Password'

AUTHENTICATION URL 'ldap://my_LDAPserver:389/'

CONNECTION TIMEOUT 3000

TLS ON

WITH ACTIVATE

Standards

ANSI SQL – Compliance level: Transact-SQL extension.

Permissions

Requires the MANAGE ANY LDAP SERVER system privilege.

CREATE LOGICAL SERVER Statement

Creates a user-defined logical server. This statement enforces consistent shared system

temporary store settings across physical nodes shared by logical servers.

Syntax

CREATE LOGICAL SERVER logical-server-name [

{ ls-create-clause, ...} ] [ WITH STOP SERVER ]

ls-create-clause:

{ MEMBERSHIP ( { ls-member, ...} ) | POLICY ls-policy-name }

ls-member:

FOR LOGICAL COORDINATOR | mpx-server-name

SQL Statements

Reference: Statements and Options 153

Parameters

•

logical-server-name – any user-specified identifier except:

• ALL

• AUTO

• COORDINATOR

• DEFAULT

• NONE

• OPEN

• SERVER

•

MEMBERSHIP – to define a logical membership to the coordinator, include FOR

LOGICAL COORDINATOR in the MEMBERSHIP clause.

When no members are specified during the creation of a logical server, the logical server is

created empty.

Note: Implicit logical server membership definitions, such as those for OPEN and

SERVER logical servers, are not stored at all.

The SYS.ISYSLOGICALMEMBER system table stores definitions for the logical server

memberships.

Changing the ALLOW_COORDINATOR_AS_MEMBER option of the root logical server

policy from ON to OFF does not affect the membership information stored in the catalog.

Instead, it affects only the effective configuration of the logical server.

You can define a logical server membership to the current coordinator either by specifying

the multiplex server name or by using the FOR LOGICAL COORDINATOR clause, even

when ALLOW_COORDINATOR_AS_MEMBER option is set to OFF. Membership

definition is stored in the catalog, but is inactive while that multiplex server acts as the

coordinator.

The catalog stores the logical server and its membership definitions.

•

POLICY – associates a logical server with a user-defined logical server policy. If no

POLICY clause is specified, the logical server is associated with the root policy.

The SYS.ISYSIQLOGICALSERVER system table stores information about the logical

server policy for a corresponding logical server.

•

ls-policy-name – any user-specified identifier except ROOT.

•

WITH STOP SERVER – automatically shuts down all servers in the logical server when

the TEMP_DATA_IN_SHARED_TEMP option is changed directly or indirectly.

Applies to

Multiplex only.

SQL Statements

154 SAP Sybase IQ

Examples

•

Example 1 – creates a user-defined logical server

ls1

with three multiplex nodes as its

members:

CREATE LOGICAL SERVER ls1 MEMBERSHIP ( n1, n2, n3 )

•

Example 2 – creates a user-defined logical server

ls1

with three member nodes, and

defines the logical server policy name

lsp1

CREATE LOGICAL SERVER ls1 MEMBERSHIP ( w1_svr, w2_svr, r2_svr )

POLICY lsp1

•

Example 3 – creates servers as in Example 2, except that WITH STOP SERVER

automatically shuts down all servers in the logical server when the

TEMP_DATA_IN_SHARED_TEMP option is changed directly or indirectly:

CREATE LOGICAL SERVER ls1 MEMBERSHIP ( w1_svr, w2_svr, r2_svr )

POLICY lsp1 WITH STOP SERVER

•

Example 4 – creates a user-defined logical server

ls1

with logical server policy

lspolicy1

and no member nodes:

CREATE LOGICAL SERVER ls1 POLICY lspolicy1

•

Example 5 – where

is the current coordinator, creates a logical server

ls2

with the

named membership of multiplex nodes

and

and logical membership of the

coordinator. Also sets the logical server policy of

ls2

lspolicy2

CREATE LOGICAL SERVER ls2 POLICY

MEMBERSHIP FOR LOGICAL COORDINATOR

lspolicy1, n1, n2, n3 POLICY lspolicy2

Permissions

Requires the MANAGE MULTIPLEX system privilege.

CREATE LOGIN POLICY Statement

Creates a login policy in the database.

Syntax

CREATE LOGIN POLICY policy-name policy-option

policy-option:

policy-option-name = policy-option-value

policy-option-value:

{ UNLIMITED | DEFAULT | value }

policy-option-name:

AUTO_UNLOCK_TIME

| CHANGE_PASSWORD_DUAL_CONTROL

SQL Statements

Reference: Statements and Options 155

| DEFAULT_LOGICAL_SERVER

| LOCKED

| MAX_CONNECTIONS

| MAX_DAYS_SINCE_LOGIN

| MAX_FAILED_LOGIN_ATTEMPTS

| MAX_NON_DBA_CONNECTIONS

| PASSWORD_EXPIRY_ON_NEXT_LOGIN

| PASSWORD_GRACE_TIME

| PASSWORD_LIFE_TIME

| ROOT_AUTO_UNLOCK_TIME

| LDAP_PRIMARY_SERVER

| LDAP_SECONDARY_SERVER

| LDAP_AUTO_FAILBACK_PERIOD

| LDAP_FAILOVER_TO_STD

| LDAP_REFRESH_DN

Parameters

•

policy-name – the name of the login policy. Specify root to modify the root login policy.

•

policy-option-name – the name of the policy option. See

and

LDAP

for details on each option.

•

policy-option-value – the value assigned to the login policy option. If you specify

UNLIMITED, no limits are used. If you specify DEFAULT, the default limits are used. See

and

LDAP Login Policy Options

for supported values for each

option.

Applies to

Simplex and multiplex.

Examples

•

Example 1 – creates the Test1 login policy. This login policy has an unlimited password

life and allows the user a maximum of five attempts to enter a correct password before the

account is locked.

CREATE LOGIN POLICY Test1

password_life_time=UNLIMITED

max_failed_login_attempts=5;

Usage

If you do not specify a policy option, values for this login policy are taken from the root login

policy. New policies do not inherit the MAX_NON_DBA_CONNECTIONS and

ROOT_AUTO_UNLOCK_TIME policy options.

Permissions

Requires MANAGE ANY LOGIN POLICY system privilege.

SQL Statements

156 SAP Sybase IQ

The following system privileges can override the noted login policy options:

Exception System Privilege Login Policy Option

SERVER OPERATOR or DROP CONNEC-

TION system privilege

MAX_NON_DBA_CONNS

MAX_CONNECTIONS

MANAGE ANY USER system privilege LOCKED

MAX_DAYS_SINCE_LOGIN

Available options for root and user-defined login policies.

Option Description

AUTO_UN-

LOCK_TIME

The time period after which locked accounts not granted the MANAGE

ANY USER system privilege are automatically unlocked. This option can

be defined in any login policy, including the root login policy.

•

Values – 0 – UNLIMITED

•

Default – UNLIMITED

•

Applies to – All users not granted the MANAGE ANY USER system

privilege.

CHANGE_PASS-

WORD_DUAL_CON-

TROL

Requires input from two users, each granted the CHANGE PASSWORD

system privilege, to change the password of another user.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users.

SQL Statements

Reference: Statements and Options 157

Option Description

DEFAULT_LOGI-

CAL_SERVER

If the connection string specifies no logical server, the user connects to the

DEFAULT_LOGICAL_SERVER option specified in the user's login pol-

icy.

•

Values –

• Name of an existing user-defined logical server

• ALL – allows access to all logical servers.

• AUTO – value of the default logical server in the root login policy.

• COORDINATOR – the current coordinator node.

• NONE – denies access to any multiplex server.

• OPEN – use alone or with the name of a user-defined logical server.

Allows access to all multiplex nodes that are not members of any

user-defined logical servers.

• SERVER – allows access to all of the multiplex nodes, subject to

the semantics of the SERVER logical server.

•

Default – AUTO

•

Applies to – All users. Requires MANAGE MULTIPLEX system

privilege.

LOCKED If set ON, users cannot establish new connections. This setting temporarily

denies access to login policy users. Logical server overrides for this option

are not allowed.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users except those with the MANAGE ANY USER

system privilege.

MAX_CONNEC-

TIONS

The maximum number of concurrent connections allowed for a user. You

can specify a per-logical-server setting for this option.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the SERVER OPERATOR or

DROP CONNECTION system privilege.

SQL Statements

158 SAP Sybase IQ

Option Description

MAX_DAYS_SINCE_

The maximum number of days that can elapse between two successive

logins by the same user.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the MANAGE ANY USER

system privilege.

MAX_FAILED_LOG-

IN_ATTEMPTS

The maximum number of failed attempts, since the last successful attempt,

to log into the user account before the account is locked.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users.

MAX_NON_DBA_C

ONNECTIONS

The maximum number of concurrent connections that a user without

SERVER OPERATOR or DROP CONNECTION system privileges can

make. This option is supported only in the root login policy.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users except those with the SERVER OPERATOR or

DROP CONNECTION privilege.

PASSWORD_EXPI-

RY_ON_NEXT_LOG-

If set ON, the user's password expires at the next login.

•

Values – ON, OFF

•

Default – OFF

•

Applies to – All users.

Note: This functionality is not currently implemented when logging in to

Sybase Control Center. A user will not be prompted to change their pass-

word. He or she will be prompted, however, when logging in to SAP Sybase

IQ outside of Sybase Control Center (for example, using Interactive SQL).

PASS-

WORD_GRACE_TIM

The number of days before password expiration during which login is

allowed but the default post_login procedure issues warnings.

•

Values – 0 – 2147483647

•

Default – 0

•

Applies to – All users.

SQL Statements

Reference: Statements and Options 159

Option Description

PASS-

WORD_LIFE_TIME

The maximum number of days before a password must be changed.

•

Values – 0 – 2147483647

•

Default – UNLIMITED

•

Applies to – All users.

ROOT_AUTO_UN-

LOCK_TIME

The time period after which locked accounts granted the MANAGE ANY

USER system privilege are automatically unlocked. This option can be

defined only in the root login policy.

•

Values – 0 – UNLIMITED

•

Default – 15

•

Applies to – All users granted the MANAGE ANY USER system

privilege.

LDAP Login Policy Options

Available login policy options for LDAP user authentication

Option Description

LDAP_PRI-

MARY_SERV-

Specifies the name of the primary LDAP server.

•

Values – n/a

•

Default – None

•

Applies to – All users.

LDAP_SECON-

DARY_SERV-

Specifies the name of the secondary LDAP server.

•

Values – n/a

•

Default – None

•

Applies to – All users.

LDAP_AU-

TO_FAIL-

BACK_PERIOD

Specifies the time period, in minutes, after which automatic failback to the pri-

mary server is attempted.

•

Values – 0 - 2147483647

•

Default – 15 minutes

•

Applies to – All users.

SQL Statements

160 SAP Sybase IQ

Option Description

LDAP_FAIL-

OVER_TO_STD

Permits authentication with standard authentication when authentication with the

LDAP server fails due to system resources, network outage, connection timeouts,

or similar system failures. However, it does not permit an actual authentication

failure returned from an LDAP server to fail over to standard authentication.

•

Values – ON, OFF

•

Default – ON

•

Applies to – All users.

LDAP_RE-

FRESH_DN

Updates the ldap_refresh_dn value in the ISYSLOGINPOLICYOPTION

system table with the current time, stored in Coordinated Universal Time (UTC).

Each time a user authenticates with LDAP, if the value of ldap_refresh_dn in

ISYSLOGINPOLICYOPTION is more recent than the value of user_dn in

ISYSUSER, a search for a new user DN occurs. The user_dn value is then

updated with the new user DN and the user_dn_changed_at value is again updated

to the current time.

•

Values – NOW

•

Initial value for ROOT policy – NULL

•

Initial value for user-defined login policy – Current time stored in UTC

•

Applies to – All users.

Multiplex Login Policy Configuration

Configure login policies for multiplex servers.

Example

This example overrides the login policy settings on a logical server, increasing the maximum

number of connections on logical server ls1:

ALTER LOGIN POLICY lp1 max_connections=20 LOGICAL SERVER ls1;

Usage

Applies only to multiplex.

Any login management commands you execute on any multiplex server automatically

propagate to all servers in the multiplex. For best performance, execute these commands, or

any DDL, on the coordinator.

An override at the logical server level override means that a particular login policy option has

different settings for different logical servers. SYS.ISYSIQLSLOGINPOLICYOPTION

stores login policy option values for logical-server override. For each logical-server override

SQL Statements

Reference: Statements and Options 161

of a login policy option, a corresponding row exists in

ISYSIQLSLOGINPOLICYOPTION.

CREATE LS POLICY Statement

Creates a user-defined logical server policy. This statement enforces consistent shared system

temporary store settings across physical nodes shared by logical servers.

Syntax

CREATE LS POLICY ls-policy-name ls-option-value-list [ WITH STOP

SERVER ]

ls-option-value-list:

{ ls-option-name = ls-policy-option-value } ...

ls-option-name:

ALLOW_COORDINATOR_AS_MEMBER

| DQP_ENABLED

| LOGIN_REDIRECTION

| REDIRECTION_WAITERS_THRESHOLD

| TEMP_DATA_IN_SHARED_TEMP

Parameters

•

ls-policy-name – the name of the logical server policy. You can specify any identifier

except root for the policy name.

•

ls-option-value-list – the name of the logical server policy option. See

LS Policy Options

for details on each option.

•

ls-policy-option-value – any unspecified option inherits its value from the root logical

server policy. See

LS Policy Options

for supported values for each option

•

WITH STOP SERVER – automatically shuts down all servers in the logical server when

the TEMP_DATA_IN_SHARED_TEMP option is changed directly or indirectly.

Applies to

Multiplex only.

Examples

•

Example 1 – creates a user-defined logical server policy named

lspolicy1

CREATE LS POLICY lspolicy1

ALLOW_COORDINATOR_AS_MEMBER=ON;

SQL Statements

162 SAP Sybase IQ

Usage

If you want a smaller IQ_SYSTEM_TEMP dbspace, set

TEMP_DATA_IN_SHARED_TEMP to ON, which writes temporary data to

IQ_SHARED_TEMP instead of IQ_SYSTEM_TEMP. In a distributed query processing

environment, however, setting both DQP_ENABLED and

TEMP_DATA_IN_SHARED_TEMP to ON may saturate your SAN with additional data in

IQ_SHARED_TEMP, where additional I/O operations against IQ_SHARED_TEMP may

adversely affect DQP performance.

Standards

• SQL – vendor extension to ISO/ANSI SQL grammar.

• Sybase – not supported by Adaptive Server Enterprise.

Permissions

Requires the MANAGE MULTIPLEX system privilege.

CREATE MESSAGE Statement [T-SQL]

Adds a user-defined message to the SYSUSERMESSAGES system table for use by PRINT and

RAISERROR statements.

Syntax

CREATE MESSAGE message-number

... AS 'message-text'

Parameters

•

message_number – the message number of the message to add. The message number for

a user-defined message must be 20000 or greater.

•

message_text – he text of the message to add. The maximum length is 255 bytes. PRINT

and RAISERROR recognize placeholders in the message text to print out. A single message

can contain up to 20 unique placeholders in any order. These placeholders are replaced

with the formatted contents of any arguments that follow the message when the text of the

message is sent to the client.

Placeholders are numbered to allow reordering of the arguments when translating a

message to a language with a different grammatical structure. A placeholder for an

argument appears as “%nn!”—a percent sign (%), followed by an integer from 1 to 20,

followed by an exclamation mark (!)—where the integer represents the position of the

argument in the argument list, “%1!” is the first argument, “%2!” is the second argument,

and so on.

SQL Statements

Reference: Statements and Options 163

Usage

CREATE MESSAGE associates a message number with a message string. The message

number can be used in PRINT and RAISERROR statements.

There is no parameter corresponding to the

language

argument for sp_addmessage.

Side Effects

• Automatic commit

Standards

• SQL—Vendor extension to ISO/ANSI SQL grammar.

• Sybase—The functionality of CREATE MESSAGE is provided by the sp_addmessage

procedure in Adaptive Server Enterprise.

Permissions

Requires one of:

• CREATE MESSAGE system privilege.

• CREATE ANY OBJECT system privilege.

See also

•

PRINT Statement [T-SQL]

on page 378

•

RAISERROR Statement [T-SQL]

on page 381

CREATE MULTIPLEX SERVER Statement

Creates a multiplex server.

Syntax

CREATE MULTIPLEX SERVER server-name DATABASE

'dbfile' host-port list [ ROLE { READER | WRITER } ]

[ STATUS | { INCLUDED | EXCLUDED } ]

host-port-list:

{[ PRIVATE ] HOST ' hostname ' PORT port number }

Parameters

•

PRIVATE – specifies that the particular HOST PORT pair is for private interconnection.

A separate private interconnection for multiplex interprocess communication (MIPC)

enables highly available and high-performance network configurations. SAP Sybase IQ

SQL Statements

164 SAP Sybase IQ

automatically opens private ports; you need not list them in the host-port-list used to start

the server. All public and private ports require unique port numbers to avoid conflicts.

•

server-name – the name of the multiplex server based on the rules for server startup option

-n.

•

ROLE – default if not specified is READER.

•

STATUS – default if not specified is INCLUDED.

Applies to

Multiplex only.

Usage

If you plan to use UNIX soft (symbolic) links for server paths, create the soft link before you

run

CREATE MULTIPLEX SERVER

. When you start the new server, the database file path must

match the database file path specified when creating that server.

When creating the initial multiplex server, both coordinator node and secondary node rows are

added to SYS.ISYSIQMPXSERVER. The transaction log records this operation as two

separate

CREATE MULTIPLEX SERVER

commands, one for the coordinator node and one for

the secondary node.

After creating the first secondary node, the coordinator shuts down automatically.

The SYS.ISYSIQMPXSERVER system table stores the HOST hostname PORT portname

pairs in its connection_info string as host:port[;host:port…].

Note: Use multiple host:port pairs if the computer the multiplex server is running on has

multiple redundant network cards mapped to different network addresses.

You may specify the clauses DATABASE, host-port list, ROLE and STATUS in any order.

When you add a server, the coordinator must be running, but you can run the CREATE

MULTIPLEX SERVER command from any server in the multiplex.

This statement is automatically committed.

Permissions

Requires the MANAGE MULTIPLEX system privilege.

CREATE PROCEDURE Statement

Creates a new user-defined SQL procedure in the database.

To create external procedure interfaces, see

CREATE PROCEDURE Statement (External

Procedures)

SQL Statements

Reference: Statements and Options 165

Syntax

CREATE [ OR REPLACE | TEMPORARY ] PROCEDURE [ owner.]procedure-name

( [ parameter, …] ) {

[ SQL SECURITY { INVOKER | DEFINER } ]

[ RESULT ( result-column, …) | NO RESULT SET ]

[ ON EXCEPTION RESUME ] compound statement | AT location-string

parameter:

parameter_mode parameter-name data-type [ DEFAULT expression ] |

SQLCODE | SQLSTATE

parameter_mode:

IN | OUT | INOUT

result-column:

column-name data-type

Parameters

•

parameter-name – parameter names must conform to the rules for other database

identifiers, such as column names, and must be a valid SQL data type. The keywords have

the following meanings:

Parameters can be prefixed by one of the keywords IN, OUT or INOUT. If no keyword is

specified, parameters are INOUT by default. The keywords have the following meanings:

•

IN – parameter is an expression that provides a value to the procedure.

•

OUT – parameter is a variable that could be given a value by the procedure.

•

INOUT – parameter is a variable that provides a value to the procedure, and could be

given a new value by the procedure.

•

SQLSTATE and SQLCODE – special parameters that output the SQLSTATE or

SQLCODE value when the procedure ends (they are OUT parameters). Whether or not a

SQLSTATE and SQLCODE parameter is specified, the SQLSTATE and SQLCODE

special values can always be checked immediately after a procedure call to test the return

status of the procedure.

The SQLSTATE and SQLCODE special values are modified by the next SQL statement.

Providing SQLSTATE or SQLCODE as procedure arguments allows the return code to be

stored in a variable.

•

CREATE – creates a new procedure.

•

OR REPLACE – replaces an existing procedure with the same name. This clause changes

the definition of the procedure, but preserves existing permissions.

You cannot use the OR REPLACE clause with temporary procedures. Also, an error is

returned if the procedure being replaced is already in use.

•

TEMPORARY – the stored procedure is visible only by the connection that created it, and

that it is automatically dropped when the connection is dropped. You can also explicitly

SQL Statements

166 SAP Sybase IQ

drop temporary stored procedures. You cannot perform ALTER, GRANT, or REVOKE on

them, and, unlike other stored procedures, temporary stored procedures are not recorded in

the catalog or transaction log.

Temporary procedures execute with the permissions of their creator (current user), or

specified owner. You can specify an owner for a temporary procedure when:

• The temporary procedure is created within a permanent stored procedure

• The temporary and permanent procedure both have the same owner

To drop the owner of a temporary procedure, drop the temporary procedure first.

You can create and drop temporary stored procedures when you are connected to a read-

only database; they cannot be external procedures.

For example, the following temporary procedure drops the table called CustRank, if it

exists. For this example, the procedure assumes that the table name is unique and can be

referenced by the procedure creator without specifying the table owner:

CREATE TEMPORARY PROCEDURE drop_table( IN @TableName char(128) )

BEGIN

IF EXISTS ( SELECT 1 FROM SYS.SYSTAB WHERE

table_name = @TableName )

THEN EXECUTE IMMEDIATE

'DROP TABLE "' || @TableName || '"';

MESSAGE 'Table "' || @TableName ||

'" dropped' to client;

END IF;

END;

CALL drop_table( 'CustRank' )

•

RESULT – declares the number and type of columns in the result set. The parenthesized

list following the RESULT keyword defines the result column names and types. This

information is returned by the Embedded SQL DESCRIBE or by ODBC SQLDescribeCol

when a CALL statement is being described. Allowed data types are listed in

Reference:

Building Blocks, Tables, and Procedures > SQL Data Types

Some procedures can produce more than one result set, depending on how they are

executed. For example, this procedure returns two columns under some circumstances,

and one in others.

CREATE PROCEDURE names( IN formal char(1))

BEGIN

IF formal = 'n' THEN

SELECT GivenName

FROM Employees

ELSE

SELECT Surname,GivenName

FROM Employees

END IF

END

Procedures with variable result sets must be written without a RESULT clause, or in

Transact-SQL. Their use is subject to these limitations:

SQL Statements

Reference: Statements and Options 167

•

Embedded SQL – you must DESCRIBE the procedure call after the cursor for the

result set is opened, but before any rows are returned, in order to get the proper shape of

result set. The CURSOR

cursor-name

clause on the DESCRIBE statement is required.

•

ODBC, OLE DB, ADO.NET – variable result-set procedures can be used by ODBC

applications. The proper description of the result sets is carried out by the driver or

provider.

•

Open Client applications – variable result-set procedures can be used by Open Client

applications.

If your procedure returns only one result set, use a RESULT clause. The presence of this

clause prevents ODBC and Open Client applications from describing the result set again

after a cursor is open.

To handle multiple result sets, ODBC must describe the currently executing cursor, not the

procedure’s defined result set. Therefore, ODBC does not always describe column names

as defined in the RESULT clause of the procedure definition. To avoid this problem, use

column aliases in the SELECT statement that generates the result set.

•

NO RESULT SET – declares that this procedure returns no result set. This is useful when

an external environment needs to know that a procedure does not return a result set.

•

SQL SECURITY – defines whether the procedure is executed as the INVOKER (the user

who is calling the procedure), or as the DEFINER (the user who owns the procedure). The

default is DEFINER.

Extra memory is used when you specify SQL SECURITY INVOKER, because annotation

must be done for each user that calls the procedure. Also, name resolution is performed as

the invoker as well. Therefore, qualify all object names (tables, procedures, and so on) with

their appropriate owner. For example, suppose user1 creates this procedure:

CREATE PROCEDURE user1.myProcedure()

RESULT( columnA INT )

SQL SECURITY INVOKER

BEGIN

SELECT columnA FROM table1;

END;

If user2 attempts to run this procedure and a table user2.table1 does not exist, a

table lookup error results. Additionally, if a user2.table1 does exist, that table is used

instead of the intended user1.table1. To prevent this situation, qualify the table

reference in the statement (user1.table1, instead of just table1).

•

ON EXCEPTION RESUME – the procedure takes an action that depends on the setting of

the ON_TSQL_ERROR option. If ON_TSQL_ERROR option is set to CONDITIONAL

(which is the default) the execution continues if the next statement handles the error;

otherwise, it exits.

Error-handling statements include:

SQL Statements

168 SAP Sybase IQ

• IF

• SELECT @variable =

• CASE

• LOOP

• LEAVE

• CONTINUE

• CALL

• EXECUTE

• SIGNAL

• RESIGNAL

• DECLARE

•

SET VARIABLE

Do not use explicit error-handling code with an ON EXCEPTION RESUME clause.

See

ON_TSQL_ERROR Option [TSQL]

•

AT location-string – creates a

proxy stored procedure

on the current database for a remote

procedure specified by

location-string

. The AT clause supports the semicolon (;) as a field

delimiter in

location-string

. If no semicolon is present, a period is the field delimiter. This

allows file names and extensions to be used in the database and owner fields.

Examples

•

Example 1 – uses a case statement to classify the results of a query:

CREATE PROCEDURE ProductType (IN product_id INT, OUT type

CHAR(10))

BEGIN

DECLARE prod_name CHAR(20) ;

SELECT name INTO prod_name FROM "GROUPO"."Products"

WHERE ID = product_id;

CASE prod_name

WHEN 'Tee Shirt' THEN

SET type = 'Shirt'

WHEN 'Sweatshirt' THEN

SET type = 'Shirt'

WHEN 'Baseball Cap' THEN

SET type = 'Hat'

WHEN 'Visor' THEN

SET type = 'Hat'

WHEN 'Shorts' THEN

SET type = 'Shorts'

ELSE

SET type = 'UNKNOWN'

END CASE ;

END

•

Example 2 – uses a cursor and loop over the rows of the cursor to return a single value:

CREATE PROCEDURE TopCustomer (OUT TopCompany CHAR(35), OUT

TopValue INT)

SQL Statements

Reference: Statements and Options 169

BEGIN

DECLARE err_notfound EXCEPTION

FOR SQLSTATE '02000' ;

DECLARE curThisCust CURSOR FOR

SELECT CompanyName, CAST( sum(SalesOrderItems.Quantity *

Products.UnitPrice) AS INTEGER) VALUE

FROM Customers

LEFT OUTER JOIN SalesOrders

LEFT OUTER JOIN SalesorderItems

LEFT OUTER JOIN Products

GROUP BY CompanyName ;

DECLARE ThisValue INT ;

DECLARE ThisCompany CHAR(35) ;

SET TopValue = 0 ;

OPEN curThisCust ;

CustomerLoop:

LOOP

FETCH NEXT curThisCust

INTO ThisCompany, ThisValue ;

IF SQLSTATE = err_notfound THEN

LEAVE CustomerLoop ;

END IF ;

IF ThisValue > TopValue THEN

SET TopValue = ThisValue ;

SET TopCompany = ThisCompany ;

END IF ;

END LOOP CustomerLoop ;

CLOSE curThisCust ;

END

Usage

CREATE PROCEDURE creates a procedure in the database. A procedure is invoked with a

CALL statement. You can create permanent or temporary (TEMPORARY) stored procedures.

You can use PROC as a synonym for PROCEDURE.

Note: There are two ways to create stored procedures: ISO/ANSI SQL and T-SQL. BEGIN

TRANSACTION, for example, is T-SQL-specific when using CREATE PROCEDURE syntax.

Do not mix syntax when creating stored procedures. See

CREATE PROCEDURE Statement

[T-SQL]

When procedures are executed using CALL, not all parameters need to be specified. If a default

value is provided in the CREATE PROCEDURE statement, missing parameters are assigned

the default values. If an argument is not provided in the CALL statement, and no default is set,

an error is given.

Remote procedures can return only up to 254 characters in output variables.

If a remote procedure can return a result set, even if it does not return one in all cases, then the

local procedure definition must contain a RESULT clause.

For information on remote servers, see

CREATE SERVER Statement

SQL Statements

170 SAP Sybase IQ

Side Effects

• Automatic commit

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—The Transact-SQL CREATE PROCEDURE statement is different.

• SQLJ—The syntax extensions for Java result sets are as specified in the proposed SQLJ1

standard.

Permissions

Watcom SQL or Transact SQL procedure to be owned by self – Requires CREATE

PROCEDURE system privilege.

Watcom SQL or Transact SQL procedure to be owned by any user – Requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

Remote procedure to be owned by self – Requires all of:

• CREATE EXTERNAL REFERENCE system privilege.

• CREATE PROCEDURE system privilege.

Remote procedure to be owned by any user – Requires CREATE EXTERNAL REFERENCE

system privilege. Also requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

See also

•

Referencing Temporary Tables Within Procedures

on page 172

•

BEGIN … END Statement

on page 84

•

CALL Statement

on page 90

•

CREATE PROCEDURE Statement [T-SQL]

on page 172

•

CREATE PROCEDURE Statement (External Procedures)

on page 175

•

CREATE SERVER Statement

on page 192

•

DROP Statement

on page 255

•

EXECUTE IMMEDIATE Statement [ESQL] [SP]

on page 279

•

GRANT EXECUTE Statement

on page 310

•

RAISERROR Statement [T-SQL]

on page 381

•

ON_TSQL_ERROR Option [TSQL]

on page 598

SQL Statements

Reference: Statements and Options 171

Referencing Temporary Tables Within Procedures

Sharing a temporary table between procedures can cause problems if the table definitions are

inconsistent.

For example, suppose you have two procedures procA and procB, both of which define a

temporary table, temp_table, and call another procedure called sharedProc. Neither

procA nor procB has been called yet, so the temporary table does not yet exist.

Now, suppose that the procA definition for temp_table is slightly different than the

definition in procB—while both used the same column names and types, the column order is

different.

When you call procA, it returns the expected result. However, when you call procB, it

returns a different result.

This is because when procA was called, it created temp_table, and then called

sharedProc. When sharedProc was called, the

SELECT

statement inside of it was

parsed and validated, and then a parsed representation of the statement is cached so that it can

be used again when another

SELECT

statement is executed. The cached version reflects the

column ordering from the table definition in procA.

Calling procB causes the temp_table to be recreated, but with different column ordering.

When procB calls sharedProc, the database server uses the cached representation of the

SELECT statement. So, the results are different.

You can avoid this from happening by doing one of the following:

• ensure that temporary tables used in this way are defined consistently

• consider using a global temporary table instead

CREATE PROCEDURE Statement [T-SQL]

Creates a new procedure that is compatible with Adaptive Server Enterprise.

Syntax

This subset of the Transact-SQL CREATE PROCEDURE statement is supported in SAP

Sybase IQ:

CREATE [ OR REPLACE ] PROCEDURE [ owner.]procedure_name

… [ [ ( ] @parameter_name data-type [ = default ] [ OUTPUT ] [ , … ]

[ ) ] ]

…[ WITH RECOMPILE ]

… AS

… statement-list

SQL Statements

172 SAP Sybase IQ

Parameters

•

CREATE – creates a new procedure.

•

OR REPLACE – replaces an existing procedure with the same name. This clause changes

the definition of the procedure, but preserves existing permissions.

Usage

Differences between Transact-SQL and SAP Sybase IQ SQL statements:

•

Variable names prefixed by @ – the “@” sign denotes a Transact-SQL variable name;

SAP Sybase IQ variables can be any valid identifier and the @ prefix is optional.

•

Input and output parameters – SAP Sybase IQ procedure parameters are specified as

IN, OUT, or INOUT; Transact-SQL procedure parameters are INPUT parameters by

default or can be specified as OUTPUT. Those parameters declared as INOUT or as OUT

in SAP Sybase IQ should be declared with OUTPUT in Transact-SQL.

•

Parameter default values – SAP Sybase IQ procedure parameters are given a default

value using the keyword DEFAULT; Transact-SQL uses an equality sign (=) to provide the

default value.

•

Returning result sets – SAP Sybase IQ uses a RESULT clause to specify returned result

sets. In Transact-SQL procedures, the column names or alias names of the first query are

returned to the calling environment:

CREATE PROCEDURE showdept @deptname varchar(30)

SELECT Employees.Surname, Employees.givenName

FROM Departments, Employees

WHERE Departments.DepartmentName = @deptname

AND Departments.DepartmentID =

Employees.DepartmentID

The corresponding SAP Sybase IQ procedure:

CREATE PROCEDURE showdept(in deptname

varchar(30) )

RESULT ( lastname char(20), firstname char(20))

ON EXCEPTION RESUME

BEGIN

SELECT Employees.SurName, Employees.GivenName

FROM Departments, Employees

WHERE Departments.DepartmentName = deptname

AND Departments.DepartmentID =

Employees.DepartmentID

END

•

Procedure body – the body of a Transact-SQL procedure is a list of Transact-SQL

statements prefixed by the AS keyword. The body of an SAP Sybase IQ procedure is a

compound statement, bracketed by BEGIN and END keywords.

SQL Statements

Reference: Statements and Options 173

Note: There are two ways to create stored procedures: T-SQL and SQL/92. BEGIN

TRANSACTION, for example, is T-SQL specific when using CREATE PROCEDURE

syntax. Do not mix syntax when creating stored procedures.

Side Effects

• Automatic commit

Standards

• SQL—Transact-SQL extension to ISO/ANSI SQL grammar.

• Sybase—SAP Sybase IQ supports a subset of the Adaptive Server Enterprise CREATE

PROCEDURE statement syntax.

If the Transact-SQL WITH RECOMPILE optional clause is supplied, it is ignored. SQL

Anywhere always recompiles procedures the first time they are executed after a database is

started, and stores the compiled procedure until the database is stopped.

Groups of procedures are not supported.

Permissions

Watcom SQL or Transact SQL procedure to be owned by self – Requires CREATE

PROCEDURE system privilege.

Watcom SQL or Transact SQL procedure to be owned by any user – Requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

Remote procedure to be owned by self – Requires all of:

• CREATE EXTERNAL REFERENCE system privilege.

• CREATE PROCEDURE system privilege.

Remote procedure to be owned by any user – Requires CREATE EXTERNAL REFERENCE

system privilege. Also requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

See also

•

CREATE PROCEDURE Statement

on page 165

SQL Statements

174 SAP Sybase IQ

CREATE PROCEDURE Statement (External Procedures)

Creates an interface to a native or external procedure.

For CREATE PROCEDURE reference information for Java UDFs, see

CREATE

PROCEDURE Statement (Java UDF)

. For CREATE PROCEDURE reference information for

table UDFs, see

CREATE PROCEDURE Statement (Table UDF)

Syntax

CREATE[ OR REPLACE ] PROCEDURE [ owner.]procedure-name ( [ parameter,

…] )

[ SQL SECURITY { INVOKER | DEFINER } ]

[ RESULT ( result-column, …) | NO RESULT SET ]

[ DYNAMIC RESULT SETS integer-expression ]

[ EXTERNAL NAME ‘native-call’

| EXTERNAL NAME 'c-call' LANGUAGE { C_ESQL32 | C_ESQL64 | C_ODBC32

| C_ODBC64 }

| EXTERNAL NAME 'perl-call' LANGUAGE PERL

| EXTERNAL NAME 'php-call' LANGUAGE PHP

| EXTERNAL NAME 'java-call' LANGUAGE JAVA }

parameter:

parameter_mode parameter-name data-type [ DEFAULT expression ] |

SQLCODE | SQLSTATE

parameter_mode:

IN | OUT | INOUT

result-column:

column-name data-type

native-call:

[operating-system:]function-name@library

c-call:

[operating-system:]function-name@library; ...

perl-call:

<file=perl-file> $sa_perl_return = perl-subroutine( $sa_perl_arg0[, ... ] )

php-call:

<file=php-file> print php-func( $argv[1][, ... ] )

java-call:

[package-name.]class-name.method-name method-signature

operating-system:

Unix

method-signature:

( [ field-descriptor, ... ] ) return-descriptor

SQL Statements

Reference: Statements and Options 175

field-descriptor and return-descriptor:

{ Z

| B

| S

| I

| J

| F

| D

| C

| V

| [descriptor

| Lclass-name;

}

Parameters

•

CREATE – creates a new procedure.

•

OR REPLACE – replaces an existing procedure with the same name. This clause changes

the definition of the procedure, but preserves existing permissions.

•

parameter – parameter names must conform to the rules for other database identifiers,

such as column names, and must be a valid SQL data type. The keywords have the

following meanings:

Parameters can be prefixed by one of the keywords IN, OUT or INOUT. If no keyword is

specified, parameters are INOUT by default. The keywords have the following meanings:

•

IN – parameter is an expression that provides a value to the procedure.

•

OUT – parameter is a variable that could be given a value by the procedure.

•

INOUT – parameter is a variable that provides a value to the procedure, and could be

given a new value by the procedure.

Note: TABLE parameters cannot be declared as INOUT or OUT. See

CREATE

PROCEDURE Statement (Table UDF)

When procedures are executed using CALL, not all parameters need to be specified. If a

default value is provided in the CREATE PROCEDURE statement, missing parameters are

assigned the default values. If an argument is not provided in the CALL statement, and no

default is set, an error is given.

Note: You cannot CALL a table UDF. Use the CREATE PROCEDURE statement.

•

RESULT – declares the number and type of columns in the result set. The parenthesized

list following the RESULT keyword defines the result column names and types. This

information is returned by the Embedded SQL DESCRIBE or by ODBC SQLDescribeCol

when a CALL statement is being described. Allowed data types are listed in

Reference:

Building Blocks, Tables, and Procedures > SQL Data Types

SQL Statements

176 SAP Sybase IQ

Embedded SQL (LANGUAGE C_ESQL32, LANGUAGE C_ESQL64) or ODBC

(LANGUAGE C_ODBC32, LANGUAGE C_ODBC64) external procedures can return 0

or 1 result sets.

Perl or PHP (LANGUAGE PERL, LANGUAGE PHP) external procedures cannot return

result sets. Procedures that call native functions loaded by the database server cannot

return result sets.

CLR or Java (LANGUAGE CLR, LANGUAGE JAVA) external procedures can return 0,

1, or more result sets.

•

NO RESULT SET – declares that this procedure returns no result set. This is useful when

an external environment needs to know that a procedure does not return a result set.

•

DYNAMIC RESULT SETS – Use this clause with LANGUAGE CLR and LANGUAGE

JAVA calls. This clause is meaningful only if you specify LANGUAGE. If you specify a

RESULT clause, DYNAMIC RESULT SETS defaults to 1. If you do not specify a

RESULT clause, DYNAMIC RESULT SETS defaults to 0. Note that procedures that call

into Perl or PHP (LANGUAGE PERL, LANGUAGE PHP) external functions cannot

return result sets. Procedures that call native functions loaded by the database server

cannot return result sets.

The C_ESQL32, C_ESQL64, C_ODBC32, and C_ODBC64 external environments can

also return result sets (like CLR and JAVA), but they are restricted to only one dynamic

result set.

Procedures that call into Perl or PHP (LANGUAGE PERL, LANGUAGE PHP) external

functions cannot return result sets. Procedures that call native functions loaded by the

database server cannot return result sets.

•

SQL SECURITY – defines whether the procedure is executed as the INVOKER (the user

who is calling the procedure), or as the DEFINER (the user who owns the procedure). The

default is DEFINER. For external calls, this clause establishes the ownership context for

unqualified object references in the external environment.

Extra memory is used when you specify SQL SECURITY INVOKER, because annotation

must be done for each user that calls the procedure. Also, name resolution is performed as

the invoker as well. Therefore, qualify all object names (tables, procedures, and so on) with

their appropriate owner. For example, suppose user1 creates this procedure:

CREATE PROCEDURE user1.myProcedure()

RESULT( columnA INT )

SQL SECURITY INVOKER

BEGIN

SELECT columnA FROM table1;

END;

If user2 attempts to run this procedure and a table user2.table1 does not exist, a

table lookup error results. Additionally, if a user2.table1 does exist, that table is used

SQL Statements

Reference: Statements and Options 177

instead of the intended user1.table1. To prevent this situation, qualify the table

reference in the statement (user1.table1, instead of just table1).

•

EXTERNAL NAME – a procedure using the EXTERNAL NAME clause with no

LANGUAGE attribute defines an interface to a native function written in a programming

language such as C. The native function is loaded by the database server into its address

space.

The library name can include the file extension, which is typically .dll on Windows

and .so on UNIX. In the absence of the extension, the software appends the platform-

specific default file extension for libraries. This is a formal example:

CREATE PROCEDURE mystring( IN instr LONG VARCHAR )

EXTERNAL NAME

'[email protected];Unix:[email protected]';

A simpler way to write the preceding EXTERNAL NAME clause, using platform-specific

defaults:

CREATE PROCEDURE mystring( IN instr LONG VARCHAR )

EXTERNAL NAME 'mystring@mylib';

When called, the library containing the function is loaded into the address space of the

database server. The native function executes as part of the server. In this case, if the

function causes a fault, then the database server terminates. Because of this, loading and

executing functions in an external environment using the LANGUAGE attribute is

recommended. If a function causes a fault in an external environment, the database server

continues to run.

•

EXTERNAL NAME c-call LANGUAGE { C_ESQL32 | C_ESQL64 | C_ODBC32 |

C_ODBC64 } : – to call a compiled native C function in an external environment instead of

within the database server, the stored procedure or function is defined with the

EXTERNAL NAME clause followed by the LANGUAGE attribute specifying one of

C_ESQL32, C_ESQL64, C_ODBC32, or C_ODBC64.

When the LANGUAGE attribute is specified, then the library containing the function is

loaded by an external process and the external function will execute as part of that external

process. In this case, if the function causes a fault, then the database server will continue to

run.

The following is a sample procedure definition.

CREATE PROCEDURE ODBCinsert(

IN ProductName CHAR(30),

IN ProductDescription CHAR(50)

)

NO RESULT SET

EXTERNAL NAME '[email protected]'

LANGUAGE C_ODBC32;

•

EXTERNAL NAME perl-call LANGUAGE CLR – to call a Perl function in an external

environment, the procedure interface is defined with an EXTERNAL NAME clause

followed by the LANGUAGE PERL attribute.

SQL Statements

178 SAP Sybase IQ

A Perl stored procedure or function behaves the same as a SQL stored procedure or

function with the exception that the code for the procedure or function is written in Perl and

the execution of the procedure or function takes place outside the database server (that is,

within a Perl executable instance).

Sample procedure definition:

CREATE PROCEDURE PerlWriteToConsole( IN str LONG VARCHAR)

NO RESULT SET

EXTERNAL NAME '<file=PerlConsoleExample>

WriteToServerConsole( $sa_perl_arg0 )'

LANGUAGE PERL;

•

EXTERNAL NAME perl-call LANGUAGE PHP – to call a PHP function in an external

environment, the procedure interface is defined with an EXTERNAL NAME clause

followed by the LANGUAGE PHP attribute.

A PHP stored procedure or function behaves the same as a SQL stored procedure or

function with the exception that the code for the procedure or function is written in PHP

and the execution of the procedure or function takes place outside the database server (that

is, within a PHP executable instance).

Sample procedure definition:

CREATE PROCEDURE PHPPopulateTable()

NO RESULT SET

EXTERNAL NAME '<file=ServerSidePHPExample>

ServerSidePHPSub()'

LANGUAGE PHP;

•

EXTERNAL NAME java-call LANGUAGE JAVA – A Java method signature is a

compact character representation of the types of the parameters and the type of the return

value.

To call a Java method in an external environment, the procedure interface is defined with

an EXTERNAL NAME clause followed by the LANGUAGE JAVA attribute.

A Java-interfacing stored procedure or function behaves the same as a SQL stored

procedure or function with the exception that the code for the procedure or function is

written in Java and the execution of the procedure or function takes place outside the

database server (that is, within a Java Virtual Machine).

Sample procedure definition:

CREATE PROCEDURE HelloDemo( IN

name LONG VARCHAR )

NO RESULT SET

EXTERNAL NAME 'Hello.main([Ljava/lang/String;)V'

LANGUAGE JAVA;

The descriptors for arguments and return values from Java methods have the following

meanings:

SQL Statements

Reference: Statements and Options 179

Field Type Java Data Type

B byte

C char

D double

F float

I int

J long

class-name

; an instance of the

class-name

class. The class name must be fully

qualified, and any dot in the name must be replaced by a back-

slash. For example, java/lang/String

S short

V void

Z boolean

[ use one for each dimension of an array

For example:

double some_method(

boolean a,

int b,

java.math.BigDecimal c,

byte [][] d,

java.sql.ResultSet[] d ) {

}

has the signature:

'(ZILjava/math/BigDecimal;[[B[Ljava/sql/ResultSet;)D'

Usage

The body of a procedure consists of a compound statement. For information on compound

statements, see

BEGIN … END Statement

Note: There are two ways to create stored procedures: ISO/ANSI SQL and T-SQL. BEGIN

TRANSACTION, for example, is T-SQL specific when using CREATE PROCEDURE syntax.

Do not mix syntax when creating stored procedures. See

CREATE PROCEDURE Statement

[T-SQL]

If a stored procedure returns a result set, it cannot also set output parameters or return a return

value.

You cannot create TEMPORARY external call procedures.

SQL Statements

180 SAP Sybase IQ

When referencing a temporary table from multiple procedures, a potential issue can arise if the

temporary table definitions are inconsistent and statements referencing the table are cached.

You can create permanent stored procedures that call external or native procedures written in a

variety of programming languages. You can use PROC as a synonym for PROCEDURE.

Side Effects

• Automatic commit

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—The Transact-SQL CREATE PROCEDURE statement is different.

• SQLJ—The syntax extensions for Java result sets are as specified in the proposed SQLJ1

standard.

Permissions

External procedure to be owned by self – Requires:

• CREATE EXTERNAL REFERENCE system privilege.

• CREATE PROCEDURE system privilege.

External procedure to be owned by any user – Requires CREATE EXTERNAL REFERENCE

system privilege. Also requires one of:

• CREATE ANY PROCEDURE system privilege.

• CREATE ANY OBJECT system privilege.

See also

•

ALTER PROCEDURE Statement

on page 36

•

BEGIN … END Statement

on page 84

•

CALL Statement

on page 90

•

CREATE PROCEDURE Statement

on page 165

•

CREATE PROCEDURE Statement [T-SQL]

on page 172

•

DROP Statement

on page 255

•

EXECUTE IMMEDIATE Statement [ESQL] [SP]

on page 279

•

GRANT EXECUTE Statement

on page 310

CREATE PROCEDURE Statement (Java UDF)

Creates an interface to an external Java table UDF.

For CREATE PROCEDURE reference information for external procedures, see

CREATE

PROCEDURE Statement (External Procedures)

. For CREATE PROCEDURE reference

information for table UDFs, see

CREATE PROCEDURE Statement (Table UDF)

SQL Statements

Reference: Statements and Options 181

Syntax

Syntax 1 – For a query referencing at least one SAP Sybase IQ table:

CREATE[ OR REPLACE ] PROCEDURE

[ owner.]procedure-name ( [ parameter, …] )

[ RESULT (result-column, ...)]

[ SQL SECURITY { INVOKER | DEFINER } ]

EXTERNAL NAME ‘java-call’ [ LANGUAGE java ] }

parameter:

[ IN parameter_mode parameter-name data-type

[ DEFAULT expression ]

result-column:

column-name data-type

java:

[ ALLOW | DISALLOW SERVER SIDE REQUESTS ]

java-call:

'[ package-name.]class-name.method-name method-signature'

Syntax 2 – For a query referencing catalog store tables only:

CREATE[ OR REPLACE ] PROCEDURE

[ owner.]procedure-name ( [ parameter, …] )

[ RESULT (result-column, ...)]

| NO RESULT SET

[ DYNAMIC RESULT SETS integer-expression ]

[ SQL SECURITY { INVOKER | DEFINER } ]

EXTERNAL NAME ‘java-call’ [ LANGUAGE Java ] }

parameter:

[ IN | OUT | INOUT ] parameter_mode parameter-name data-type

[ DEFAULT expression ]

result-column:

column-name data-type

java:

[ ALLOW | DISALLOW SERVER SIDE REQUESTS ]

java-call:

'[ package-name.]class-name.method-name method-signature'

Parameters

•

java – DISALLOW is the default. ALLOW indicates that server-side connections are

allowed.

Note: Do not specify ALLOW unless necessary. A setting of ALLOW slows down certain

types of SAP Sybase IQ table joins. If you change a procedure definition from ALLOW to

DISALLOW, or vice-versa, the change will not be recognized until you make a new

connection.

SQL Statements

182 SAP Sybase IQ

Do not use UDFs with both ALLOW SERVER SIDE REQUESTS and DISALLOW

SERVER SIDE REQUESTS in the same query.

Usage

If your query references SAP Sybase IQ tables, note that different syntax and parameters

apply compared to a query that references only catalog store tables.

Java table UDFs are only supported in the FROM clause.

For Java table functions, exactly one result set is allowed. If the Java table functions are joined

with an SAP Sybase IQ table or if a column from an SAP Sybase IQ table is an argument to the

Java table function then only one result set is supported.

If the Java table function is the only item in the FROM clause then N number of result sets are

allowed.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—The Transact-SQL

CREATE PROCEDURE

statement is different.

• SQLJ—The syntax extensions for Java result sets are as specified in the proposed SQLJ1

standard.

Permissions

Unless creating a temporary procedure, a user must have the CREATE PROCEDURE system

privilege to create a procedure for themselves. To create UDF procedure for others, a user must

specify an owner and have either the CREATE ANY PROCEDURES or CREATE ANY

OBJECT system privilege. If a procedure has an external reference, a user must also have the

CREATE EXTERNAL REFERENCE system privilege, in addition to the previously

mentioned system privileges, regardless of whether or not they are the owner of procedure.

CREATE PROCEDURE Statement (Table UDF)

Creates an interface to an external table user-defined function (table UDF). Users must be

specifically licensed to use table UDFs.

For CREATE PROCEDURE reference information for external procedures, see

CREATE

PROCEDURE Statement (External Procedures)

. For CREATE PROCEDURE reference

information for Java UDFs, see

CREATE PROCEDURE Statement (Java UDF)

Syntax

CREATE[ OR REPLACE ] PROCEDURE

[ owner.]procedure-name ( [ parameter[, …]] )

| RESULT result-column [, …] )

[ SQL SECURITY { INVOKER | DEFINER } ]

EXTERNAL NAME ‘external-call’

SQL Statements

Reference: Statements and Options 183

parameter:

[ IN ] parameter-name data-type [ DEFAULT expression ]

| [ IN ] parameter-name table-type

table-type:

TABLE( column-name data-type [, ...] )

external-call:

[column-name:]function-name@library; ...

Parameters

•

IN – the parameter is an object that provides a value for a scalar parameter or a set of values

for a TABLE parameter to the UDF.

Note: TABLE parameters cannot be declared as INOUT or OUT. You can only have one

table parameter (the position of which is not important).

•

OR REPLACE – specifying OR REPLACE (CREATE OR REPLACE PROCEDURE)

creates a new procedure, or replaces an existing procedure with the same name. This

clause changes the definition of the procedure, but preserves existing permissions. An

error is returned if you attempt to replace a procedure that is already in use.

•

RESULT – declares the column names and their data types for the result set of the external

UDF. The data types of the columns must be a valid SQL data type (e.g., a column in the

result set cannot have TABLE as data type). The set of datums in the result implies the

TABLE. External UDFs can only have one result set of type TABLE.

Note: TABLE is not an output value. A table UDF cannot have LONG VARBINARY or

LONG VARCHAR data types in its result set, but a table parameterized function (TPF) can

have large object (LOB) data in its result set.

A TPF cannot produce LOB data, but can have columns in the result set as LOB data types.

However, the only way to get LOB data in the output is to pass a column from an input table

to the output table. The describe attribute

EXTFNAPIV4_DESCRIBE_COL_VALUES_SUBSET_OF_INPUT allows this, as

illustrated in the sample file tpf_blob.cxx.

•

SQL SECURITY – defines whether the procedure is executed as the INVOKER (the user

who is calling the UDF), or as the DEFINER (the user who owns the UDF). The default is

DEFINER.

When SQL SECURITY INVOKER is specified, more memory is used because annotation

must be done for each user that calls the procedure. Also, when SQL SECURITY

INVOKER is specified, name resolution is done as the invoker as well. Therefore, care

should be taken to qualify all object names (tables, procedures, and so on) with their

appropriate owner. For example, suppose user1 creates this procedure:

CREATE PROCEDURE user1.myProcedure()

RESULT( columnA INT )

SQL Statements

184 SAP Sybase IQ

SQL SECURITY INVOKER

BEGIN

SELECT columnA FROM table1;

END;

If user2 attempts to run this procedure and a table user2.table1 does not exist, a table

lookup error results. Additionally, if a user2.table1 does exist, that table is used instead of

the intended user1.table1. To prevent this situation, qualify the table reference in the

statement (user1.table1, instead of just table1).

•

EXTERNAL NAME – An external UDF must have EXTERNAL NAME clause which

defines an interface to a function written in a programming language such as C. The

function is loaded by the database server into its address space.

The library name can include the file extension, which is typically .dll on Windows and .so

on UNIX. In the absence of the extension, the software appends the platform-specific

default file extension for libraries. This is a formal example.

CREATE PROCEDURE mystring( IN instr CHAR(255),

IN input_table TABLE(A INT) )

RESULT (CHAR(255))

EXTERNAL NAME

'[email protected];Unix:[email protected]'

A simpler way to write the preceding EXTERNAL NAME clause, using platform-specific

defaults, is as follows:

CREATE PROCEDURE mystring( IN instr CHAR(255),

IN input_table TABLE(A INT) )

RESULT (CHAR(255))

EXTERNAL NAME ‘mystring@mylib’

Usage

You define table UDFs using the a_v4_extfn API. CREATE PROCEDURE statement

reference information for external procedures that do not use the a_v3_extfn or

a_v4_extfn APIs is located in a separate topic. CREATE PROCEDURE statement reference

information for Java UDFs is located in a separate topic.

The CREATE PROCEDURE statement creates a procedure in the database. To create a

procedure for themselves, a user must have the CREATE PROCEDURE system privilege. To

create a procedure for others, a user must specify the owner of the procedure and must have

either the CREATE ANY PROCEDURE or CREATE ANY OBJECT system privilege. If the

procedure contains an external reference, the user must have the CREATE EXTERNAL

REFERENCE system privilege in addition to previously mentioned system privileges,

regardless of who owns the procedure.

If a stored procedure returns a result set, it cannot also set output parameters or return a return

value.

SQL Statements

Reference: Statements and Options 185

When referencing a temporary table from multiple procedures, a potential issue can arise if the

temporary table definitions are inconsistent and statements referencing the table are cached.

Use caution when referencing temporary tables within procedures.

You can use the CREATE PROCEDURE statement to create external table UDFs implemented

in a different programming language than SQL. However, be aware of the table UDF

restrictions before creating external UDFs.

The data type for a scalar parameter, a result column, and a column of a TABLE parameter

must be a valid SQL data type.

Parameter names must conform to the rules for other database identifiers such as column

names. They must be a valid SQL data type.

TPFs support a mix scalar parameters and single table parameter. A TABLE parameter must

define a schema for an input set of rows to be processed by the UDF. The definition of a

TABLE parameter includes column names and column data types.

TABLE(c1 INT, c2 CHAR(20))

The above example defines a schema with the two columns c1 and c2 of types INT and

CHAR(20). Each row processed by the UDF must be a tuple with two (2) values. Table

parameters, unlike scalar parameters cannot be assigned a default value.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—The Transact-SQL CREATE PROCEDURE statement is different.

• SQLJ—The syntax extensions for Java result sets are as specified in the proposed SQLJ1

standard.

Permissions

Unless creating a temporary procedure, a user must have the CREATE PROCEDURE system

privilege to create a UDF for themselves. To create a UDF for others, they must specify the

owner of the procedure and must have either the CREATE ANY PROCEDURE or CREATE

ANY OBJECT system privilege. If the procedure contains an external reference, a user must

also have the CREATE EXTERNAL REFERENCE system privilege, in addition to the

previously mentioned system privileges.

SQL Statements

186 SAP Sybase IQ

CREATE ROLE Statement

Creates a new role, extends an existing user to act as a role, or manages role administrators on a

role.

Syntax

CREATE [ OR REPLACE ] ROLE { role_name | FOR USER userID }

[ WITH ADMIN [ ONLY ] admin_name [...,], [ SYS_MANAGE_ROLES_ROLE ]

Parameters

•

role_name – unless you are using the OR REPLACE clause,

role_name

cannot already

exist in the database.

•

OR REPLACE –

role_name

must already exist in the database. If

role_name

does not

already exist, a new user-defined role is created. All current administrators are replaced by

those specified in the

admin_name [..]

clause as follows:

• All existing role administrators granted the WITH ADMIN OPTION not included on

the new role administrators list become members of the role with no administrative

rights on the role.

• All existing role administrators granted the WITH ADMIN ONLY OPTION not

included on the new role administrators list are removed as members of the role.

When using the OR REPLACE clause, if an existing role administrator is included on the

new role administrators list he or she retains his or her original administrative rights if they

are higher than the replacement rights. For example, User A is an existing role

administrator originally granted WITH ADMIN rights on the role. New role

administrators are granted WITH ADMIN ONLY rights. If User A is included on this list,

User A retains the higher WITH ADMIN rights.

•

FOR USER – when using the FOR USER clause without the OR REPLACE,

userID

must

be the name of an existing user that currently does not have the ability to act as a role.

•

admin_name – list of users to be designated administrators of the role.

•

WITH ADMIN – each

admin_name

specified is granted administrative privileges over

the role in addition to all underlying system privileges. WITH ADMIN clause is not valid

when SYS_MANAGE_ROLES_ROLE is included on the list.

•

WITH ADMIN ONLY – each

admin_name

specified is granted administrative privileges

only over the role, not the underlying system privileges.

•

SYS_MANAGE_ROLES_ROLE – allows global role administrators to administer the

role. Can be specified in conjunction with the WITH ADMIN ONLY clause.

SQL Statements

Reference: Statements and Options 187

Examples

•

Example 1 – creates the role Sales. Only global role administrator can administer the

role.

CREATE ROLE Sales

•

Example 2 – extends the existing user Jane to act as a role.

CREATE OR REPLACE ROLE FOR USER Jane

•

Example 3 – creates the role Finance with Mary and Jeff as role administrators with

administrative rights to the role. Global role administrators cannot administer this role.

CREATE ROLE Finance

WITH ADMIN Mary, Jeff

•

Example 3 – creates the role Marketing with Mary and Jeff as role administrators.

Global role administrators can also manage this role.

CREATE ROLE Finance

WITH ADMIN ONLY Mary, Jeff, SYS_MANAGE_ROLES_ROLE

•

Example 4 – Finance is an existing role with Harry and Susan as role administrators

with administrative rights. You want to keep Susan as an administrator, replace Harry,

and add the global role administrator. The new role administrators will have administrative

rights only.

This statement keeps Susan as an administrator, but Susan retains administrative rights

to the role since the original administrative rights granted were higher. Harry is replaced

by Bob and Sarah, with administrative rights only, and the global role administrator is

added to the role. Harry remains a member of the role, but has no administrative rights.

CREATE OR REPLACE ROLE Finance

WITH ADMIN ONLY Susan, Bob, Sarah, SYS_MANAGE_ROLE_ROLE

Usage

If you specify role administrators (

admin_name

), but do not include the global role

administrator (SYS_MANAGE_ROLES_ROLE), global role administrators will be unable to

manage the new role. Therefore, it is recommended that you not specify role administrators

during the creation process. Use the OR REPLACE clause to add them afterwards.

If you do not specify an ADMIN clause, the default WITH ADMIN ONLY clause is used and

the default administrator is the global roles administrator (SYS_MANAGE_ROLES_ROLE).

When replacing role administrators, if the role has a global role administrator, it must be

included on the new role administrators list or it is removed from the role.

However, when using the WITH ADMIN clause to grant role administrators, since the clause

is not valid for global role administrators, you must use the GRANT ROLE statement to re-add

the global role administrator (SYS_MANAGE_RILES_ROLE) to the role. Failure to perform

this grant means global role administrators are unable to manage the role.

SQL Statements

188 SAP Sybase IQ

Standards

ANSI SQL – Compliance level: Transact-SQL extension.

Permissions

• Create a new role – Requires the MANAGE ROLES system privilege.

• OR REPLACE clause – Requires the MANAGE ROLES system privilege along with

administrative rights over the role being replaced.

CREATE SCHEMA Statement

Creates a schema, which is a collection of tables, views, and permissions and their associated

permissions, for a database user.

Syntax

CREATE SCHEMA AUTHORIZATION userid

... [ { create-table-statement

| create-view-statement

| grant-statement } ] …

Usage

The

userid

must be the user ID of the current connection. You cannot create a schema for

another user. The user ID is not case-sensitive.

If any of the statements in the CREATE SCHEMA statement fail, the entire CREATE SCHEMA

statement is rolled back.

CREATE SCHEMA statement is simply a way to collect individual CREATE and GRANT

statements into one operation. There is no SCHEMA database object created in the database,

and to drop the objects you must use individual DROP TABLE or DROP VIEW statements. To

revoke permissions, use a REVOKE statement for each permission granted.

Note: The CREATE SCHEMA statement is invalid on an active multiplex.

Individual CREATE or GRANT statements are not separated by statement delimiters. The

statement delimiter marks the end of the CREATE SCHEMA statement itself.

The individual CREATE or GRANT statements must be ordered such that the objects are

created before permissions are granted on them.

Creating more than one schema for a user is not recommended and might not be supported in

future releases.

Side Effects

• Automatic commit

SQL Statements

Reference: Statements and Options 189

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—SAP Sybase IQ does not support the use of REVOKE statements within the

CREATE SCHEMA statement, and does not allow its use within Transact-SQL batches or

procedures.

Permissions

Requires the CREATE ANY OBJECT system privilege.

See also

•

CREATE TABLE Statement

on page 205

•

CREATE VIEW Statement

on page 234

•

GRANT CREATE Statement

on page 308

CREATE SEQUENCE statement

Creates a sequence that can be used to generate primary key values that are unique across

multiple tables, and for generating default values for a table. This statement applies to SAP

Sybase IQ catalog store tables only.

Syntax

CREATE [ OR REPLACE ] SEQUENCE [ owner.] sequence-name

[ INCREMENT BY signed-integer ]

[ START WITH signed-integer ]

[ MINVALUE signed-integer | NO MINVALUE ]

[ MAXVALUE signed-integer | NO MAXVALUE ]

[ CACHE integer | NO CACHE ]

[ CYCLE | NO CYCLE ]

Parameters

OR REPLACE clause – Specifying OR REPLACE creates a new sequence, or replaces an

existing sequence with the same name. If you do not use the OR REPLACE clause, an error is

returned if you specify the name of a sequence that already exists for the current user.

INCREMENT BY clause – Defines the amount the next sequence value is incremented from

the last value assigned. The default is 1. Specify a negative value to generate a descending

sequence. An error is returned if the INCREMENT BY value is 0.

START WITH clause – Defines the starting sequence value. If you do not specify a value for

the START WITH clause, MINVALUE is used for ascending sequences and MAXVALUE is

used for descending sequences. An error is returned if the START WITH value is beyond the

range specified by MINVALUE or MAXVALUE.

SQL Statements

190 SAP Sybase IQ

MINVALUE clause – Defines the smallest value generated by the sequence. The default is 1.

An error is returned if MINVALUE is greater than ( 2^63-1) or less than -(2^63-1). An error is

also returned if MINVALUE is greater than MAXVALUE.

MAXVALUE clause – Defines the largest value generated by the sequence. The default is

2^63-1. An error is returned if MAXVALUE is greater than 2^63-1 or less than -(2^63-1).

CACHE clause – Specifies the number of preallocated sequence values that are kept in

memory for faster access. When the cache is exhausted, the sequence cache is repopulated and

a corresponding entry is written to the transaction log. At checkpoint time, the current value of

the cache is forwarded to the ISYSSEQUENCE system table. The default is 100.

CYCLE clause – Specifies whether values should continue to be generated after the

maximum or minimum value is reached.

The default is NO CYCLE, which returns an error once the maximum or minimum value is

reached.

Remarks

A sequence is a database object that allows the automatic generation of numeric values. A

sequence is not bound to a specific or unique table column and is only accessible through the

table column to which it is applied.

Sequences can generate values in one of the following ways:

Increment or decrement monotonically without bound

Increment or decrement monotonically to a user-defined limit and stop

Increment or decrement monotonically to a user-defined limit and cycle back to the

beginning and start again

You control the behavior when the sequence runs out of values using the CYCLE clause.

If a sequence is increasing and it exceeds the MAXVALUE, MINVALUE is used as the next

sequence value if CYCLE is specified. If a sequence is decreasing and it falls below

MINVALUE, MAXVALUE is used as the next sequence value if CYCLE is specified. If

CYCLE is not specified, an error is returned.

Sequence values cannot be used with views or materialized view definitions.

Privileges

You must have the CREATE ANY SEQUENCE or CREATE ANY OBJECT system privilege

to create sequences.

Side effects

None

SQL Statements

Reference: Statements and Options 191

Standards and compatibility

•

SQL/2008 – Sequences comprise SQL/2008 language feature T176. SAP Sybase IQ does

not allow optional specification of the sequence data type—this behavior can be achieved

with a CAST when using the sequence.

In addition, the following are vendor extensions:

CACHE clause

OR REPLACE syntax

CURRVAL expression

Use of sequences in DEFAULT expressions

Example

The following example creates a sequence named Test that starts at 4, increments by 2, does

not cycle, and caches 15 values at a time:

CREATE SEQUENCE Test

START WITH 4

INCREMENT BY 2

NO MAXVALUE

NO CYCLE

CACHE 15;

CREATE SERVER Statement

Adds a server to the ISYSSERVER table.

Syntax

CREATE SERVER server-name

CLASS 'server-class'

USING 'connection-info'

[ READ ONLY ]

server-class:

{ ASAJDBC

| ASEJDBC

| SAODBC

| ASEODBC

| DB2ODBC

| MSSODBC

| ORAODBC

| ODBC }

connection-info:

{ machine-name:port-number [ /dbname ] | data-source-name }

SQL Statements

192 SAP Sybase IQ

Parameters

•

USING – if a JDBC-based server class is used, the USING clause is

hostname:port-

number [/dbname]

where:

•

hostname – the machine on which the remote server runs.

•

portnumber – the TCP/IP port number on which the remote server listens. The default

port number for SAP Sybase IQ and SQL Anywhere is 2638.

•

dbname – for SQL Anywhere remote servers, if you do not specify a

dbname

, the

default database is used. For Adaptive Server Enterprise, the default is the master

database, and an alternative to using

dbname

is to another database by some other

means (for example, in the FORWARD TO statement).

If an ODBC-based server class is used, the USING clause is the

data-source-name

, which

is the ODBC Data Source Name.

•

READ ONLY – specifies that the remote server is a read-only data source. Any update

request is rejected by SAP Sybase IQ.

Examples

•

Example 1 – create a remote server for the JDBC-based Adaptive Server Enterprise server

named ase_prod. Its machine name is “banana” and port number is 3025.

CREATE SERVER ase_prod

CLASS 'asejdbc'

USING 'banana:3025'

•

Example 2 – create a SQL Anywhere remote server named testasa on the machine

“apple” with listening on port number 2638:

CREATE SERVER testasa

CLASS 'asajdbc'

USING 'apple:2638'

•

Example 3 – create a remote server for the Oracle server named oracle723. Its ODBC

Data Source Name is “oracle723”:

CREATE SERVER oracle723

CLASS 'oraodbc'

USING 'oracle723'

Usage

CREATE SERVER defines a remote server from the SAP Sybase IQ catalogs.

Side Effects

• Automatic commit

SQL Statements

Reference: Statements and Options 193

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Supported by Open Client/Open Server.

Permissions

Requires the SERVER OPERATOR system privilege.

See also

•

ALTER SERVER Statement

on page 41

•

DROP SERVER Statement

on page 269

CREATE SERVICE Statement

Permits a database server to act as a Web server.

Syntax

CREATE SERVICE service-name-string

TYPE service-type-string

[ attributes ] [

AS statement ]

attributes:

[ AUTHORIZATION { ON | OFF } ]

[ SECURE { ON | OFF } ]

[ USER { user-name | NULL } ]

[ URL [ PATH/ ] { ON | OFF | ELEMENTS } ]

[ USING { SOAP-prefix | NULL } ]

service-type-string:

{ 'RAW '

| 'HTML '

| 'XML '

| 'SOAP '

| 'DISH ' }

Parameters

•

service-name-string – Web service names may be any sequence of alphanumeric

characters or “/”, “-”, “_”, “.”, “!”, “~”, “*”, “'”, “(“, or “”)”, except that the first character

cannot begin with a slash (/) and the name cannot contain two or more consecutive slash

characters.

•

AUTHORIZATION – determines whether users must specify a user name and password

when connecting to the service. The default value is ON.

SQL Statements

194 SAP Sybase IQ

• If authorization is OFF, the AS clause is required and a single user must be identified by

the USER clause. All requests are run using that user’s account and permissions.

• If authorization is ON, all users must provide a user name and password. Optionally,

you can limit the users that are permitted to use the service by providing a user or role

name using the USER clause. If the user name is NULL, all known users can access the

service.

Run production systems with authorization turned on. Grant permission to use the service

by adding users to a role.

•

SECURE – indicates whether unsecure connections are accepted. ON indicates that only

HTTPS connections are to be accepted. Service requests received on the HTTP port are

automatically redirected to the HTTPS port. If set to OFF, both HTTP and HTTPS

connections are accepted. The default value is OFF.

•

USER – if authorization is disabled, this parameter becomes mandatory and specifies the

user ID used to execute all service requests. If authorization is enabled (the default), this

optional clause identifies the user or role permitted access to the service. The default value

is NULL, which grants access to all users.

•

URL – determines whether URI paths are accepted and, if so, how they are processed.

OFF indicates that nothing must follow the service name in a URI request. ON indicates

that the remainder of the URI is interpreted as the value of a variable named

url

ELEMENTS indicates that the remainder of the URI path is to be split at the slash

characters into a list of up to 10 elements. The values are assigned to variables named url

plus a numeric suffix of between 1 and 10; for example, the first three variable names are

url1, url2, and url3. If fewer than 10 values are supplied, the remaining variables are set to

NULL. If the service name ends with the character /, then URL must be set to OFF. The

default value is OFF.

•

USING – applies only to DISH services. The parameter specifies a name prefix. Only

SOAP services whose names begin with this prefix are handled.

•

service-type-string – identifies the type of the service. The type must be one of the listed

service types. There is no default value.

• RAW – sends the result set to the client without any further formatting. You can produce

formatted documents by generating the required tags explicitly within your procedure.

• HTML – formats the result set of a statement or procedure into an HTML document that

contains a table.

• XML – assumes the result set is an XML format. If it is not already so, it is automatically

converted to XML RAW format.

• SOAP – formats the result set as a Simple Object Access Protocol (SOAP) response.

The request must be a valid SOAP request. For more information about the SOAP

standards, see

www.w3.org/TR/SOAP

• DISH – determine SOAP Handler, or DISH, service acts as a proxy for one or more

SOAP services. In use, it acts as a container that holds and provides access to a number

SQL Statements

Reference: Statements and Options 195

of SOAP services. A Web Services Description Language (WSDL) file is

automatically generated for each of the included SOAP services. The included SOAP

services are identified by a common prefix, which must be specified in the USING

clause.

•

statement – if the statement is NULL, the URI must specify the statement to be executed.

Otherwise, the specified SQL statement is the only one that can be executed through the

service. The statement is mandatory for SOAP services, and ignored for DISH services.

The default value is NULL.

All services that are run in production systems must define a statement. The statement can

be NULL only if authorization is enabled.

Examples

•

Example 1 – sets up a Web server quickly, start a database server with the -xs switch, then

execute this statement:

CREATE SERVICE tables TYPE 'HTML'

AUTHORIZATION OFF USER DBA

AS SELECT * FROM SYS.ISYSTAB

After executing this statement, use any Web browser to open the URL http://

localhost/tables.

Usage

The CREATE SERVICE statement causes the database server to act as a web server. A new

entry is created in the SYSWEBSERVICE system table.

Standards

• SQL—ISO/ANSI SQL compliant.

• Sybase—Not supported by Adaptive Server Enterprise.

Permissions

Requires the MANAGE ANY WEB SERVICE system privilege.

See also

•

ALTER SERVICE Statement

on page 44

•

DROP SERVICE Statement

on page 269

SQL Statements

196 SAP Sybase IQ

CREATE SPATIAL REFERENCE SYSTEM Statement

Creates or replaces a spatial reference system.

Syntax

{ CREATE [ OR REPLACE ] SPATIAL REFERENCE SYSTEM

| CREATE SPATIAL REFERENCE SYSTEM IF NOT EXISTS }

srs-name

[ srs-attribute ] [ srs-attribute ... ]

srs-attribute:

SRID srs-id

| DEFINITION { definition-string | NULL }

| ORGANIZATION { organization-name IDENTIFIED BY organization-srs-id

| NULL }

| TRANSFORM DEFINITION { transform-definition-string | NULL }

| LINEAR UNIT OF MEASURE linear-unit-name

| ANGULAR UNIT OF MEASURE { angular-unit-name | NULL }

| TYPE { ROUND EARTH | PLANAR }

| COORDINATE coordinate-name { UNBOUNDED | BETWEEN low-number

AND high-number }

| ELLIPSOID SEMI MAJOR AXIS semi-major-axis-length { SEMI MINOR AXIS

semi-minor-axis-length

| INVERSE FLATTENING inverse-flattening-ratio }

| SNAP TO GRID { grid-size | DEFAULT }

| TOLERANCE { tolerance-distance | DEFAULT }

| POLYGON FORMAT polygon-format

| STORAGE FORMAT storage-format

grid-size:

DOUBLE : usually between 0 and 1

axis-order:

{ 'x/y/z/m' | 'long/lat/z/m' | 'lat/long/z/m' }

polygon-format:

{ 'CounterClockWise' | 'Clockwise' | 'EvenOdd' }

storage-format:

{ 'Internal' | 'Original' | 'Mixed' }

Parameters

•

OR REPLACE – Specifying OR REPLACE creates the spatial reference system if it does

not already exist in the database, and replaces it if it does exist. An error is returned if you

attempt to replace a spatial reference system while it is in use. An error is also returned if

you attempt to replace a spatial reference system that already exists in the database without

specifying the OR REPLACE clause.

SQL Statements

Reference: Statements and Options 197

•

IF NOT EXISTS – Specifying CREATE SPATIAL REFERENCE IF NOT EXISTS

checks to see if a spatial reference system by that name already exists. If it does not exist,

the database server creates the spatial reference system. If it does exist, no further action is

performed and no error is returned.

•

IDENTIFIED BY – the SRID (

srs-id

) for the spatial reference system. If the spatial

reference system is defined by an organization with an

organization-srs-id

, then

srs-id

should be set to that value.

If the IDENTIFIED BY clause is not specified, then the SRID defaults to the

organization-

srs-id

defined by either the ORGANIZATION clause or the DEFINITION clause. If

neither clause defines an

organization-srs-id

that could be used as a default SRID, an error

is returned.

When the spatial reference system is based on a well known coordinate system, but has a

different geodesic interpretation, set the srs-id value to be 1000000000 (one billion) plus

the well known value. For example, the SRID for a planar interpretation of the geodetic

spatial reference system WGS 84 (ID 4326) would be 1000004326.

With the exception of SRID 0, spatial reference systems provided by SAP Sybase IQ that

are not based on well known systems are given a SRID of 2000000000 (two billion) and

above. The range of SRID values from 2000000000 to 2147483647 is reserved by SAP

Sybase IQ and you should not create SRIDs in this range.

To reduce the possibility of choosing a SRID that is reserved by a defining authority such

as OGC or by other vendors, you should not choose a SRID in the range 0 - 32767 (reserved

by EPSG), or in the range 2147483547 - 2147483647.

Also, since the SRID is stored as a signed 32-bit integer, the number cannot exceed 231-1

or 2147483647.

•

DEFINITION – set, or override, default coordinate system settings. If any attribute is set

in a clause other than the DEFINITION clause, it takes the value specified in the other

clause regardless of what is specified in the DEFINITION clause.

definition-string

is a string in the Spatial Reference System Well Known Text syntax as

defined by SQL/MM and OGC. For example, the following query returns the definition for

WGS 84.

SELECT ST_SpatialRefSys::ST_FormatWKT( definition )

FROM ST_SPATIAL_REFERENCE_SYSTEMS

WHERE srs_id=4326;

In Interactive SQL, if you double-click the value returned, an easier to read version of the

value appears.

When the DEFINITION clause is specified, definition-string is parsed and used to choose

default values for attributes. For example, definition-string may contain an AUTHORITY

element that defines the organization-name and

organization-srs-id

SQL Statements

198 SAP Sybase IQ

Parameter values in definition-string are overridden by values explicitly set using the SQL

statement clauses. For example, if the ORGANIZATION clause is specified, it overrides

the value for ORGANIZATION in definition-string.

•

ORGANIZATION – information about the organization that created the spatial reference

system that the spatial reference system is based on.

•

TRANSFORM DEFINITION – a description of the transform to use for the spatial

reference system. Currently, only the PROJ.4 transform is supported. The transform

definition is used by the ST_Transform method when transforming data between spatial

reference systems. Some transforms may still be possible even if there is no transform-

definition-string defined.

•

LINEAR UNIT OF MEASURE – the linear unit of measure for the spatial reference

system. The value you specify must match a linear unit of measure defined in the

ST_UNITS_OF_MEASURE system view.

If this clause is not specified, and is not defined in the DEFINITION clause, the default is

METRE. To add predefined units of measure to the database, use the sa_install_feature

system procedure.

To add custom units of measure to the database, use the CREATE SPATIAL UNIT OF

MEASURE statement.

Note: While both METRE and METER are accepted spellings, METRE is preferred as it

conforms to the SQL/MM standard.

•

ANGULAR UNIT OF MEASURE – the angular unit of measure for the spatial reference

system. The value you specify must match an angular unit of measure defined in the

ST_UNITS_OF_MEASURE system table.

If this clause is not specified, and is not defined in the DEFINITION clause, the default is

DEGREE for geographic spatial reference systems and NULL for non-geographic spatial

reference systems.

The angular unit of measure must be non-NULL for geographic spatial reference systems

and it must be NULL for non-geographic spatial reference systems.

The angular unit of measure must be non-NULL for geographic spatial reference systems

and it must be NULL for non-geographic spatial reference systems. To add predefined

units of measure to the database, use the sa_install_feature system procedure.

To add custom units of measure to the database, use the CREATE SPATIAL UNIT OF

MEASURE statement.

•

TYPE – control how the SRS interprets lines between points. For geographic spatial

reference systems, the TYPE clause can specify either ROUND EARTH (the default) or

PLANAR. The ROUND EARTH model interprets lines between points as great elliptic

arcs. Given two points on the surface of the Earth, a plane is selected that intersects the two

SQL Statements

Reference: Statements and Options 199