3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

By clicking here, you understand that we use cookies to improve your experience on our website. For more details, please see our Cookie Policy. ×

 TechDocs

CA DATACOM CORE 15.1

 PDF Version 15.1  English

Product Menu 

Using SCROLL CURSOR with DECLARE CURSOR and

FETCH Statements
Last Updated March 4, 2020

Product:CA Datacom®
Release: 14.0
OS: z/OS
The SCROLL CURSOR enhancement to the DECLARE CURSOR and FETCH statements in SQL provides the option to control
whether the cursor is scrollable.
The following topics are discussed on this page:

DECLARE CURSOR

Cursor Usage
FETCH

DECLARE CURSOR

This SQL statement can Through the CA Datacom® In an application program prepared By using CA Dataquery™
be executed in the Datadictionary™ interactive SQL using Datacom/DB SQL for CA Datacom® (SQL &
following ways: Service Facility (interactive) preprocessor (embedded) Batch Modes)

DECLARE CURSOR YES

Note: YES indicates a valid execution method for this statement.

Note: This statement cannot be executed interactively. Use the SELECT statement instead (see SELECT).
The DECLARE CURSOR statement defines a cursor.
The following syntax diagram displays the DECLARE CURSOR statement and provides a brief description of the keywords and
variables.

►►─ DECLARE cursor-name ─┬─ NO SCROLL ◄ ──────────────────────────┬─ CURSOR ──►

├─ ASENSITIVE ◄ ──────────────┬─ SCROLL ─┘
├─ INSENSITIVE ───────────────┤
└─ SENSITIVE ─┬─ DYNAMIC ◄ ─┬─┘
└─ STATIC ────┘
►──┬─────────────┬─ FOR ─┬─ select-statement ─┬──────────────────────────►◄
└─ WITH HOLD ─┘ └─ statement-name ───┘

NO SCROLL

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 1/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

Specifies the cursor is not scrollable. If scrolling is not specified, the default is NO SCROLL. With NO SCROLL, the FETCH statement
can only return the next row.
Note: Rows are sensitive to changes if a temporary table is not used.
SCROLL
Specifies the cursor is scrollable.
ASENSITIVE
Specifies that the cursor is SENSITIVE DYNAMIC if a temporary table is not used. Otherwise, it is INSENSITIVE. This is the same as
NO SCROLL except that scroll options are available with the FETCH statement.
When scrolling is used, ASENSITIVE is the default scroll type.
INSENSITIVE
Specifies that the cursor is not sensitive to changes in the underlying tables of the result set.
With INSENSITIVE specified, the cursor is made read-only, and no positioned update or delete is allowed
SENSITIVE
Specifies that the cursor is sensitive to changes made after the cursor is opened.
Note: If changes cannot be made visible to the cursor, an error is returned on the bind of the cursor open statement.
Changes cannot be made visible if a temporary table is required, or when the cursor has more than one database table, or when a User
Defined Function Table (UDFT) is used.
A SENSITIVE scroll cursor must therefore reference only a single database table and not use aggregation.
SENSITIVE scroll cursors can be DYNAMIC or STATIC. The DYNAMIC scroll cursor is the default with SENSITIVE specified.
DYNAMIC
Specifies that changes made by the current transaction are visible immediately, and changes made by other transactions are visible
when committed.
A temporary table is not built, so qualifying rows that are inserted while the cursor is open are visible, and rows deleted or updated such
that they no longer qualify while the cursor is open are no longer visible.
If a row is updated, it is logically moved to its new position in the result set. For example, if the key being used to retrieve rows
dynamically is on column line_number, if the application increments line_number using a positioned update, then the same row will be
fetched using fetch next.
This is more efficient than an insensitive scroll cursor because no temporary table is required, but the application must be able to work
properly with the dynamic nature of the result set.
STATIC
As with an insensitive scroll cursor, a result table is built, so the size of the result set does not change. However, rows fetched using the
fetch sensitive option reflect the current state of the corresponding underlying base table row.
Row of a cursor declared as sensitive static can be fetched as sensitive or insensitive. If fetch sensitive is used, then the temporary
table is updated to reflect the corresponding row of the underlying database table. If fetch insensitive is used, the row is returned from
the temporary table in its current state, which reflects changes due to a previous fetch sensitive.

Rows inserted after the cursor is opened are not visible.

Rows deleted after the cursor is opened are not visible; a delete hole is created.
Rows updated after the cursor is opened such that they no longer qualify are not visible; an update hole is created.

cursor-name
A cursor with the specified name is defined when your program is executed. The name must not be the same as the name of another
cursor declared in your program.
If you specify SQLMODE=ANSI or SQLMODE=FIPS in the SQL Preprocessor options, the cursor name can be 1 to 18 characters.
For all other modes, the cursor name can be 1 to 32 characters.
WITH HOLD
When this CA Datacom®/DB extension is specified, the cursor stays open when a COMMIT WORK is executed. Any record-at-a-time
(RAAT) command that commits the logical unit of work (for example LOGCP, LOGCR) works the same way. This is especially useful in
a batch program that does updates and issues COMMIT WORK periodically to keep the log from becoming full and to limit the amount
of work RESTART would have to do in case of a failure. The repositioning of the cursor is harder to program without WITH HOLD.
select-statement
For information, see Select-Statement.
statement-name
Specifies the name of a prepared statement. That statement must be prepared (using the PREPARE statement) sometime after the
DECLARE CURSOR statement is executed and before the OPEN statement is executed, and it must be a select-statement. For
information, see PREPARE.
A cursor in the open state designates a result table and a position relative to the rows of that table. The table is the result table
specified by the select-statement of the cursor.
https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 2/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

The result table is read-only if the select-statement includes any of the following:

The keyword DISTINCT

A UNION operator
A column function
A GROUP BY clause
A HAVING clause
An ORDER BY clause

The result table is also read-only if the FROM clause of the outer sub-select of the select-statement:

Identifies more than one table or view

Identifies a read-only view
Identifies a table or view that is also identified in a FROM clause of a sub-query of the select-statement

Cursor Usage
A DECLARE CURSOR statement must have corresponding OPEN, FETCH, and CLOSE statements in the same source program. The
execution of the OPEN can then proceed without error.
Cursors must be declared in the source:

1. Before any reference to the cursor

2. After all host variables used in the definition have been defined

If an exception declaration (WHENEVER statement) is not provided, we recommend that your program include code to check the
returned value of the SQLCODE immediately after each executable SQL statement. If you do not use a WHENEVER statement, be
aware of the following:
Cursor definitions are declarations, not operational (procedural) statements, and as such are used for Preprocessor input only.
Because no call is sent to the MUF, checking the SQLCODE after a DECLARE CURSOR statement always shows the SQLCODE
received by whatever statement immediately preceeded the DECLARE CURSOR statement.
In COBOL, cursor declarations can be made in the:

WORKING-STORAGE SECTION
LINKAGE SECTION

REPORT SECTION
PROCEDURE DIVISION

Note: We recommend that you place all cursor definitions immediately before the PROCEDURE DIVISION source statement. However,
if you do not use a WHENEVER statement and want to avoid any potential confusion resulting from the content of the SQLCODE after
a DECLARE CURSOR statement, place all of your DECLARE CURSOR statements in the WORKING-STORAGE SECTION.

Example 1
In the following example, the DECLARE CURSOR statement associates the cursor name C1 with the results of the SELECT. This
example also shows how the cursor is opened with the OPEN statement, used in a FETCH statement, and closed with a CLOSE
statement.

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 3/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

EXEC SQL
DECLARE C1 CURSOR FOR
SELECT DEPTNO, DEPTNAME, MGRNO
FROM DEPTTBL
WHERE ADMDEPT = 'A0'
END-EXEC.

...

* DISPLAY DEPT TABLE INFO

EXEC SQL
WHENEVER NOT FOUND GO TO DEPT-FETCH-LP-END
WHENEVER SQLERROR GO TO SQL-ERROR-RTN
WHENEVER SQLWARNING CONTINUE
END-EXEC.

EXEC SQL
OPEN C1
END-EXEC.

DEPT-FETCH-LP.
EXEC SQL
FETCH C1 INTO :DNUM, :DNAME, :MNUM
END-EXEC.
DISPLAY DNUM, DNAME, MNUM.
GO TO FETCH-LOOP.
DEPT-FETCH-LP-END.

EXEC SQL
CLOSE C1
END-EXEC.
...

 Example 2
In the following example, the DECLARE CURSOR statement defines the cursor, C1. The C1 cursor could be used in an UPDATE
statement to update the column named in the clause, or used in a DELETE statement to delete a row.

EXEC SQL
DECLARE C1 CURSOR FOR
SELECT DEPTNO, DEPTNAME, MGRNO
FROM DEPTTBL
WHERE EXISTS
(SELECT *
FROM DIVTBL
WHERE DIVTBL.DEPTNO = DEPTTBL.DEPTNO)
END-EXEC

Example 3
In the following example, the DECLARE CURSOR statement defines the cursor, C1. Because an ORDER BY clause is included in the
definition, the results of the SELECT are ordered. The SELECT retrieves the number and name of all employees hired before 1980 in
order of seniority. HIREDATE is in the form "yymmdd."

EXEC SQL
DECLARE C1 CURSOR FOR
SELECT DEPTNO, DEPTNAME, MGRNO
FROM DEPTTBL
WHERE EXISTS
(SELECT *
FROM DIVTBL
WHERE DIVTBL.DEPTNO = DEPTTBL.DEPTNO)
END-EXEC

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 4/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

FETCH
This SQL statement can be executed in the following ways:

This SQL statement can Through the CA Datacom® In an application program prepared By using CA Dataquery™
be executed in the Datadictionary™ interactive SQL using Datacom/DB SQL for CA Datacom® (SQL &
following ways: Service Facility (interactive) preprocessor (embedded) Batch Modes)

FETCH YES

Note: YES indicates a valid execution method for this statement.

The FETCH statement positions a cursor on the specified row of its result table and assigns the value of that row to any specified host
variables. You can use multiple FETCH statements referencing the same cursor. The host variables in the INTO list are matched by
position to SELECT list expressions. The INTO list may FETCH a leading subset of the SELECT list expressions. However, unless the
plan has SQLMODE=DB2, the FETCH statement that appears first in the host program must have the same or greater number of host
variables. Also, although each FETCH statement may reference different host variables, unless the plan has SQLMODE=DB2, they
must have the same data type, length, precision, and scale.
The following syntax diagram displays the FETCH statement and provides a brief description of the keywords, notes, and variables.

►►─ FETCH ─┬───────────────┬──┤ fetch-orientation ├──┬──────────┬─ cursor-name ─►

├─ INSENSITIVE ─┤ └─ FROM ◄ ─┘
└─ SENSITIVE ───┘
►──┬──────────────────────┬─────┬───────────────────────────────────┬──────────►◄
└─┤ single-row-fetch ├─┘ ├ ┌─ , ─────────────┐ ┤
├─ INTO ─▼─ host-variable ─┴────────┤
└─ USING DESCRIPTORdescriptor-name ─┘

Expansion of fetch-orientation
├──┬── BEFORE ──────────┬──────────────────────────────────────┤
├── AFTER ───────────┤
└─┤ row-positioned ├─┘

Expansion of row-positioned

├──┬── NEXT ────────────────────────────┬───────────────────────┤

├── PRIOR ───────────────────────────┤
├── FIRST ───────────────────────────┤
├── LAST ────────────────────────────┤
├── ABSOLUTE──┬─ host-variable ────┬─┤
├ └─ integer-constant ─┘ ┤
└── RELATIVE ─┬─ host-variable ────┬─┘
└─ integer-constant ─┘

Expansion of single-row-fetch

├──┬───────────────────────────────────┬─────────────────────────┤
├ ┌─ , ─────────────┐ ┤
├─ INTO ─▼─ host-variable ─┴────────┤
└─ INTO DESCRIPTOR descriptor-name ─┘

Note 1: Whether INSENSITIVE or SENSITIVE is the default in the FETCH statement depends on the sensitivity of the cursor specified
in the DECLARE CURSOR statement. If INSENSITIVE was specified in DECLARE CURSOR, INSENSITIVE is the default in the
FETCH statement. If SENSITIVE was specified in DECLARE CURSOR, SENSITIVE is the default in the FETCH statement.
Note 2: If SENSITIVE or INSENSITIVE is specified in the FETCH statement, single-row-fetch must also be specified.
Note 3: If BEFORE or AFTER is specified, do not specify SENSITIVE, INSENSITIVE, or the accompanying single-row-fetch.
Note 4: For a scrollable cursor, all FETCH statements with the single-row-fetch must specify the same number of columns.
Note 5: INTO and USING are optional, as shown, if a SCROLL CURSOR is being used. For non-SCROLL CURSOR operations,
however, specifying either INTO or USING is required.Description
Positioning
Positioning is either BEFORE or AFTER the first or last row of the result set, or it is based on the ABSOLUTE or RELATIVE position in
the result set.
The position value must be an integer literal or host variable.
ABSOLUTE

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 5/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

The cursor is positioned to the row specified from the beginning, or end if negative, of the result set. If the position is zero, the cursor is
positioned before the first row of the set. If the position value is greater than the number of rows in the result set, a warning is issued
and the position is changed to after the last row.
Examples with a set of 100 rows:
0 - cursor is positioned before first row of set, no data returned.
10 - cursor is positioned on the tenth row of the set, data returned (unless a hole with the static sensitive cursor mode).
-1 - cursor is positioned on the last row of the set.
101 - cursor is positioned after the last row of the set, no data returned, warning issued.
-101 - cursor is positioned before the first row of the set, no data returned, warning issued.
RELATIVE
The cursor is positioned from the current position. A negative value positions backwards, and a positive value forwards. Zero returns the
current row; however, if the current row has been deleted or updated such that it no longer qualifies, then the next row of the set is
returned for the dynamic sensitive cursor mode.
0 - the same row is returned. If it has been deleted or no longer qualifies for a sensitive dynamic cursor, then the next row is returned.
+10 - cursor is moved forward 10 rows, and data returned (unless a hole with the static sensitive cursor mode). If position is after the
last row of the set, a warning is returned and no data returned.
-1 - cursor is positioned backwards one row.
+101 - cursor is positioned after the last row of the set, no data returned, warning issued.
-101 - cursor is positioned before the first row of the set, no data returned, warning issued.
Cursors are declared insensitive, sensitive static and sensitive dynamic, but there is also the option of specifying insensitive or sensitive
on the fetch.

Declare Fetch Fetch

Insentitive Sensitive

Insensitive Not needed since it is the default. Error returned, no effect on cursor.

Sensitive Error returned; no effect on cursor. Row is returned from the database, reflecting changes made by this
Dynamic transaction, and other committed changes.

Sensitive Returns row as is

Static If the row has been deleted, no data is returned.

If the row has been updated such that it no longer qualifies for the set, no
data is returned.
If the row has been updated, the updated values are returned.
Rows inserted since the cursor was opened that would qualify are not
visible.

Any Positioned update or delete from the Previous fetch sensitive reflected.
cursor are reflected.

Starting and Resulting Cursor Position

Kalpana Shyam of IBM Silicon Valley Lab provided the table below in her presentation "Scrollable Cursors: Fetching Opportunities for
DB2 for OS/390" at the DB2 and Business Intelligence Technical Conference, October 16-20, 2000.
Starting and resulting cursor position table

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 6/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

Note: If a fetch encounters an update or delete hole, a +222 SQLCODE is returned to the program.
SQLCA
Explanation of SQLCA fields on scrollable cursors

Field Value Meaning

SQLWARN1 N Non-scrollable

SQLWARN1 S Scrollable

SQLWARN4 I Insensitive

SQLWARN4 S Sensitive-static

SQLWARN5 1 Read-only implicitly or explicitly

SQLWARN5 2 Select and delete allowed on result table

SQLWARN5 3 Select, delete, and update allowed on result table

cursor-name
Specify the name of a cursor that is defined in a DECLARE CURSOR statement of your program. The DECLARE CURSOR statement
must precede the FETCH statement in your source program. When the FETCH statement is executed, the cursor must be in the open
state.
INTO host-variable
If INTO is used, each host-variable you specify must identify a variable that is described in your program in accordance with the rules for
declaring host variables. The host variables must be separated by commas.
The first value in the result row is assigned to the first variable in the list, the second value to the second variable, and so on. If the
number of variables is not the same as the number of values in the row, the SQLCA-WARNING(4) field of the SQLCA is set to W.
The data type of a variable must be compatible with the value assigned to it. If the value is numeric, the variable must have the
capacity to represent the integral part of the value. If the value is null, an indicator variable must be specified.
Each assignment to a variable is made according to the rules described in Basic Operations (Assignment and Comparison)
Assignments are made in sequence through the list. If an assignment error occurs, the value is not assigned to the variable, and no
more values are assigned to variables. Any values that have already been assigned to variables remain assigned.
USING DESCRIPTOR descriptor-name
This clause allows the row of a result table of a cursor to be fetched into variables which are determined at execution-time. Descriptor-
name identifies a SQL Descriptor Area (SQLDA) that contains a valid description of zero or more host variables. The length of the
SQLDA, as indicated by SQLABC, must be sufficient to describe the number of variables indicated by SQLD. The first value of a row
corresponds to the first variable described by the SQLDA, the second value to the second variable, and so on. For more information
about the SQLDA, see SQL Descriptor Area (SQLDA).
https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 7/8
3/17/2020 Using SCROLL CURSOR with DECLARE CURSOR and FETCH Statements

Note: A cursor referenced in an UPDATE or DELETE statement must be positioned on a row. A cursor can only be positioned on a row
as a result of a FETCH statement. If an error occurs during the execution of a FETCH statement that makes the position of a cursor
unpredictable, the cursor is closed.

Example
See the DECLARE CURSOR's "Example 1" on Example1.

Products

Applications

Support

Company

How to Buy

Copyright © 2005-2019 Broadcom. All Rights Reserved. The term 'Broadcom' refers to Broadcom Inc. and/or its subsidiaries.

Privacy Policy Cookie Policy Terms of Use Sitemap

    

https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-mainframe-software/database-management/ca-datacom/15-1/using/using-sql/using-scroll-cursor-with-declare-cursor-and-fetch-statements.html 8/8