View source for Large Object field processing for non-FILEORG X'100' files

<div class="toclimit-3">

==Overview==
<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===
<p>
Special processing necessary for non-<var>FILEORG</var> X'100' files with LOB fields is needed for:</p>
<table>
<tr class="head">
<th>Statement </th>
<th> Action</th>
</tr>
 
<tr>
<td><var>Add</var> </td>
<td>Place a new field-value pair on a record.</td>
</tr>
 
<tr>
<td><var>Change</var> </td>
<td>Alter the value of fields in a record.</td>
</tr>

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

===Using For Each Record loops===
<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===
<p>
Each statement is discussed separately on the pages that follow. To illustrate their usage, assume that the following two records have been stored:</p>
<p class="code">VIN = A99999998E           VIN = X99999999Z
MAKE = FORD                MAKE = FORD
COLOR = GREEN              COLOR = RED
YEAR = 88                  YEAR = 04
MODEL = FOCUS              MODEL = MUSTANG
</p>

==Adding Large Object fields==
<p>
Use the following special syntax of the <var>[[Add statement|Add]]</var> statement to add a Large Object field to a record: </p>
{{Template:Add lob-fieldname statement syntax}} 
<p>
Where:</p>
<ul>
<li><var class="term">lob-fieldname</var> specifies the field name of the Large Object data. 
<p class="note"><b>Note:</b> Subscripts are not valid on <var>Add</var> statements.</p>
</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">length</var> is a positive number specifying the length to move. The length can be a %variable or a constant. </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><var>Bytes</var>, optional, specifies that <span class="term">n</span> applies to bytes. </li>
</ul>
 
===Example===
<p class="code">BEGIN
IMAGE XYZ
  BUFF_DATA IS STRING LEN 200
END IMAGE
IDENTIFY IMAGE XYZ
 
<b></b>* 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
 
<b></b>* 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
</p>
<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="output">A99999998E CURREC0
X99999999Z CURREC1
</p>
 
===Usage===
<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>

==Changing Large Object fields==
<p>
To change large object fields, use the <var>Change</var> statement with the following syntax:</p>
{{Template:Change lob-fieldname statement syntax}}
<ul>
<li><var class="term">lob-fieldname</var> specifies the name of the field</li>
 
<li><var class="term">position, position1</var> and <var class="term">position2</var> are positive numbers specifying the offset of the first character in the buffer or Large Object data. If <var class="term">position, position1,</var> or <var class="term">position2</var> is set to a negative value, an error occurs. Any positions 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.
The source and target lengths must be equal. 
<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>
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>
<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>
<p>
The field would then contain <code>ABC ABCDEFGHIJ</code> with position 4 being a binary zero. </p></li>

<li><var>To Buffer</var> specifies the Universal Buffer. You can use <var>Buffer</var> only in conjunction with a Large Object field. </li>
</ul>
 
===Example===
<p class="code">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
 
<b></b>* 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
</p>
<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="output">A99999998E This is the data for VIN A99999998E
X99999999Z This is the data for VIN X99999999Z
</p>
 
===Usage===
<ul>
<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>

<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.
<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>
</blockquote></li>

<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
   * 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
</p></li>
</ul>

==Storing Large Object fields==
<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
   <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>]
</p>
<p>
Where:</p>
<ul>
<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></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">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>Bytes</var>, optional, specifies that <var class="term">n</var> applies to bytes. </li>
</ul>
 
===Example===
<p class="code">STORE RECORD
  NOVEL=BUFFER,%POSITION,%LENGTH
 [RESERVE n [BYTES]]
 AUTHOR_PIC=BUFFER,%POSITION2,%LENGTH2
END STORE
</p>

===Usage===
<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.
See [[File Load utility#Building a Large Object descriptor|Building a Large Object descriptor]]
for a description of how to build a Large Object data descriptor.</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>
<p class="code">M204.0037: Invalid syntax
</p>
 
[[Category:SOUL]]