START_SEGMENTED_STRING
Starts a stream of segmented string segments within a record
stream. To end the stream, use the END_SEGMENTED_STRING
statement.
1 – More
If you have invoked a database, you have the necessary privileges
to use the START_SEGMENTED_STRING statement.
Starts a stream of segmented string segments within a record
stream. Retrieving records with segmented string fields requires
a kind of "segment stream" within a record stream. This second
stream is normally established by nesting a special segmented
string FOR loop inside another FOR loop. However, in certain
cases, you cannot or may not want to use FOR loops (as in
Callable RDO programs).
The START_SEGMENTED_STRING statement is similar to the START_
STREAM statement: it starts a "stream" of string segments. You
do not use a FETCH statement to retrieve each segment. The PRINT
or GET statement retrieves the segment and advances the pointer
to the next segment. At the end of the stream, Oracle Rdb returns an
end-of-stream message, SEGSTR_EOF.
To end the stream, use the END_SEGMENTED_STREAM statement.
2 – Format
(B)0[m[4mSTART_SEGMENTED_STRING[m qwqqqqqqqqqqqqqqqqqqq>qqqqqqqqqqqqqqqqqwqk
mq> ( q> [4mTRANSACTION_HANDLE[m var q> ) qj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mq> ss-handle q> [4mUSING[m qwqqqqq>qqqqqqqqqwqq> context-var q> [4mIN[m qk
mqq> on-error qqj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mq> ss-field qqq>
2.1 – TRANSACTION_HANDLE
A keyword followed by a host language variable. A transaction
handle identifies each instance of a transaction. If you do not
declare the transaction handle explicitly, Oracle Rdb attaches an
internal identifier to the transaction.
If you start a transaction with a transaction handle, you must
include that handle in the START_SEGMENTED_STRING statement,
otherwise you get the following error:
RDB-E-EXCESS_TRANS, exceeded limit of !UL transactions !%S per
database attachment
In Callable RDO, use !VAL as a marker for host language
variables.
You can put parentheses around the host language variable name.
Normally, you do not need to use this argument. The ability to
declare a transaction handle is provided for compatibility with
other database products and future releases of Oracle Rdb.
2.2 – ss-handle
A host language variable or name used to refer to the segmented
string.
2.3 – on-error
The ON ERROR clause, which specifies host language statements or
Oracle Rdb data manipulation statements to be performed if an Oracle Rdb
error occurs. For more information, request HELP on ON_ERROR.
2.4 – context-var
A valid context variable. You use this context variable to
qualify the segments in the data manipulation statements that
follow.
2.5 – ss-field
A qualified field name that refers to a field defined with the
segmented string data type. Note that this field name must
be qualified by its own context variable. This second context
variable must match the variable declared in the START_STREAM
statement.
3 – Example
INVOKE DATABASE FILENAME 'PERSONNEL'
START_STREAM STREAM USING R IN RESUMES
FETCH STREAM
START_SEGMENTED_STRING STRING USING T IN R.RESUME
GET !VAL = T.RDB$VALUE;
!VAL = T.RDB$LENGTH
END_GET
END_SEGMENTED_STRING STRING
END_STREAM STREAM
This example:
o Starts a stream with the stream name STREAM. END_STREAM STREAM
closes the block.
o Uses the FETCH statement to move the stream pointer to the
first record in the relation RELNAME.
o Uses START_SEGMENTED_STRING to start a stream of segments from
the RESUME field of RESUMES. Note that the context variable
(R) on RESUME relates it to RESUMES.
o Uses GET to retrieve each segment and its length. The second
context variable relates each segment value to the segmented
string field, RESUME. The COBOL program displays the results.
o Encloses both the FETCH and the GET in loops. This outer and
inner looping structure is necessary to retrieve each record
and each segment within RESUME.