START_SEGMENTED_STRING

 Starts a stream of segmented string segments within a record stream.
 To end the stream, use the END_SEGMENTED_STRING statement.

Additional information available:

MoreFormatExample

 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, Rdb/VMS returns an end-of-stream
 message, SEGSTR_EOF.

 To end the stream, use the END_SEGMENTED_STREAM statement.

 STARTSEGMENTEDSTRING ─┬───────────────────>─────────────────┬─┐
                         └─> ( ─> 
T
R
A
N
S
A
C
T
I
O
N
H
A
N
D
L
E var ─> ) ─┘ │
 ┌─────────────────────────────<─────────────────────────────────┘
 └─> ss-handle ─> 
U
S
I
N
G ─┬─────>─────────┬──> context-var ─> 
I
N ─┐
                         └──> on-error ──┘                       │
 ┌─────────────────────────────<─────────────────────────────────┘
 └─> ss-field ───>

Additional information available:

TRANSACTION_HANDLE

ss-handleon-errorcontext-varss-field

 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, Rdb/VMS 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 Rdb/VMS.

 A host language variable or name used to refer to the segmented
 string.

 The ON ERROR clause, which specifies host language statements or
 Rdb/VMS data manipulation statements to be performed if an Rdb/VMS
 error occurs.  For more information, request HELP on ON_ERROR.

 A valid context variable.  You use this context variable to qualify
 the segments in the data manipulation statements that follow.

 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.

 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.

 For a more extensive example, see the VAX Rdb/VMS RDO Reference
 Manual.