Large Object field processing for non-FILEORG X'100' files: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "<div class="toclimit-3"> ==Overview== <p> <var class="product">Model 204</var> Version 7.5 introduced the X'0100' switch on the FILEORG parameter which provides for a va...")
 
 
(15 intermediate revisions by 3 users not shown)
Line 3: Line 3:
==Overview==
==Overview==
<p>
<p>
<var class="product">Model&nbsp;204</var> Version 7.5 introduced the X'0100' switch on the FILEORG parameter which provides for a variety of extended features, including a simpler syntax for ADDing, CHANGEing and DELETEing Large Object fields (fields with BLOB or CLOB attributes). Prior to FILEORG=X'0100', working with Large Objects requires the use of a 'universal buffer'. This page describes this syntax, which is deprecated for X'0100' files.</p>
<var class="product">Model&nbsp;204</var> Version 7.5 introduced the X'100' bit on the <var>[[FILEORG parameter|FILEORG]]</var> parameter which provides for a variety of extended features, including a simpler syntax for adding, changing and deleting [[Field design#BLOB, CLOB, and MINLOBE attributes|Large Object fields]] (fields with a <var>BLOB</var> or <var>CLOB</var> attribute). Without <var>FILEORG</var> X'100', working with Large Objects requires the use of a <b>Universal Buffer</b>. The Universal Buffer is a one-per-user, temporary storage area that automatically expands to accommodate its data contents. </p>
 
This page describes the Universal Buffer syntax, which is deprecated for X'100' files but required for earlier-version files that use <var>BLOB</var> or <var>CLOB</var> fields. For LOB syntax used in X'100' files, see [[Data maintenance]].
 
===Data maintenance statements===
===Data maintenance statements===
<p>
<p>
Large Object processing for pre-FILEORG X'0100' files:</p>
Special processing necessary for non-<var>FILEORG</var> X'100' files with LOB fields is needed for:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 15: Line 17:
   
   
<tr>
<tr>
<td><var>ADD</var> </td>
<td><var>Add</var> </td>
<td>Place a new field-value pair on a record.</td>
<td>Place a new field-value pair on a record.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<td><var>CHANGE</var> </td>
<td><var>Change</var> </td>
<td>Alter the value of fields in a record.</td>
<td>Alter the value of fields in a record.</td>
</tr>
</tr>


<tr>
<tr>
<td><var>STORE RECORD</var> </td>
<td><var>Store Record</var> </td>
<td>Put a new record to a <var class="product">Model&nbsp;204</var> file.</td>
<td>Add a new record to a <var class="product">Model&nbsp;204</var> file.</td>
</tr>
</tr>
</table>
</table>


===Using FOR EACH RECORD loops===
===Using For Each Record loops===
<p>
<p>
The User Language data maintenance statements handle one record at a time, therefore the data maintenance statements are always part of a FOR EACH RECORD loop. The data maintenance may involve a field-value pair for the field.</p>
Since the <var class="product">SOUL</var> data maintenance statements handle one record at a time, the data maintenance statements are always part of a <var>[[For Each Record statement|For Each Record]]</var> loop. The data maintenance may involve a field-value pair for the field.</p>
 
===Data used in examples in this topic===
===Data used in examples in this topic===
<p>
<p>
Line 44: Line 45:
MODEL = FOCUS              MODEL = MUSTANG
MODEL = FOCUS              MODEL = MUSTANG
</p>
</p>
 
==ADD statement==
==Adding Large Object fields==
<p>
The <var>ADD</var> statement adds a new occurrence of a field and/or value to a record.</p>
===Syntax===
<p>
<p>
The basic format of the ADD statement is:</p>
Use the following special syntax of the <var>[[Add statement|Add]]</var> statement to add a Large Object field to a record: </p>
<p class="syntax">ADD <span class="term">fieldname</span> = {<span class="term">value</span> <span class="squareb">|</span> (<span class="term">expression</span>)}
{{Template:Add lob-fieldname statement syntax}}
</p>
<p>
Where:</p>
<p>
<span class="term">fieldname</span> identifies the field in a record.</p>
<p>
<span class="term">value</span> specifies the value you want to store.</p>
<p>
(<span class="term">expression</span>) can be used in place of value to specify the resolved value at the time of evaluation. (<span class="term">expression</span>) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</p>
====Large Object field syntax====
<p class="syntax">ADD <span class="term">lob-name</span>=BUFFER,<span class="term">position</span>,<span class="term">length</span> [RESERVE <span class="term">n</span> [BYTES]]
</p>
<p>
<p>
Where:</p>
Where:</p>
<ul>
<ul>
<li><var class="term">lob-name</var> specifies the field name of the Large Object data.  
<li><var class="term">lob-fieldname</var> specifies the field name of the Large Object data.  
<p class="note"><b>Note: </b>you cannot use subscripts on ADD statements.</p>
<p class="note"><b>Note:</b> Subscripts are not valid on <var>Add</var> statements.</p>
</li>
</li>


<li>BUFFER specifies the Universal Buffer</li>
<li><var>Buffer</var> specifies the Universal Buffer. </li>
   
   
<li><var class="term">position</var> is a positive number specifying the offset of the first character in the buffer or Large Object data. If the position is set to a negative value, an error occurs. The position can be a %variable or a constant.</li>
<li><var class="term">position</var> is a positive number specifying the offset of the first character in the buffer or Large Object data. If the position is set to a negative value, an error occurs. The position can be a %variable or a constant. </li>
   
   
<li><var class="term">length</var> is a positive number specifying the length to move. The length can be a %variable or a constant.</li>
<li><var class="term">length</var> is a positive number specifying the length to move. The length can be a %variable or a constant. </li>
   
   
<li>RESERVE <var class="term">n</var> specifies a positive number of bytes to reserve for the Large Object field value. The number of RESERVE bytes is always greater than or equal to maximum length of Large Object. </li>
<li><var>Reserve <i>n</i></var> specifies a positive number of bytes to reserve for the Large Object field value. The number of <var>Reserve</var> bytes is always greater than or equal to maximum length of Large Object. </li>
   
   
<li>BYTES, optional, specifies that <span class="term">n</span> applies to bytes.  
<li><var>Bytes</var>, optional, specifies that <span class="term">n</span> applies to bytes. </li>
</li>
</ul>
</ul>
   
   
<b>Example</b>
===Example===
<p class="code">BEGIN
<p class="code">BEGIN
IMAGE XYZ
IMAGE XYZ
Line 113: Line 96:
</p>
</p>
<p>
<p>
This code would result in adding a large object field to each record containing the text "CURREC" followed by the internal record number and this output:</p>
This request adds a Large Object field to each record containing the text <code>CURREC</code> followed by the internal record number and this output:</p>
<p class="code">A99999998E CURREC0
<p class="output">A99999998E CURREC0
X99999999Z CURREC1
X99999999Z CURREC1
</p>
</p>
   
   
===Usage===
===Usage===
<p>
<p>
For Large Object data, a compiler error is issued for ADD (and STORE) statements if the context to the right of the equal sign (=) is not a BUFFER reference.</p>
For Large Object data, a compiler error is issued for <var>Add</var> (and <var>Store</var>) statements if the context to the right of the equal sign (<tt>=</tt>) is not a <var>Buffer</var> reference:</p>
<p class="code">M204.0037: INVALID SYNTAX
<p class="code">M204.0037: Invalid syntax
</p>
</p>


====Large Object field syntax for CHANGE====
==Changing Large Object fields==
<p>
<p>
To change large object fields with the CHANGE statement use the following syntax:</p>
To change large object fields, use the <var>Change</var> statement with the following syntax:</p>
<p class="syntax">CHANGE  <span class="term">lob-fieldname,position1,length</span> TO <span class="term">BUFFER position2,length</span>
{{Template:Change lob-fieldname statement syntax}}
</p>
<ul>
<ul>
<li><var class="term">lob-fieldname</var> specifies the name of the field</li>
<li><var class="term">lob-fieldname</var> specifies the name of the field</li>
Line 138: Line 119:
The source and target lengths must be equal.  
The source and target lengths must be equal.  
<p>
<p>
If <var class="term">position</var> plus <var class="term">length</var> minus one exceeds the current length of the LOB field, the intervening bytes are filled with binary 0. If the file has FILEORG X'100' on, then any final length of the LOB field is allowed. Otherwise extending a LOB field requires that the final length must fit within the RESERVE clause length specified when the LOB field was added.</p>
If <var class="term">position</var> plus <var class="term">length</var> minus one exceeds the current length of the LOB field, the intervening bytes are filled with binary 0. If the file has the <var>FILEORG</var> X'100' bit set, then any final length of the LOB field is allowed. Otherwise extending a LOB field requires that the final length must fit within the <var>Reserve</var> clause length specified when the LOB field was added.</p>
<p>
<p>
For example, if the buffer contains "ABCDEFGHIJKL" and the field is initially stored with:</p>
For example, if the buffer contains <code>ABCDEFGHIJKL</code> and the field is initially stored with:</p>
<p class="code">ADD LOB.FLD=BUFFER,1,3 RESERVE 500 BYTES
<p class="code">ADD LOB.FLD=BUFFER,1,3 RESERVE 500 BYTES
</p>
</p>
<p>
<p>
The field would contain "ABC". If it was subsequently changed as follows:</p>
The field would contain <code>ABC</code>. If it was subsequently changed as follows:</p>
<p class="code">CHANGE LOB.FLD,5,10 TO BUFFER,1,10
<p class="code">CHANGE LOB.FLD,5,10 TO BUFFER,1,10
</p>
</p>
<p>
<p>
The field would then contain "ABC ABCDEFGHIJ" with position 4 being a binary zero. </p>
The field would then contain <code>ABC ABCDEFGHIJ</code> with position 4 being a binary zero. </p></li>
</li>


<li>TO BUFFER specifies the Universal Buffer. You can use BUFFER only in conjunction with a Large Object field.  
<li><var>To Buffer</var> specifies the Universal Buffer. You can use <var>Buffer</var> only in conjunction with a Large Object field. </li>
</li>
</ul>
</ul>
   
   
====Example====
===Example===
 
<p class="code">BEGIN
<p class="code">BEGIN
IMAGE XYZ
IMAGE XYZ
Line 183: Line 161:
</p>
</p>
<p>
<p>
This code results in changing the large object field in each record to the text "This is the data for VIN" followed by the VIN field and this output. </p>
This code results in changing the large object field in each record to the text <code>This is the data for VIN</code> followed by the <code>VIN</code> field and this output:</p>
<p class="code">A99999998E This is the data for VIN A99999998E
<p class="output">A99999998E This is the data for VIN A99999998E
X99999999Z This is the data for VIN X99999999Z
X99999999Z This is the data for VIN X99999999Z
</p>
</p>
   
   
===Usage===
===Usage===
<p>
<ul>
If you issue a CHANGE statement on a Large Object field to a record that does not contain the field, nothing happens. Unlike a non-Large Object field, a new occurrence of the field is not added to the record.</p>
<li>If you issue a <var>Change</var> statement on a Large Object field to a record that does not contain the field, nothing happens. Unlike a non-Large Object field, a new occurrence of the field is not added to the record.</li>
<p>
 
Extending a LOB field requires that the final length must fit within the RESERVE clause length specified when the LOB field was added.</p>
<li>Extending a LOB field requires that the final length must fit within the <var>Reserve</var> clause length specified when the LOB field was added.
<p class="note"><b>Note:</b> You cannot change the number of RESERVE bytes. Furthermore, facilities are not available to delete a portion of data or to insert data: for example, to replace 10 bytes with 25 bytes within Large Object data. When an attempt to insert or delete data is made the following error message is issued:</p>
<blockquote class="note">
<p><b>Note:</b> You cannot change the number of <var>Reserve</var> bytes. Furthermore, facilities are not available to delete a portion of data or to insert data: for example, to replace 10 bytes with 25 bytes within Large Object data. When an attempt to insert or delete data is made the following error message is issued:</p>
<p class="code">M204.2693: SOURCE AND TARGET LENGTH MUST BE EQUAL
<p class="code">M204.2693: SOURCE AND TARGET LENGTH MUST BE EQUAL
</p>
</p>
<p>
</blockquote></li>
All Large Object data implicitly has the contiguous characteristic. A User Language procedure can store some amount of initial data and then extend the data up to the RESERVE number of bytes with subsequent CHANGE statements. For example:</p>
 
<li>All Large Object data implicitly has the contiguous characteristic. A SOUL procedure can store some amount of initial data and then extend the data up to the <var>Reserve</var> number of bytes with subsequent <var>Change</var> statements. For example:
<p class="code">FR
<p class="code">FR
   * add initial 10 bytes:
   * add initial 10 bytes:
Line 211: Line 191:
   PRINT 'LOBLEN' AND $LOBLEN(LOB.FLD)
   PRINT 'LOBLEN' AND $LOBLEN(LOB.FLD)
END
END
</p>
</p></li>
 
</ul>
 
===STORE RECORD syntax for Large Object fields===
<p>
Binary Large Objects &mdash; fields defined with a BLOB or CLOB attribute (often referred to collectively as LOBs) &mdash; are stored in Table E, and they can hold content longer than the 255 limit of regular <var class="product">Model&nbsp;204</var> fields.  They are useful for holding blocks of text, images, documents, etc.  Prior to the <var class="product">Model&nbsp;204</var> Version 7.5 introduction of X'0100' files (see the <var>[[FILEORG parameter|FILEORG]]</var> parameter for more information), LOB fields required a special STORE syntax referencing the "universal buffer".</p>


<p>As of <var class="product">Model&nbsp;204</var> V7.5, LOB fields can be stored using normal STORE syntax, typically with a [[Longstrings|Longstring]] variable holding the content:</p>
==Storing Large Object fields==
 
<p class="code">%myImage is longString
...
store record
  rectype="IMAGE"
  name="sunset.jpg"
  image=%myImage
end store 
</p>
<p>
<p>
Prior to <var class="product">Model&nbsp;204</var> V7.5, or in lieu of the X'0100' FILEORG bit being set, LOB fields require the use of the universal buffer, and special syntax to access the buffer.</p>
To store a Large Object (prior to <var class="product">Model&nbsp;204</var> V7.5 or absent the X'100' <var>FILEORG</var> bit), LOB fields require the Universal Buffer and this <var>[[STORE RECORD statement|Store Record]]</var> syntax to access the buffer:</p>
<p class="syntax">STORE RECORD
<p class="syntax">Store Record
   <span class="term">lob-name</span>=BUFFER,<span class="term">position</span>,<span class="term">length</span> [RESERVE <span class="term">n</span> [BYTES]]
   <span class="term">lob-name</span>=Buffer,<span class="term">position</span>,<span class="term">length</span> [Reserve <span class="term">n</span> [Bytes]]
   .
   .
   .
   .
   .
   .
END_STORE [<span class="term">label</span>]
End Store [<span class="term">label</span>]
</p>
</p>
<p>
<p>
Line 241: Line 208:
<ul>
<ul>
<li><var class="term">lob-name</var> specifies the field name of the Large Object field.
<li><var class="term">lob-name</var> specifies the field name of the Large Object field.
<p class="note"><b>Note: </b>you cannot use subscripts on statements for any field type.</p>
<p class="note"><b>Note: </b>you cannot use subscripts on statements for any field type.</p></li>
</li>


<li><var>BUFFER</var> specifies the Universal Buffer</li>
<li><var>Buffer</var> specifies the Universal Buffer</li>
   
   
<li><var class="term">position</var> is a positive number specifying the offset of the first character in the buffer. If the position is less than one, an error occurs. The position can be a %variable or a constant.</li>
<li><var class="term">position</var> is a positive number specifying the offset of the first character in the buffer. If the position is less than one, an error occurs. The position can be a %variable or a constant.</li>
Line 250: Line 216:
<li><var class="term">length</var> is a positive number specifying the length to move. The length can be a %variable or a constant.</li>
<li><var class="term">length</var> is a positive number specifying the length to move. The length can be a %variable or a constant.</li>
   
   
<li><var>RESERVE</var> ><var class="term">n</var> specifies a positive number of bytes to reserve for the Large Object field value. The number of bytes is always greater than or equal to <var>[[$LOBLEN]]</var>. </li>
<li><var>Reserve</var> <var class="term">n</var> specifies a positive number of bytes to reserve for the Large Object field value. The number of bytes is always greater than or equal to <var>[[$LobLen]]</var>. </li>
   
   
<li><var>BYTES</var>, optional, specifies that <var class="term">n</var> applies to bytes. </li>
<li><var>Bytes</var>, optional, specifies that <var class="term">n</var> applies to bytes. </li>
</ul>
</ul>
   
   
====Examples====
===Example===
<p class="code">BEGIN
STORE RECORD
  NAME = JEAN ANDERSON
  SALARY = 30000
  POSITION = CHEMIST
END STORE
END
</p>
<b>Using the THEN CONTINUE statement</b>
<p class="code">%COLOR = 'BLUE'
STORE RECORD
  MODEL = %MODEL
  THEN CONTINUE
  FR WHERE RECTYPE = 'TABLE' AND COLOR = %COLOR
      %CODE = COLOR_CODE
  END FOR
  ADD COLOR_CODE=%CODE
  PAI
END STORE
</p>
<b>Storing Large Object data</b>
<p class="code">STORE RECORD
<p class="code">STORE RECORD
   NOVEL=BUFFER,%POSITION,%LENGTH
   NOVEL=BUFFER,%POSITION,%LENGTH
Line 286: Line 229:
</p>
</p>


====Handling Large Object data====
===Usage===
<p>
<p>
When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields &mdash; unless the field is preallocated.
When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields &mdash; unless the field is preallocated.
Line 292: Line 235:
for a description of how to build a Large Object data descriptor.</p>
for a description of how to build a Large Object data descriptor.</p>
<p>
<p>
The following compiler error is issued when the right side of the equal sign is expected to contain a <var>BUFFER</var> expression and it does not.</p>
The following compiler error is issued when the right side of the equal sign is expected to contain a <var>Buffer</var> expression and it does not:</p>
<p class="code">M204.0037: INVALID SYNTAX
<p class="code">M204.0037: Invalid syntax
</p>
</p>
   
   
[[Category:SOUL]]
[[Category:SOUL]]

Latest revision as of 17:39, 11 May 2018

Overview

Model 204 Version 7.5 introduced the X'100' bit on the FILEORG parameter which provides for a variety of extended features, including a simpler syntax for adding, changing and deleting Large Object fields (fields with a BLOB or CLOB attribute). Without FILEORG X'100', working with Large Objects requires the use of a Universal Buffer. The Universal Buffer is a one-per-user, temporary storage area that automatically expands to accommodate its data contents.

This page describes the Universal Buffer syntax, which is deprecated for X'100' files but required for earlier-version files that use BLOB or CLOB fields. For LOB syntax used in X'100' files, see Data maintenance.

Data maintenance statements

Special processing necessary for non-FILEORG X'100' files with LOB fields is needed for:

Statement Action
Add Place a new field-value pair on a record.
Change Alter the value of fields in a record.
Store Record Add a new record to a Model 204 file.

Using For Each Record loops

Since the SOUL data maintenance statements handle one record at a time, the data maintenance statements are always part of a For Each Record loop. The data maintenance may involve a field-value pair for the field.

Data used in examples in this topic

Each statement is discussed separately on the pages that follow. To illustrate their usage, assume that the following two records have been stored:

VIN = A99999998E VIN = X99999999Z MAKE = FORD MAKE = FORD COLOR = GREEN COLOR = RED YEAR = 88 YEAR = 04 MODEL = FOCUS MODEL = MUSTANG

Adding Large Object fields

Use the following special syntax of the Add statement to add a Large Object field to a record:

Add lob-fieldname=Buffer,position,length [Reserve n [Bytes]]

Where:

  • lob-fieldname specifies the field name of the Large Object data.

    Note: Subscripts are not valid on Add statements.

  • Buffer specifies the Universal Buffer.
  • position is a positive number specifying the offset of the first character in the buffer or Large Object data. If the position is set to a negative value, an error occurs. The position can be a %variable or a constant.
  • length is a positive number specifying the length to move. The length can be a %variable or a constant.
  • Reserve n specifies a positive number of bytes to reserve for the Large Object field value. The number of Reserve bytes is always greater than or equal to maximum length of Large Object.
  • Bytes, optional, specifies that n applies to bytes.

Example

BEGIN IMAGE XYZ BUFF_DATA IS STRING LEN 200 END IMAGE IDENTIFY IMAGE XYZ * add LOB field with "CURRECn" to the records: FOR EACH RECORD * enter data into image item: %XYZ:BUFF_DATA = 'CURREC' WITH $CURREC * write image on the buffer: WRITE IMAGE XYZ ON BUFFER POSITION=1 MAXLEN=200 * add LOB field from buffer contents: ADD MY.LOB.FIELD=BUFFER,1,10 RESERVE 200 BYTES END FOR * print LOB data: FOR EACH RECORD * place LOB data into the buffer: BUFFER,1,200=MY.LOB.FIELD,1,200 * place contents of the buffer into image: READ IMAGE XYZ FROM BUFFER * print LOB data that has been placed into the buffer: PRINT VIN AND %XYZ:BUFF_DATA END

This request adds a Large Object field to each record containing the text CURREC followed by the internal record number and this output:

A99999998E CURREC0 X99999999Z CURREC1

Usage

For Large Object data, a compiler error is issued for Add (and Store) statements if the context to the right of the equal sign (=) is not a Buffer reference:

M204.0037: Invalid syntax

Changing Large Object fields

To change large object fields, use the Change statement with the following syntax:

Change lob-fieldname,position1,length To Buffer,position2,length[Reserve n [Bytes]]

  • lob-fieldname specifies the name of the field
  • position, position1 and position2 are positive numbers specifying the offset of the first character in the buffer or Large Object data. If position, position1, or position2 is set to a negative value, an error occurs. Any positions can be a %variable or a constant.
  • length is a positive number specifying the length to move. The length can be a %variable or a constant. The source and target lengths must be equal.

    If position plus length minus one exceeds the current length of the LOB field, the intervening bytes are filled with binary 0. If the file has the FILEORG X'100' bit set, then any final length of the LOB field is allowed. Otherwise extending a LOB field requires that the final length must fit within the Reserve clause length specified when the LOB field was added.

    For example, if the buffer contains ABCDEFGHIJKL and the field is initially stored with:

    ADD LOB.FLD=BUFFER,1,3 RESERVE 500 BYTES

    The field would contain ABC. If it was subsequently changed as follows:

    CHANGE LOB.FLD,5,10 TO BUFFER,1,10

    The field would then contain ABC ABCDEFGHIJ with position 4 being a binary zero.

  • To Buffer specifies the Universal Buffer. You can use Buffer only in conjunction with a Large Object field.

Example

BEGIN IMAGE XYZ BUFF_DATA IS STRING LEN 200 END IMAGE IDENTIFY IMAGE XYZ IN JUNK FOR EACH RECORD * place LOB data into the buffer: %XYZ:BUFF_DATA = 'This is the data for VIN ' WITH VIN * write image on the buffer: WRITE IMAGE XYZ ON BUFFER POSITION=1 MAXLEN=200 * change the LOB field to the contents of the buffer: CHANGE MY.LOB.FIELD,1,50 TO BUFFER,1,50 END FOR * print LOB data: FOR EACH RECORD * place LOB data into the buffer: BUFFER,1,200=MY.LOB.FIELD,1,200 * place contents of the buffer into image: READ IMAGE XYZ FROM BUFFER * print LOB data that has been placed into the buffer: PRINT VIN AND %XYZ:BUFF_DATA END

This code results in changing the large object field in each record to the text This is the data for VIN followed by the VIN field and this output:

A99999998E This is the data for VIN A99999998E X99999999Z This is the data for VIN X99999999Z

Usage

  • If you issue a Change statement on a Large Object field to a record that does not contain the field, nothing happens. Unlike a non-Large Object field, a new occurrence of the field is not added to the record.
  • Extending a LOB field requires that the final length must fit within the Reserve clause length specified when the LOB field was added.

    Note: You cannot change the number of Reserve bytes. Furthermore, facilities are not available to delete a portion of data or to insert data: for example, to replace 10 bytes with 25 bytes within Large Object data. When an attempt to insert or delete data is made the following error message is issued:

    M204.2693: SOURCE AND TARGET LENGTH MUST BE EQUAL

  • All Large Object data implicitly has the contiguous characteristic. A SOUL procedure can store some amount of initial data and then extend the data up to the Reserve number of bytes with subsequent Change statements. For example:

    FR * add initial 10 bytes: ADD LOB.FLD=BUFFER,1,10 RESERVE 200 BYTES * add increments of 10 bytes at * positions 11, 21, 31, 41 * moving data from the buffer to the field FOR %X FROM 1 TO 4 %Y = %X WITH '1' CHANGE LOB.FLD,%Y,10 TO BUFFER,%Y,10 END FOR PAI PRINT 'LOBLEN' AND $LOBLEN(LOB.FLD) END

Storing Large Object fields

To store a Large Object (prior to Model 204 V7.5 or absent the X'100' FILEORG bit), LOB fields require the Universal Buffer and this Store Record syntax to access the buffer:

Store Record lob-name=Buffer,position,length [Reserve n [Bytes]] . . . End Store [label]

Where:

  • lob-name specifies the field name of the Large Object field.

    Note: you cannot use subscripts on statements for any field type.

  • Buffer specifies the Universal Buffer
  • position is a positive number specifying the offset of the first character in the buffer. If the position is less than one, an error occurs. The position can be a %variable or a constant.
  • length is a positive number specifying the length to move. The length can be a %variable or a constant.
  • Reserve n specifies a positive number of bytes to reserve for the Large Object field value. The number of bytes is always greater than or equal to $LobLen.
  • Bytes, optional, specifies that n applies to bytes.

Example

STORE RECORD NOVEL=BUFFER,%POSITION,%LENGTH [RESERVE n [BYTES]] AUTHOR_PIC=BUFFER,%POSITION2,%LENGTH2 END STORE

Usage

When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields — unless the field is preallocated. See Building a Large Object descriptor for a description of how to build a Large Object data descriptor.

The following compiler error is issued when the right side of the equal sign is expected to contain a Buffer expression and it does not:

M204.0037: Invalid syntax