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.
1 – 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)0[m[4mCREATE_SEGMENTED_STRING[m qqwqqqqqqqq>qqqqqqqqwqk
mq> db-handle . qqj x
lqqqqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqqqqqqqqj
mq> ss-handle qqqwqqqqqqq>qqqqqqwqqqqqq>
mq> on-error qqj
2.1 – 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.
2.2 – ss-handle
A host language variable or name used to refer to the segmented
string.
2.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.
3 – 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