Defining fields manually: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
 
m (link repair)
 
(45 intermediate revisions by 8 users not shown)
Line 1: Line 1:
<p>This chapter describes the DEFINE command, which allows you to define the fields in a file. For the complete syntax and description of this command, see the <var class="product">Model&nbsp;204</var> Parameter and Command Reference.</p>
<p>
This chapter describes the use of the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command, which allows you to define the fields in a file. For the full syntax, follow that link.</p>
==Defining fields==
==Defining fields==
<p>After you create and initialize a <var class="product">Model&nbsp;204</var> file, use the DEFINE command or the IFDFLD Host Language Interface function to establish the names and types of the fields in the file. </p>
<p>
<p>The format of the DEFINE command is:</p>
After you <var>[[CREATE command: File|CREATE]]</var> and <var>[[INITIALIZE command|INITIALIZE]]</var> a <var class="product">Model&nbsp;204</var> file, use the DEFINE command or the IFDFLD Host Language Interface function to establish the names and types of the fields in the file. </p>
 
<b>Syntax</b>
<b>Syntax</b>
<p>
The format of the DEFINE command is:</p>
<p class="code">DEFINE FIELD <var class="term">name</var> [(<var class="term">attribute</var> [,[<var class="term">attribute</var> ...]]) |
<p class="code">DEFINE FIELD <var class="term">name</var> [(<var class="term">attribute</var> [,[<var class="term">attribute</var> ...]]) |
   WITH [<var class="term">attribute</var>][,[<var class="term">attribute</var> ...]]]
   WITH [<var class="term">attribute</var>][,[<var class="term">attribute</var> ...]]]
</p>
</p>
<p>where:</p>
<p>
<p>name is a 1 to 255 character name that must begin with a letter and can contain any alphanumeric characters, including spaces, except:</p>
where:</p>
<p class="code"> ??
<ul>
<li><var class="term">name</var> is a 1 to 255 character name that must begin with a letter and can contain any alphanumeric characters, including spaces, except:
<p class="code"><b>??
?$
?$
?&amp;
?&amp;
@ (or an alternative delete character)
@</b> (or an alternative delete character)
# (or an alternative flush character)
<b>#</b> (or an alternative flush character)
;
<b>;</b>
</p>
</p></li>
<p>attribute is a member of the list in [[#Field attributes|Field attributes]].     </p>
 
<p>If you specify the ORDERED attribute, you can follow it with a list of qualifying parameters that designate the type of ordering and the space utilization characteristics of the Ordered Index. See the discussion of the ORDERED attribute in [[ Field Descriptions and Attributes#ORDERED and NON-ORDERED attributes|ORDERED and NON-ORDERED attributes]].  </p>
<li><var class="term">attribute</var> is a member of the list in [[Field attributes]].  
<p>
If you specify the ORDERED attribute, you can follow it with a list of qualifying parameters that designate the type of ordering and the space utilization characteristics of the Ordered Index. See the discussion of the ORDERED attribute in [[ Field design#ORDERED and NON-ORDERED attributes|ORDERED and NON-ORDERED attributes]].  </p></li>
</ul>
 
<b>Example</b>
<b>Example</b>
<p>In the following example the field CUSTID is named and given the ORDERED CHARACTER attribute:</p>
<p>
In the following example, the field CUSTID is named and given the ORDERED CHARACTER attribute:</p>
<p class="code">DEFINE FIELD CUSTID ORDERED CHARACTER
<p class="code">DEFINE FIELD CUSTID ORDERED CHARACTER
</p>
</p>
<p>Specify as many field attributes as needed from [[#Field attributes|Field attributes]]. For each attribute pair shown in the list, only one of the alternatives can be specified; conflicting attributes, such as KEY and NON-KEY, cannot be used together in a single description.</p>
<p>
<p>Note</p>
Specify as many field attributes as needed from [[Field attributes]]. For each attribute pair shown in the list, only one of the alternatives can be specified; conflicting attributes, such as KEY and NON-KEY, cannot be used together in a single description.</p>
<p>Every attribute has a default value. Therefore, you only need to specify the attribute if it is not the default.</p>
<p class="note"><b>Note:</b>
Every attribute has a default value. Therefore, you only need to specify the attribute if it is not the default.</p>
===When to use the FIELD keyword===
===When to use the FIELD keyword===
<p>The keyword FIELD is required before field names that begin with the word FIELD, PRINTER, or DATASET. It is optional with other field names. If FIELD is specified, only one field can be defined or redefined per command. For example:</p>
<p>
The keyword FIELD is required before field names that begin with the word FIELD, PRINTER, or DATASET. It is optional with other field names. If FIELD is specified, only one field can be defined or redefined per command. For example:</p>
<p class="code">DEFINE FIELD POLICYHOLDER
<p class="code">DEFINE FIELD POLICYHOLDER
DEFINE POLICYHOLDER
DEFINE POLICYHOLDER
</p>
</p>
<p>Each example above defines a field with the name POLICYHOLDER. The following example defines a field with the name FIELD LOCATION:</p>
<p>
Each example above defines a field with the name POLICYHOLDER. The following example defines a field with the name FIELD LOCATION:</p>
<p class="code">DEFINE FIELD FIELD LOCATION
<p class="code">DEFINE FIELD FIELD LOCATION
</p>
</p>
===Defining sort key, hash key, and record security fields===
===Defining sort key, hash key, and record security fields===
<p>The DEFINE command cannot be used to define sort key fields, hash key fields, or record security fields. These fields can be defined only with the INITIALIZE command, described in [[ Initializing Files Manually#INITIALIZE command|INITIALIZE command]], and the appropriate parameter settings.</p>
<p>
The DEFINE command cannot be used to define sort key fields, hash key fields, or record security fields. These fields can be defined only with the <var>[[INITIALIZE command|INITIALIZE]]</var> command and the appropriate parameter settings.</p>
===Field attributes===
===Field attributes===
<p>The attributes listed in [[#Field attributes|Field attributes]] are introduced in [[ Field Descriptions and Attributes#Field Descriptions and Attributes|Field Descriptions and Attributes]], along with a summary of the rules follow in assigning them. The ORDERED attribute has additional qualifying attributes that can be specified with the DEFINE command, which are also described in [[ Field Descriptions and Attributes#Field Descriptions and Attributes|Field Descriptions and Attributes]].</p>
<p>
The attributes listed in the following tables are introduced in [[Field design|Field design]], along with a summary of the rules follow in assigning them. A number of the attributes have additional optional attributes (in particular, see [[Field design#ORDERED field definition|the ORDERED attribute]]) that can be specified with the [[DEFINE FIELD command]], which are also described in [[Field design|Field design]].</p>
====Indexing attributes====
<p>
The overall effect of the defaults is that, unless specified, the field is not indexed.</p>
<table>
<table>
<caption>Field attributes with the DEFINE command</caption>
<caption>Indexing field attributes with the DEFINE command</caption>
<tr class="head">
<tr class="head">
<th>Attribute</th>
<th>Attribute</th><th>Abbreviation</th><th>Default</th>
<th>Abbreviation</th>
<th>Default</th>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>ORDERED CHARACTER</p>
ORDERED CHARACTER<p>NON-ORDERED</p>
<p>NON-ORDERED</p>
</td>
</td>
<td rowspan="2">
<td>
<p>ORD CHAR</p>
ORD CHAR<p>NORD</p>
<p>NORD</p>
</td>
</td>
<td rowspan="2">NON-ORDERED</td>
<td>NON-ORDERED</td>
</tr>
</tr>
<tr>
<tr>
<td>
ORDERED NUMERIC<p>NON-ORDERED</p>
</td>
<td>
ORD NUM<p>NORD</p>
</td>
<td>NON-ORDERED</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>ORDERED NUMERIC</p>
KEY<p>NON-KEY</p>
<p>NON-ORDERED</p>
</td>
</td>
<td rowspan="2">
<td>&nbsp;
<p>ORD NUM</p>
<p>NKEY</p>
<p>NORD</p>
</td>
</td>
<td rowspan="2">NON-ORDERED</td>
<td>NON-KEY</td>
</tr>
</tr>
<tr>
<tr>
<td>
FRV<p>NON-FRV</p>
<p>The ORD attribute is preferable; shown for compatibility.</p>
</td>
<td>&nbsp;
<p>NFRV</p>
</td>
<td>NON-FRV</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>KEY</p>
[NUMERIC] RANGE<p>NON-RANGE</p>
<p>NON-KEY</p>
<p>Obsolete; supported for compatibility.</p>
</td>
</td>
<td rowspan="2">
<td>
<p>-</p>
NR<p>NNR</p>
<p>NKEY</p>
</td>
</td>
<td rowspan="2">NON-KEY</td>
<td>NON-RANGE</td>
</tr>
</tr>
</table>
====Data types====
<p>
In most cases, only one of these may be specified on any field (see the UTF attributes). The default is STRING</p>
<table>
<caption>Data type attributes with the DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Notes</th>
</tr>
<tr>
<td>STRING</td>
<td>STR</td>
<td></td>
</tr>
<tr>
<tr>
<td>BINARY</td>
<td>BIN</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>VISIBLE</p>
BINARY-LARGE-OBJECT<p>CHARACTER-LARGE-OBJECT</p>
<p>INVISIBLE</p>
</td>
<td>
BLOB<p>CLOB</p>
</td>
</td>
<td rowspan="2">
<td>
<p>VIS</p>
Must have Table E enabled<p></p>
<p>INV</p>
</td>
</td>
<td rowspan="2">VISIBLE</td>
</tr>
</tr>
<tr>
<td>FLOAT</td>
<td>FLT</td>
<td>Must have LEN specified</td>
</tr>
<tr>
<tr>
<td>DATETIME</td>
<td>DT</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>DEFERRABLE</p>
UTF-8<p>UTF-16</p>
<p>NON-DEFERRABLE</p>
</td>
</td>
<td rowspan="2">
<td>
<p>DEF</p>
UTF8<p>UTF16</p>
<p>NDEF</p>
</td>
<td>
Must be used in conjunction with the BLOB or CLOB attribute<p></p>
</td>
</td>
<td rowspan="2">DEFERRABLE</td>
</tr>
</tr>
<tr>
<tr>
<td>
VISIBLE<p>INVISIBLE</p>
</td>
<td>
VIS<p>INV</p>
</td>
</tr>
</table>
==== Data content attributes====
<table>
<caption>Data content field attributes with the DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Default</th>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>AT-MOST-ONE</p>
LENGTH <var class="term">m</var>
<p>REPEATABLE</p>
</td>
<td>
LEN <var class="term">m</var>
</td>
</td>
<td rowspan="2">
<td>
<p>ONE</p>
No preallocated length
<p>REPT</p>
</td>
</td>
<td rowspan="2">REPT (except in 1NF files)</td>
</tr>
</tr>
<tr>
<tr>
<td>OCCURS n</td>
<td>OCC n</td>
<td>No preallocated occurrences</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>UNIQUE</p>
PAD <var class="term">character</var>
<p>NON-UNIQUE</p>
</td>
<td>
&nbsp;
</td>
</td>
<td rowspan="2">
<td>
<p>UNIQ</p>
<var class="term">character</var> = X'00'
<p>NUNIQ</p>
</td>
</td>
<td rowspan="2">NON-UNIQUE</td>
</tr>
</tr>
<tr>
<tr>
<td>
DEFERRABLE<p>NON-DEFERRABLE</p>
</td>
<td>
DEF<p>NDEF</p>
</td>
<td>DEFERRABLE</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p><var>FRV</var></p>
UPDATE IN PLACE<p>UPDATE AT END</p>
<p><var>NON-FRV</var></p>
<p><var>Obsolete; supported for compatibility. </var></p>
</td>
</td>
<td rowspan="2">
<td>
<p><var>-</var></p>
UP<p>UE</p>
<p><var>NFRV</var></p>
</td>
</td>
<td rowspan="2"><var>NON-FRV</var></td>
<td>UPDATE IN PLACE</td>
</tr>
</tr>
<tr>
<tr>
<td>DEFAULT-VALUE
<p>STORE-DEFAULT</p>
<p>STORE-NULL</p></td>
<td>DV
<p>SD</p>
<p>SN</p></td>
<td>&nbsp;
<p>LITERAL</p>
<p>LITERAL</p></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>CODED</p>
AT-MOST-ONE<p>EXACTLY-ONE</p>
<p>NON-CODED</p>
<p>REPEATABLE</p>
</td>
</td>
<td rowspan="2">
<td>
<p>COD</p>
ONE<p>EXONE</p>
<p>NCOD</p>
<p>REPT</p>
</td>
</td>
<td rowspan="2">NON-CODED</td>
<td>REPT (except in 1NF files), or inside a field group (where it is EXONE)<p></p><p></p></td>
</tr>
</tr>
<tr>
<tr>
<td>
CODED<p>NON-CODED</p>
</td>
<td>
COD<p>NCOD</p>
</td>
<td>NON-CODED</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>FEW-VALUED</p>
FEW-VALUED<p>MANY-VALUED</p>
<p>MANY-VALUED</p>
</td>
</td>
<td rowspan="2">
<td>
<p>FV</p>
FV<p>MV</p>
<p>MV</p>
</td>
</td>
<td rowspan="2">MANY-VALUED</td>
<td>MANY-VALUED</td>
</tr>
</tr>
</table>
====Field constraints====
<p>
More than one constraint may be set on a field. For example, if you only want to accept integer values between 5 and 99, then you can code:</p>
<p class="code">DEFINE FIELD <i>fieldname</i> WITH INTGE 5 INTLE 99
</p>
<table>
<caption>Field constraint attributes with DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Notes</th>
</tr>
<tr>
<tr>
<td>
UNIQUE<p>NON-UNIQUE</p>
</td>
<td>
UNIQ<p>NUNIQ</p>
</td>
<td>NON-UNIQUE is default</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>UPDATE IN PLACE</p>
LEVEL
<p>UPDATE AT END</p>
</td>
</td>
<td rowspan="2">
<td>
<p>UP</p>
LEV
<p>UE</p>
</td>
</td>
<td rowspan="2">UPDATE IN PLACE</td>
<td>
See [[Model 204 security features]]
</td>
</tr>
<tr>
<td colspan="3">
<p><center><b>Field length constraints</b></center></p>
</td>
</tr>
<tr>
<td>LENGTH-EQ</td><td>LEQ</td><td>Available as of V7.5</td>
</tr>
<tr>
<td>LENGTH-GE</td><td>LGE</td><td>Available as of V7.5</td>
</tr>
</tr>
<tr>
<tr>
<td>LENGTH-LE</td><td>LLE</td><td>Available as of V7.5</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td colspan="3">
<p>STRING</p>
<center><b>Integer value constraints</b></center>
<p>BINARY</p>
(validate contents against permissible integer value)
</td>
</td>
<td rowspan="2">
</tr>
<p>STR</p>
<p>BIN</p>
<tr>
<td>INTEGER-GE</td><td>INTGE</td><td>Available as of V7.5</td>
</tr>
<tr>
<td>INTEGER-GT</td><td>INTGT</td><td>Available as of V7.5</td>
</tr>
<tr>
<td>INTEGER-LE</td><td>INTLE</td><td>Available as of V7.5</td>
</tr>
<tr>
<td>INTEGER-LT</td><td>INTLT</td><td>Available as of V7.5</td>
</tr>
<tr>
<td colspan="3">
<center><b>Float value constraints</b></center>
(validate contents against permissible float value)
</td>
</td>
<td rowspan="2">STRING</td>
</tr>
</tr>
<tr>
<td>FLOAT-GE</td><td>FLTGE</td><td>Available as of V7.5</td>
</tr>
<tr>
<td>FLOAT-GT</td><td>FLTGT</td><td>Available as of V7.5</td>
</tr>
<tr>
<tr>
<td>FLOAT-LE</td><td>FLTLE</td><td>Available as of V7.5</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>FLOAT-LT</td><td>FLTLT</td><td>Available as of V7.5</td>
<p>FLOAT</p>
</tr>
<p>LENGTH <var class="term">m</var></p>
</td>
<tr>
<td rowspan="2">
</tr>
<p>-</p>
<p>LEN <var class="term">m</var></p>
<tr>
</td>
<td colspan="3">
<td rowspan="2">
<center><b>Date Time value constraints</b></center>
<p>-</p>
(validate contents against permissible date times value)
<p>No preallocated length</p>
</td>
</td>
</tr>
</tr>
<tr>
<td>DATETIME-GE</td><td>DTGE</td><td>Available as of V7.5</td>
</tr>
<tr>
<tr>
<td>DATETIME-GT</td><td>DTGT</td><td>Available as of V7.5</td>
</tr>
</tr>
<tr>
<tr>
<td>OCCURS n</td>
<td>DATETIME-LE</td><td>DTLE</td><td>Available as of V7.5</td>
<td>OCC n</td>
<td>No preallocated occurrences</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">LEVEL <var class="term">k</var></td>
<td>DATETIME-LT</td><td>DTLT</td><td>Available as of V7.5</td>
<td rowspan="2">LVL <var class="term">k</var></td>
</tr>
<td rowspan="2">No level</td>
</table>
==== Concatenated fields ====
<table>
<caption>Concatenated field attributes with the DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Notes</th>
</tr>
</tr>
<tr>
<tr>
<td>CONCATENATION-OF</td>
<td>CAT</td>
<td>All source fields must be EXACTLY-ONE</td>
</tr>
</table>
==== Automatic fields ====
<table>
<caption>Automatic field attributes with the DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Notes</th>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>
<p>PAD <var class="term">character</var></p>
COUNT-OCCURRENCES-OF
<p>LENGTH <var class="term">m</var></p>
</td>
<td>
CTO
</td>
</td>
<td rowspan="2">
<td>
<p>-</p>
Followed by what it is you are counting;
<p>LEN <var class="term">m</var></p>
<br>
not allowed for fields defined as REPEATABLE
</td>
</td>
<td rowspan="2">
</tr>
<p>Character = X'00'</p>
<p>No preallocated length</p>
<tr>
<td colspan="3">
<center><b>Tracking updates with automatic fields</b></center>
</td>
</td>
</tr>
</tr>
<tr>
<td>CREATE-TIME</td><td>CRTM</td><td>Not allowed for fields defined as REPEATABLE</td>
</tr>
<tr>
<td>CREATE-TIMEUTC</td><td>CRTMU</td><td>Not allowed for fields defined as REPEATABLE</td>
</tr>
<tr>
<td>UPDATE-TIME</td><td>UPTM</td><td>Not allowed for fields defined as REPEATABLE</td>
</tr>
<tr>
<tr>
<td>UPDATE-TIMEUTC</td><td>UPTMU</td><td>Not allowed for fields defined as REPEATABLE</td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>CREATE-USER</td><td>CRUS</td><td>Not allowed for fields defined as REPEATABLE</td>
<p><var>[NUMERIC] RANGE</var></p>
</tr>
<p><var>NON-RANGE</var></p>
<p><var>Obsolete; supported for compatibility. </var></p>
<tr>
</td>
<td>UPDATE-USER</td><td>UPUS</td><td>Not allowed for fields defined as REPEATABLE</td>
<td rowspan="2">
</tr>
<p><var>NR</var></p>
</table>
<p><var>NNR</var></p>
</td>
==== Defining a field inside a field group ====
<td rowspan="2"><var>NON-RANGE</var></td>
<table>
<caption>Linking a field to a field group with the DEFINE command</caption>
<tr class="head">
<th>Attribute</th>
<th>Abbreviation</th>
<th>Notes</th>
</tr>
</tr>
<tr>
<tr>
<td>FIELDGROUP</td>
<td>FG</td>
<td>If not the last attribute specified, requires ' AND ' after it</td>
</tr>
</tr>
</table>
</table>
===OCCURS and LENGTH clauses===
===OCCURS and LENGTH clauses===
<p>The variables n and m specified for OCCURS and LENGTH must be decimal numbers between 1 and 255. The PAD character can be specified in decimal, hexadecimal (X'xx'), or character (C'c') form, and can take on any value equivalent to a number between 0 and 255.</p>
<p>
<p>All preallocated fields (fields that have an OCCURS clause) must be defined before any records are added to the file. </p>
The variables n and m specified for OCCURS and LENGTH must be decimal numbers between 1 and 255. The PAD character can be specified in decimal, hexadecimal (X'xx'), or character (C'c') form, and can take on any value equivalent to a number between 0 and 255.</p>
<p>
All preallocated fields (fields that have an OCCURS clause) must be defined before any records are added to the file. </p>
<p class="note"><b>Note:</b> After records are loaded, you can add a preallocated field definition only by reinitializing the file, defining all the fields-including the new preallocated field-and reloading the records. Non-preallocated field definitions can be added at any time. </p>
<p class="note"><b>Note:</b> After records are loaded, you can add a preallocated field definition only by reinitializing the file, defining all the fields-including the new preallocated field-and reloading the records. Non-preallocated field definitions can be added at any time. </p>
===Defining field retrieval attributes===
===Defining field retrieval attributes===
<p>If you do not know if a field will be used in retrievals, you can define it initially as NON-KEY, NON-ORDERED, and NON-RANGE. Then, you will be able to monitor the use of the field in FIND statements using information written to the journal data set and redefine it as KEY, NUMERIC RANGE, or ORDERED when necessary.</p>
<p>
<p>For details, see [[ File Statistics and Tuning#Monitoring field retrievals in FIND statements|Monitoring field retrievals in FIND statements]].</p>
If you do not know if a field will be used in retrievals, you can define it initially as NON-KEY, NON-ORDERED, and NON-RANGE. Then, you will be able to monitor the use of the field in FIND statements using information written to the journal data set and redefine it as KEY, NUMERIC RANGE, or ORDERED when necessary.</p>
<p>
For details, see [[File statistics and tuning#Monitoring field retrievals in FIND statements|Monitoring field retrievals in FIND statements]].</p>
==Implementing the date-time stamp feature (DTS)==
==Implementing the date-time stamp feature (DTS)==
<p>The date-time stamp feature in <var class="product">Model&nbsp;204</var> lets you can easily discern when a record in a file was last changed. The date-time stamp feature is supported for ONLINE and BATCH204.</p>
<p>
<ul>
The date-time stamp feature in <var class="product">Model&nbsp;204</var> lets you can easily discern when a record in a file was last changed. The date-time stamp feature is supported for ONLINE and BATCH204.</p>
<li>Your site may customize:</li>
</ul>
<p>
<b>The date-time stamp field name</b>
See [[Setting up the date-time stamp field]] for the steps the System Manger must take before this feature is used.
<p>There is no default date-time stamp field name as delivered. You can define the date-time stamp field name in the CUST source code or on User 0's parameter line by setting the new DTSFN parameter.</p>
</p>
<b>The field definition</b>
<p>
<p>A user with file manager privileges can define the date-time stamp field for each file you want enabled, and subsequently, you must set the FOPT parameter to include X'10'. Note: the FOPT=X'10' value cannot be set until the date-time stamp field has been defined to the file.</p>
See [[Adding a date-time stamp field]] for rules about using the date-time stamp feature.</p>
<b>The data that is stored in this field</b>
 
<p>The default date-time stamp format uses the operating system timestamp value. If your site prefers a different field value or a different data format, consult your Rocket <var class="product">Model&nbsp;204</var> installation guide to customize the date-time stamp field name and to activate the date-time stamp feature.</p>
<ul>
<li>The DTS feature is implemented on a file-by-file basis.</li>
<li>Precision and accuracy of the date-time stamp is to the millisecond when you use the date-time stamp as delivered. Rocket Software recommends that the date-time stamp field be defined as ORDERED CHARACTER to support ordered index FIND processing. (The length of this field is 17 bytes.)</li>
<li>The date-time stamp field is updated at the beginning of commit processing when a new record is stored or an existing record is updated-change, insert, or delete field. </li>
<li>You can read and display the date-time stamp field with User Language, the same as any other field.</li>
<li>You can exclude a user thread from date-time stamp field maintenance by resetting the DTS parameter to 0.</li>
</ul>
<p>The date-time stamp routine executes once for each transaction if the user thread has set DTS=1 and the files being updated have an FOPT value that includes X'10'. The data built by the DTS routine updates the field specified by the DTSFN parameter. </p>
===Adding a date-time stamp field to your files===
<p>You can include a date-time stamp field in your files to keep track of when records in the file were last modified. The date-time stamp feature lets you put a date-time stamp (DTS) on each record that was updated in a transaction. You can then use the data in the <var class="term">date-time stamp</var> field in an end-user written application to find and process all the rows of data that were changed.</p>
<p>An application that processes these records can track the <var class="term">date-time stamp</var> field values that have been processed to date, or it may take another action, including updating the date-time stamp field.</p>
<p>To install and use this functionality, you must obtain the correct decrypt keys and install this release.</p>
<p class="note"><b>Note:</b> There is no support in PQO/204 for the data/time stamp feature.</p>
<b>Handling the date-time stamp field in a file</b>
<p>The DELETE FIELD command is prohibited for the DTSFN field in a file when the FOPT=X'10' is set.</p>
==Preventing definition of new field names==
==Preventing definition of new field names==
<p><var class="product">Model&nbsp;204</var> permits a user to define new fields at any time. This is an advantage in some applications, because it enables the file to evolve beyond its original definition. If your site does not want users to add new field names, reset the FOPT parameter to X'01' from its default value of X'00'. This file option causes <var class="product">Model&nbsp;204</var> to issue the following response, when a user issues a DEFINE command:</p>
<p>
<var class="product">Model&nbsp;204</var> permits a user to define new fields at any time. This is an advantage in some applications, because it enables the file to evolve beyond its original definition. If your site does not want users to add new field names, reset the <var>[[FOPT parameter|FOPT]]</var> parameter to X'01' from its default value of X'00'. This file option causes <var class="product">Model&nbsp;204</var> to issue the following response, when a user issues a DEFINE command:</p>
<p class="code"><b></b>*** M204.1261: NEW FIELD NAMES NOT PERMITTED
<p class="code"><b></b>*** M204.1261: NEW FIELD NAMES NOT PERMITTED
</p>
</p>
<p>Regardless of the setting of the FOPT parameter, the file manager can define new fields at any time. The FOPT parameter is discussed in detail in the <var class="product">Model&nbsp;204</var> Parameter and Command Reference. </p>
<p>
<p>&nbsp;</p>
Regardless of the setting of the <var>FOPT</var> parameter, users with file manager privileges (see the <var>[[PRIVDEF parameter|PRIVDEF]]</var> parameter) can define new fields at any time. See the [[FOPT parameter]] discussion for more detail. </p>
[[Category:File manager]]
[[Category:Model 204 files]]

Latest revision as of 21:21, 7 April 2017

This chapter describes the use of the DEFINE FIELD command, which allows you to define the fields in a file. For the full syntax, follow that link.

Defining fields

After you CREATE and INITIALIZE a Model 204 file, use the DEFINE command or the IFDFLD Host Language Interface function to establish the names and types of the fields in the file.

Syntax

The format of the DEFINE command is:

DEFINE FIELD name [(attribute [,[attribute ...]]) | WITH [attribute][,[attribute ...]]]

where:

  • name is a 1 to 255 character name that must begin with a letter and can contain any alphanumeric characters, including spaces, except:

    ?? ?$ ?& @ (or an alternative delete character) # (or an alternative flush character) ;

  • attribute is a member of the list in Field attributes.

    If you specify the ORDERED attribute, you can follow it with a list of qualifying parameters that designate the type of ordering and the space utilization characteristics of the Ordered Index. See the discussion of the ORDERED attribute in ORDERED and NON-ORDERED attributes.

Example

In the following example, the field CUSTID is named and given the ORDERED CHARACTER attribute:

DEFINE FIELD CUSTID ORDERED CHARACTER

Specify as many field attributes as needed from Field attributes. For each attribute pair shown in the list, only one of the alternatives can be specified; conflicting attributes, such as KEY and NON-KEY, cannot be used together in a single description.

Note: Every attribute has a default value. Therefore, you only need to specify the attribute if it is not the default.

When to use the FIELD keyword

The keyword FIELD is required before field names that begin with the word FIELD, PRINTER, or DATASET. It is optional with other field names. If FIELD is specified, only one field can be defined or redefined per command. For example:

DEFINE FIELD POLICYHOLDER DEFINE POLICYHOLDER

Each example above defines a field with the name POLICYHOLDER. The following example defines a field with the name FIELD LOCATION:

DEFINE FIELD FIELD LOCATION

Defining sort key, hash key, and record security fields

The DEFINE command cannot be used to define sort key fields, hash key fields, or record security fields. These fields can be defined only with the INITIALIZE command and the appropriate parameter settings.

Field attributes

The attributes listed in the following tables are introduced in Field design, along with a summary of the rules follow in assigning them. A number of the attributes have additional optional attributes (in particular, see the ORDERED attribute) that can be specified with the DEFINE FIELD command, which are also described in Field design.

Indexing attributes

The overall effect of the defaults is that, unless specified, the field is not indexed.

Indexing field attributes with the DEFINE command
AttributeAbbreviationDefault
ORDERED CHARACTER

NON-ORDERED

 ORD CHAR

NORD

 NON-ORDERED
ORDERED NUMERIC

NON-ORDERED

 ORD NUM

NORD

 NON-ORDERED
KEY

NON-KEY

  

NKEY

 NON-KEY
FRV

NON-FRV

The ORD attribute is preferable; shown for compatibility.

  

NFRV

 NON-FRV
[NUMERIC] RANGE

NON-RANGE

Obsolete; supported for compatibility.

 NR

NNR

 NON-RANGE

Data types

In most cases, only one of these may be specified on any field (see the UTF attributes). The default is STRING

Data type attributes with the DEFINE command
Attribute Abbreviation Notes
STRING STR
BINARY BIN
BINARY-LARGE-OBJECT

CHARACTER-LARGE-OBJECT

 BLOB

CLOB

 Must have Table E enabled
FLOAT FLT Must have LEN specified
DATETIME DT
UTF-8

UTF-16

 UTF8

UTF16

 Must be used in conjunction with the BLOB or CLOB attribute
VISIBLE

INVISIBLE

 VIS

INV

Data content attributes

Data content field attributes with the DEFINE command
Attribute Abbreviation Default

LENGTH m

LEN m

No preallocated length

OCCURS n OCC n No preallocated occurrences

PAD character

 

character = X'00'

DEFERRABLE

NON-DEFERRABLE

 DEF

NDEF

 DEFERRABLE
UPDATE IN PLACE

UPDATE AT END

 UP

UE

 UPDATE IN PLACE
DEFAULT-VALUE

STORE-DEFAULT

STORE-NULL

 DV

SD

SN

  

LITERAL

LITERAL
AT-MOST-ONE

EXACTLY-ONE

REPEATABLE

 ONE

EXONE

REPT

 REPT (except in 1NF files), or inside a field group (where it is EXONE)
CODED

NON-CODED

 COD

NCOD

 NON-CODED
FEW-VALUED

MANY-VALUED

 FV

MV

 MANY-VALUED

Field constraints

More than one constraint may be set on a field. For example, if you only want to accept integer values between 5 and 99, then you can code:

DEFINE FIELD fieldname WITH INTGE 5 INTLE 99

Field constraint attributes with DEFINE command
Attribute Abbreviation Notes
UNIQUE

NON-UNIQUE

 UNIQ

NUNIQ

 NON-UNIQUE is default

LEVEL

LEV

See Model 204 security features

Field length constraints
LENGTH-EQLEQAvailable as of V7.5
LENGTH-GELGEAvailable as of V7.5
LENGTH-LELLEAvailable as of V7.5
Integer value constraints

(validate contents against permissible integer value)

INTEGER-GEINTGEAvailable as of V7.5
INTEGER-GTINTGTAvailable as of V7.5
INTEGER-LEINTLEAvailable as of V7.5
INTEGER-LTINTLTAvailable as of V7.5
Float value constraints

(validate contents against permissible float value)

FLOAT-GEFLTGEAvailable as of V7.5
FLOAT-GTFLTGTAvailable as of V7.5
FLOAT-LEFLTLEAvailable as of V7.5
FLOAT-LTFLTLTAvailable as of V7.5
Date Time value constraints

(validate contents against permissible date times value)

DATETIME-GEDTGEAvailable as of V7.5
DATETIME-GTDTGTAvailable as of V7.5
DATETIME-LEDTLEAvailable as of V7.5
DATETIME-LTDTLTAvailable as of V7.5

Concatenated fields

Concatenated field attributes with the DEFINE command
Attribute Abbreviation Notes
CONCATENATION-OF CAT All source fields must be EXACTLY-ONE


Automatic fields

Automatic field attributes with the DEFINE command
Attribute Abbreviation Notes

COUNT-OCCURRENCES-OF

CTO

Followed by what it is you are counting;
not allowed for fields defined as REPEATABLE

Tracking updates with automatic fields
CREATE-TIMECRTMNot allowed for fields defined as REPEATABLE
CREATE-TIMEUTCCRTMUNot allowed for fields defined as REPEATABLE
UPDATE-TIMEUPTMNot allowed for fields defined as REPEATABLE
UPDATE-TIMEUTCUPTMUNot allowed for fields defined as REPEATABLE
CREATE-USERCRUSNot allowed for fields defined as REPEATABLE
UPDATE-USERUPUSNot allowed for fields defined as REPEATABLE

Defining a field inside a field group

Linking a field to a field group with the DEFINE command
Attribute Abbreviation Notes
FIELDGROUP FG If not the last attribute specified, requires ' AND ' after it

OCCURS and LENGTH clauses

The variables n and m specified for OCCURS and LENGTH must be decimal numbers between 1 and 255. The PAD character can be specified in decimal, hexadecimal (X'xx'), or character (C'c') form, and can take on any value equivalent to a number between 0 and 255.

All preallocated fields (fields that have an OCCURS clause) must be defined before any records are added to the file.

Note: After records are loaded, you can add a preallocated field definition only by reinitializing the file, defining all the fields-including the new preallocated field-and reloading the records. Non-preallocated field definitions can be added at any time.

Defining field retrieval attributes

If you do not know if a field will be used in retrievals, you can define it initially as NON-KEY, NON-ORDERED, and NON-RANGE. Then, you will be able to monitor the use of the field in FIND statements using information written to the journal data set and redefine it as KEY, NUMERIC RANGE, or ORDERED when necessary.

For details, see Monitoring field retrievals in FIND statements.

Implementing the date-time stamp feature (DTS)

The date-time stamp feature in Model 204 lets you can easily discern when a record in a file was last changed. The date-time stamp feature is supported for ONLINE and BATCH204.

See Setting up the date-time stamp field for the steps the System Manger must take before this feature is used.

See Adding a date-time stamp field for rules about using the date-time stamp feature.

Preventing definition of new field names

Model 204 permits a user to define new fields at any time. This is an advantage in some applications, because it enables the file to evolve beyond its original definition. If your site does not want users to add new field names, reset the FOPT parameter to X'01' from its default value of X'00'. This file option causes Model 204 to issue the following response, when a user issues a DEFINE command:

*** M204.1261: NEW FIELD NAMES NOT PERMITTED

Regardless of the setting of the FOPT parameter, users with file manager privileges (see the PRIVDEF parameter) can define new fields at any time. See the FOPT parameter discussion for more detail.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Defining_fields_manually&oldid=102613"