Allows you to store segments in a segmented string.

 Storing into a segmented string field requires two steps:

  o  Storing the segments into the string
  o  Storing the string field into the relation


 Example

    RDO>  CREATE_SEGMENTED_STRING RESUME_HANDLE

Additional information available:

MoreFormatExamples

 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.

 You cannot modify a segmented string.

 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