A special form of the STORE statement inserts a segment into a
segmented string. Storing a segmented string requires four steps:
1. Create a segmented string with the CREATE_SEGMENTED_STRING
statement. See HELP on CREATE_SEGMENT.
2. Store each segment using the syntax shown in the following
Format section. You must use the special Oracle Rdb value
expression RDB$VALUE or RDB$LENGTH as the segment name in
the USING clause.
3. Store the entire segmented string using the usual syntax for
storing records in relations. Use the segmented string handle,
declared in the CREATE_SEGMENTED_STRING statement, as the
value expression in this USING clause.
4. Close the segmented string.
1 – Format
(B)0[m[4mSTORE[m qqqk
lqqqqqj
mqq> context-var qqq> [4mIN[m qqqq> ss-handle qqqqk
lqqqqqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqqqqqj
mqq> [4mUSING[m qqqwqqqqqqqqqqqqqqwqqqqqqqk
mq> on-error qqj x
lqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqj
mqqwq> context-var . [4mRDB$VALUE[m qqwq> = qqq> value-expr qqk
mq> context-var . [4mRDB$LENGTH[m qj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqq<qqqqqqqqqqqqqqqqqqqqqqqqqqqj
mqq> [4mEND_STORE[m
1.1 – Arguments
context-var A valid context variable.
ss-handle A host language variable or name used to refer
to the segmented string. This handle must match
the one declared in the CREATE_SEGMENTED_STRING
statement.
on-error The ON ERROR clause, which specifies host language
or Oracle Rdb data manipulation statements to be
performed if an Oracle Rdb error occurs.
value-expr A valid Oracle Rdb value expression that specifies
the value to be stored.
2 – More
Oracle Rdb defines a special name to refer to the segments of a
segmented string. This value expression is equivalent to a field
name; it names the fields or segments of the string. Furthermore,
because segments can vary in length, Oracle Rdb also defines a name
for the length of a segment. These names are:
o RDB$VALUE
The value stored in a segment of a segmented string
o RDB$LENGTH
The length in bytes of a segment
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.
3 – Example
For a complete example, ask for HELP on CREATE_SEGMENT.