Allows you to store segments in a segmented string.

 Storing into a segmented string field requires two steps:


 1.  Storing the segments into the string

 2.  Storing the string field into the relation


 See the Examples subtopic for an example of storing segments in a
 segmented string.

Additional information available:

MoreFormatExamples

 If you have invoked a database, you have the necessary privileges to
 use the CREATE_SEGMENTED_STRING statement.

 You cannot modify a segmented string.

 When using the RDML and RDBPRE precompilers, be sure to define a
 sufficiently large value for the RDMS$BIND_SEGMENTED_STRING_BUFFER
 logical name.  An adequate buffer size is needed to store large
 segmented strings (using segmented string storage maps) in storage
 areas other than the default RDB$SYSTEM storage area.  The minimum
 acceptable value for the RDMS$BIND_SEGMENTED_STRING_BUFFER logical
 name must be equal to the sum of the length of the segments of the
 segmented string.  For example, if you know that the sum of the
 length of the segments is one megabyte, then 1,048,576 bytes is an
 acceptable value for this logical name.

 You must specify the logical name value because when RDML and RDBPRE
 precompilers store segmented strings, Rdb/VMS does not know which
 table contains the string until after the entire string is stored.
 Rdb/VMS buffers the entire segmented string, if possible, and does
 not store it until the STORE statement executes.

 If the segmented string remains buffered, it is stored in the
 appropriate storage area.  If the string is not buffered (because it
 is larger than the defined value for the logical name or the default
 value of 10,000 bytes), it is not stored in the default storage area
 and the following exception message is displayed:

 %RDB-F-IMP_EXC, facility-specific limit exceeded
 -RDMS-E-SEGSTR_AREA_INC, segmented string was stored incorrectly

 To avoid this error, set the value of the
 RDMS$BIND_SEGMENTED_STRING_BUFFER logical name to a sufficiently
 large value.  Note that a value of up to 500 MB can be specified for
 this logical name.

 You must execute this statement in a read/write transaction.  If
 there is no active transaction and you issue this statement, Rdb/VMS
 starts a read/write transaction implicitly.

 In order to store the segments into the segmented string, the string
 must have a name.  The CREATE_SEGMENTED_STRING statement initializes
 a segmented string and gives it a handle, so you can store segments
 into the field.  After you are finished storing segments, you store
 the entire field into the relation, using the handle to relate the
 newly built string to the field in which it belongs.  Finally, you
 use the END_SEGMENTED_STRING statement to close the block.  See the
 example.

 CREATESEGMENTEDSTRING  ──┬────────>────────┬─┐
                            └─> db-handle . ──┘ │
 ┌────────────────────<─────────────────────────┘
 └─> ss-handle ───┬───────>──────┬──────>
                  └─> on-error ──┘

Additional information available:

on-errorss-handledb-handle

 Specifies host language statements or Rdb/VMS data manipulation
 statements to be performed if an Rdb/VMS error occurs.  For more
 information, ask for HELP on ON_ERROR.

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

 A host language variable or name used to refer to the database.  You
 can specify a database handle as part of the segmented string handle
 if you have invoked more than one database.

 Example 1:

 The following example stores a segmented string:

 START_TRANSACTION READ_WRITE RESERVING
   RESUMES FOR EXCLUSIVE WRITE
 !
 ! Start a stream of segments.  Give the stream a name.
 !
 CREATE_SEGMENTED_STRING RESUME_HANDLE
 !
 ! Store the segments in the field.
 !
 STORE SEG IN RESUME_HANDLE USING
    SEG.RDB$VALUE =
    "This is the first line of an employee's resume."
 END_STORE
 !
 STORE SEG IN RESUME_HANDLE USING
    SEG.RDB$VALUE =
    "This is the second line of an employee's resume."
 END_STORE
 !
 STORE SEG IN RESUME_HANDLE USING
    SEG.RDB$VALUE =
    "This is the third line of an employee's resume."
 END_STORE
 !
 STORE SEG IN RESUME_HANDLE USING
    SEG.RDB$VALUE =
    "This is the fourth line of an employee's resume."
 END_STORE
 !
 ! Store the segmented string field in the relation.
 !
 STORE R IN RESUMES USING
     R.EMPLOYEE_ID = "00164";
     R.RESUME = RESUME_HANDLE
 END_STORE
 !
 END_SEGMENTED_STRING RESUME_HANDLE
 COMMIT

 This sequence of statements demonstrates the steps required to store
 a segmented string:

  o  CREATE_SEGMENTED_STRING starts a "stream" so that you can store
     the segments into the field.  The segmented string handle gives
     the stream a name.

  o  Each segmented string STORE statement stores a text string in a
     segment.  The context variable SEG relates the values being
     stored to the stream.

  o  The final STORE statement stores the segmented string field into
     the relation, along with the other field, ID_NUMBER.  Note that
     this STORE uses the segmented string handle as the value
     expression in the STORE assignment.

 In most cases, this set of statements would be part of a program that
 reads lines from a text file and stores each line in a segment of the
 segmented string field.


 Example 2

 The following program reads a file and loads it into the specified
 employee's RESUMES record in the PERSONNEL database.

 program STORE_RESUME

 !
 ! STORE RESUME
 ! This program reads a file and loads it into the specified
 ! employee's RESUMES record in the PERSONNEL database
 !
         option type = EXPLICIT
         declare long constant TRUE = -1%, FALSE = 0%
         declare                                                 &
             string                                              &
                 employee_id, resume_file, text_line,            &
                 last_name, first_name,                          &
             long                                                &
                 found, line_count

 &RDB&   INVOKE DATABASE FILENAME "DB$:PERSONNEL31"

         print "** Personnel RESUME Load **"
         when error in
             input "Enter EMPLOYEE_ID"; employee_id
         use
             print "Program terminated"
             continue END_PROGRAM
         end when

 &RDB&   START_TRANSACTION READ_WRITE
 &RDB&   FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = employee_id
 &RDB&       GET
 &RDB&           last_name = E.LAST_NAME;
 &RDB&           first_name = E.FIRST_NAME;
 &RDB&       END_GET
             found = TRUE
 &RDB&   END_FOR

         if not found then
             print "Error - employee " + employee_id + " not found"
             exit program
         else
             !
             ! Display the employees name
             !
             print "Loading RESUME for employee " +              &
                   TRM$(first_name) + ", " + TRM$(last_name)

             !
             ! Read the name of the resume source file
             !
         GET_NAME:
             when error in
                 input "Enter the resume file name"; resume_file
                 open resume_file for input as file #1,          &
                     organization sequential, recordtype ANY
             use
                 if err = 11% then
                     print "Program terminated"
                     continue END_PROGRAM
                 else
                     print "Error - " + RIGHT(ERT$(err),2%)
                     continue GET_NAME
                 end if
             end when

 &RDB&       CREATE_SEGMENTED_STRING RES

             !
             ! Loop and read each line from the resume, and store
                        ! it in the segmented string
             !
             line_count = 0%
             while TRUE  ! indefinite loop
                 when error in
                     linput #1, text_line
                 use
                     continue EOF
                 end when
                 text_line = TRM$(text_line)
                 line_count = line_count + 1%
 &RDB&           STORE R IN RES USING
 &RDB&               R.RDB$VALUE = text_line;
 &RDB&               R.RDB$LENGTH = LEN(text_line)
 &RDB&           END_STORE
             next
     EOF:
             close #1
             print line_count; "lines stored in resume."
 &RDB&       STORE RS IN RESUMES USING
 &RDB&           RS.EMPLOYEE_ID = employee_id;
 &RDB&           RS.RESUME = RES
 &RDB&       END_STORE
 &RDB&       END_SEGMENTED_STRING RES
         end if

 &RDB&   commit
 &RDB&   finish

     END_PROGRAM:

 end program