1 CREATE_SEGMENT 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 See the Examples subtopic for an example of storing segments in a segmented string. 2 More 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, Oracle Rdb does not know which table contains the string until after the entire string is stored. Oracle Rdb 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, Oracle Rdb 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. 2 Format (B)0CREATE_SEGMENTED_STRING qqwqqqqqqqq>qqqqqqqqwqk mq> db-handle . qqj x lqqqqqqqqqqqqqqqqqqqq ss-handle qqqwqqqqqqq>qqqqqqwqqqqqq> mq> on-error qqj 3 on-error Specifies host language statements or Oracle Rdb data manipulation statements to be performed if an Oracle Rdb error occurs. For more information, ask for HELP on ON_ERROR. 3 ss-handle A host language variable or name used to refer to the segmented string. 3 db-handle 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. 2 Examples 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