Table E and FILEORG X'100' files (File architecture): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
<span class="pageSubtitle">Holds Large Object Data (BLOBs and CLOBs)</span>  
<span class="pageSubtitle">Holds Large Object data (BLOBs and CLOBs)</span>  


When FILEORG x'100' is set on a file, large object data storage is enabled by reorganizing or [[CREATE command: File|creating]] a file with [[ESIZE parameter|ESIZE]] greater than 0, and then [[DEFINE FIELD command|defining one or more fields]] with an attribute of [[Field design (File management)#BLOB.2C CLOB and MINLOBE attributes|CLOB or BLOB]]. (The file must have an ESIZE for its fields to be defined as CLOB or BLOB.)
Storage and manipulation of Large Objects (LOBs) differs greatly depending on whether <var>FILEORG</var> X'100' is set for the file. This page discusses working with <var>FILEORG</var> X'100' files; for a parallel discussion of working with LOBs in files where FILEORG X'100' is ''not'' set, see [[Table E non X'100' (File architecture)]]. For a summary of the differences between working with LOB data in files where <var>FILEORG</var> X'100' is set and files where it is not, see [[Table E (File architecture)]].  


Available as of Model 204 V7.5.  
When the <var>[[FILEORG parameter|FILEORG]]</var> X'100' bit is set on a file, you enable large object data storage by:
<ol>
<li>Reorganizing or [[CREATE command: File|creating]] a file with <var>[[ESIZE parameter|ESIZE]]</var> greater than 0.


==Summary==
<li>[[DEFINE FIELD command|Defining one or more fields]] with an attribute of [[Field design (File management)#BLOB.2C CLOB and MINLOBE attributes|CLOB or BLOB]]. (The file must have an <var>ESIZE</var> for its fields to be defined as <var>CLOB</var> or <var>BLOB</var>.)  
Storage and manipulation of Large Objects (LOBs):
</ol>


All LOBs in a [[FILEORG parameter|FILEORG]]=X’100’ file are chained.
The <var>FILEORG</var> X'100' bit and its Table E effects are available as of Model&nbsp;204 V7.5.  
<p>Storing chained LOBs has the following advantages over storing and accessing LOBs in non x'100' files:
*Because the LOBs no longer need to be contiguous, space monitoring is simpler and Table E is less likely to fill up.
*You can define fields so that 'small' LOBs can be stored 'locally' in the record (and so do not use an entire page in Table E). See the [[Field design (File management)#Using the MINLOBE attribute|MINLOBE attribute]].
*You no longer need to predict (using the [[Data maintenance#ADD_statement|RESERVE clause]]) the size that a LOB field might grow to.</p>


== Storing Large Objects ==
==Summary==  
In a <var>FILEORG</var> X'100' file, all LOBs are chained.
Storing chained LOBs has the following advantages over storing and accessing LOBs in non X'100' files:
<ul>
<li>Because the LOBs no longer need to be contiguous, space monitoring is simpler and Table E is less likely to fill up. </li>


<p>Defining a field as a large object (LOB) using the [[Field design (File management)#BLOB attribute|BLOB]] or [[Field design (File management) #CLOB attribute|CLOB attribute]] stores a pointer in the record in Table B or Table X. Storage of the LOB value depends on the [[Field design (File management)#MINLOBE attribute|MINLOBE attribute]] and length of the value being stored, as described below.</p>
<li>You can define fields so that "small" LOBs can be stored "locally" in the record (and so do not use an entire page in Table E). See [[Field design (File management)#Using the MINLOBE attribute|Using the MINLOBE attribute]]. </li>
<li>You no longer need to predict (using the [[Data maintenance#ADD_statement|RESERVE clause]]) the size to which a LOB field might grow. </li>
</ul>


=== Pointer in the record ===
==Storing Large Objects==
<p>
Defining a field as a large object (LOB) using the [[Field design (File management)#BLOB attribute|BLOB]] or [[Field design (File management) #CLOB attribute|CLOB attribute]] stores a pointer in the record in Table B or Table X. Storage of the LOB value depends on the [[Field design (File management)#MINLOBE attribute|MINLOBE attribute]] and the length of the value being stored, as described below.</p>


<p>When you store a 'not null' Large Object value in Table E, a Large Object descriptor is stored in Table B (or Table X depending on where the field is being ADDed). The descriptor contains the length, and a pointer to the Large Object data in the Table E page, and is 27 bytes long.</p>
===Pointer in the record===
<p>
When you store a "not null" Large Object value in Table E, a Large Object descriptor is stored in Table B (or Table X depending on where the field is being added). The 27-byte descriptor contains the length of and a pointer to the Large Object data in the Table E page.</p>


This descriptor is the same as in non x'100' files.
This descriptor is the same as in non X'100' files.


=== Storing a Large Object ===
=== Storing a Large Object ===
When the length of the value being stored is 0 (a null string), the action taken depends on the "repeating" type ([[Field design (File management)#AT-MOST-ONE, REPEATABLE and EXACTLY-ONE attributes|AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes]]) as discussed in the next section.
<p>
Other than null strings, if the value being stored is less than or equal to the <var>MINLOBE</var> attribute for the field, the value is stored directly in the record (Table B or Table X). Note that this value is in addition to the pointer described above.</p>
<p>
If the length of the value being stored is greater than the <var>MINLOBE</var> attribute for the field, the value is stored in a series of pages in Table E. The first (up to) 6140 bytes (4 bytes being reserved for the chain pointer) go on the first page, the next (up to) 6140 bytes go on the "next" page, and so on. These pages are not necessarily contiguous. Any pages emptied by LOB deletes are first reused before the pages at <var>[[EHIGHPG parameter|EHIGHPG]]</var> are used. </p>


When the length of the value being stored is 0 (a null string), the action taken depends on the 'repeating' type ([[Field design (File management)#AT-MOST-ONE, REPEATABLE and EXACTLY-ONE attributes|AT-MOST-ONE, REPEATABLE and EXACTLY-ONE attributes]]) as discussed in the next section.
====Null strings and Large Objects====
<p>Other than null strings, if the value being stored is less than or equal to the [[Field design (File management)#MINLOBE attribute|MINLOBE attribute]] for the field, then the value is stored directly in the record (Table B or Table X). Note that this value is in addition to the pointer described above.</p>
<p>If the length of the value being stored is greater than the [[Field design (File management)#MINLOBE attribute|MINLOBE attribute]] for the field, the value is stored in a series of pages in Table E with the first (up to) 6140 bytes (4 bytes being reserved for the chain pointer) on the first page, the next (up to) 6140 bytes on the 'next' page, and so on. These pages are not necessarily contiguous. Any pages emptied by LOB deletes are first reused before the pages at [[EHIGHPG parameter|EHIGHPG]] are used. </p>
 
==== Null Strings and Large Objects ====
 
The [[Field design (File management)#STORE-DEFAULT (SD) and STORE-NULL (SN) attributes|STORE-DEFAULT (SD) and STORE-NULL (SN) attributes]] cannot be set on LOB fields like they can on other field types. This restriction results in LOB fields having the equivalent of the LITeral option. The following table illustrates the results when null strings are stored in Large Object fields:         
The [[Field design (File management)#STORE-DEFAULT (SD) and STORE-NULL (SN) attributes|STORE-DEFAULT (SD) and STORE-NULL (SN) attributes]] cannot be set on LOB fields like they can on other field types. This restriction results in LOB fields having the equivalent of the LITeral option. The following table illustrates the results when null strings are stored in Large Object fields:         


{| class="wikitable";style="width="90%
<table class="thJustBold" style="width:90%">
|-
<tr class="head">
! align="center" scope="col" | Attribute
<th align="center">Attribute</th>
! align="center" scope="col" | Explicit Null <br/> ''fieldname'' = ' '
<th align="center">Explicit null <br/> ''fieldname'' = ' '</th>
! align="center" scope="col" | Implicit Null <br/> ''fieldname'' = %X (where %X is null)  
<th align="center">Implicit null <br/> ''fieldname'' = ''%x'' (where ''%x'' is null) </th>
! align="center" scope="col" | No reference in code  
<th align="center">No reference in code </th></tr>
|-
! scope="row"| EXACTLY-ONE
<tr><th>EXACTLY-ONE</th>
| (Note 1)
<td>(see Note, below) </td>
| (Note 1)
<td>(see Note, below) </td>
| (Note 1)
<td>(see Note, below) </td></tr>
|-
! scope="row"| AT-MOST-ONE  
<tr><th>AT-MOST-ONE</th>
| field stored with null value
<td>field stored with null value </td>
| not present
<td>not present </td>
| not present
<td>not present </td></tr>
|-
! scope="row"| REPEATABLE
<tr><th>REPEATABLE</th>
| field stored with null value
<td>field stored with null value </td>
| not present
<td>not present </td>
| not present
<td>not present </td></tr>
|}
</table>


<b>Note 1:</b> The field will always act as if it is physically present (and return a null). However, exactly-one fields react a bit differently depending on whether they are inside a field group or not. Inside a field group, all three operations will result in a field being present (as displayed in a PAI). Outside of field groups, (and remembering that only the CHANGE statement can be used on exactly-one fields) only the 'CHANGE ''fieldname'' TO %X' syntax will physically create an occurrence on the record.
<p class="note"><b>Note:</b> The field will always act as if it is physically present (and return a null). However, exactly-one fields react a bit differently depending on whether they are inside a field group or not. Inside a field group, all three operations will result in a field being present (as displayed in a PAI). Outside of field groups, (and remembering that only the CHANGE statement can be used on exactly-one fields) only the 'CHANGE ''fieldname'' TO %X' syntax will physically create an occurrence on the record. </p>


==Parameters and commands relating to the use of Table E==
==Parameters and commands relating to the use of Table E==

Revision as of 23:58, 27 January 2014

Holds Large Object data (BLOBs and CLOBs)

Storage and manipulation of Large Objects (LOBs) differs greatly depending on whether FILEORG X'100' is set for the file. This page discusses working with FILEORG X'100' files; for a parallel discussion of working with LOBs in files where FILEORG X'100' is not set, see Table E non X'100' (File architecture). For a summary of the differences between working with LOB data in files where FILEORG X'100' is set and files where it is not, see Table E (File architecture).

When the FILEORG X'100' bit is set on a file, you enable large object data storage by:

  1. Reorganizing or creating a file with ESIZE greater than 0.
  2. Defining one or more fields with an attribute of CLOB or BLOB. (The file must have an ESIZE for its fields to be defined as CLOB or BLOB.)

The FILEORG X'100' bit and its Table E effects are available as of Model 204 V7.5.

Summary

In a FILEORG X'100' file, all LOBs are chained. Storing chained LOBs has the following advantages over storing and accessing LOBs in non X'100' files:

  • Because the LOBs no longer need to be contiguous, space monitoring is simpler and Table E is less likely to fill up.
  • You can define fields so that "small" LOBs can be stored "locally" in the record (and so do not use an entire page in Table E). See Using the MINLOBE attribute.
  • You no longer need to predict (using the RESERVE clause) the size to which a LOB field might grow.

Storing Large Objects

Defining a field as a large object (LOB) using the BLOB or CLOB attribute stores a pointer in the record in Table B or Table X. Storage of the LOB value depends on the MINLOBE attribute and the length of the value being stored, as described below.

Pointer in the record

When you store a "not null" Large Object value in Table E, a Large Object descriptor is stored in Table B (or Table X depending on where the field is being added). The 27-byte descriptor contains the length of and a pointer to the Large Object data in the Table E page.

This descriptor is the same as in non X'100' files.

Storing a Large Object

When the length of the value being stored is 0 (a null string), the action taken depends on the "repeating" type (AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes) as discussed in the next section.

Other than null strings, if the value being stored is less than or equal to the MINLOBE attribute for the field, the value is stored directly in the record (Table B or Table X). Note that this value is in addition to the pointer described above.

If the length of the value being stored is greater than the MINLOBE attribute for the field, the value is stored in a series of pages in Table E. The first (up to) 6140 bytes (4 bytes being reserved for the chain pointer) go on the first page, the next (up to) 6140 bytes go on the "next" page, and so on. These pages are not necessarily contiguous. Any pages emptied by LOB deletes are first reused before the pages at EHIGHPG are used.

Null strings and Large Objects

The STORE-DEFAULT (SD) and STORE-NULL (SN) attributes cannot be set on LOB fields like they can on other field types. This restriction results in LOB fields having the equivalent of the LITeral option. The following table illustrates the results when null strings are stored in Large Object fields:

Attribute Explicit null
fieldname = ' '		 Implicit null
fieldname = %x (where %x is null) 		No reference in code
EXACTLY-ONE (see Note, below) (see Note, below) (see Note, below)
AT-MOST-ONE field stored with null value not present not present
REPEATABLE field stored with null value not present not present

Note: The field will always act as if it is physically present (and return a null). However, exactly-one fields react a bit differently depending on whether they are inside a field group or not. Inside a field group, all three operations will result in a field being present (as displayed in a PAI). Outside of field groups, (and remembering that only the CHANGE statement can be used on exactly-one fields) only the 'CHANGE fieldname TO %X' syntax will physically create an occurrence on the record.

Parameters and commands relating to the use of Table E

Note: Pages are either used or not in Table E, so there is no formula to determine whether a page is added to the reuse queue (unlike Tables B and X). Because of this, there are no EREUSE, EREUSED, or EQLEN parameters. The size of the reuse queue can always be determined by the difference between EHIGHPG and EPGSUSED.

EHIGHPG parameter The highest active Table E page. (The first page in Table E is page zero.)
EPGSUSED parameter The number of Table E pages currently in use.
ESIZE parameter The number of pages in Table E
FILEORG parameter The file organization
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Table_E_and_FILEORG_X%27100%27_files_(File_architecture)&oldid=67190"