Defining fields manually

This chapter describes the use of DEFINE 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.

The format of the DEFINE command is:

Syntax

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, described in INITIALIZE command, and the appropriate parameter settings.

Field attributes

The attributes listed in Field attributes are introduced in 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 attributes with the DEFINE command

Attribute	Abbreviation	Default
ORDERED CHARACTER NON-ORDERED	ORD CHAR NORD	NON-ORDERED
ORDERED NUMERIC NON-ORDERED	ORD NUM NORD	NON-ORDERED
KEY NON-KEY	- NKEY	NON-KEY
VISIBLE INVISIBLE	VIS INV	VISIBLE
DEFERRABLE NON-DEFERRABLE	DEF NDEF	DEFERRABLE
AT-MOST-ONE REPEATABLE	ONE REPT	REPT (except in 1NF files)
UNIQUE NON-UNIQUE	UNIQ NUNIQ	NON-UNIQUE
FRV NON-FRV Obsolete; supported for compatibility.	- NFRV	NON-FRV
CODED NON-CODED	COD NCOD	NON-CODED
FEW-VALUED MANY-VALUED	FV MV	MANY-VALUED
UPDATE IN PLACE UPDATE AT END	UP UE	UPDATE IN PLACE
STRING BINARY	STR BIN	STRING
FLOAT LENGTH m	- LEN m	- No preallocated length
OCCURS n	OCC n	No preallocated occurrences
LEVEL k	LVL k	No level
PAD character LENGTH m	- LEN m	Character = X'00' No preallocated length
[NUMERIC] RANGE NON-RANGE Obsolete; supported for compatibility.	NR NNR	NON-RANGE

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.

• Your site may customize:

The date-time stamp field name

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.

The field definition

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.

The data that is stored in this field

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 Model 204 installation guide to customize the date-time stamp field name and to activate the date-time stamp feature.

• The DTS feature is implemented on a file-by-file basis.
• 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.)
• 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.
• You can read and display the date-time stamp field with User Language, the same as any other field.
• You can exclude a user thread from date-time stamp field maintenance by resetting the DTS parameter to 0.

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.

Adding a date-time stamp field to your files

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 date-time stamp field in an end-user written application to find and process all the rows of data that were changed.

An application that processes these records can track the date-time stamp field values that have been processed to date, or it may take another action, including updating the date-time stamp field.

To install and use this functionality, you must obtain the correct decrypt keys and install this release.

Note: There is no support in PQO/204 for the data/time stamp feature.

Handling the date-time stamp field in a file

The DELETE FIELD command is prohibited for the DTSFN field in a file when the FOPT=X'10' is set.

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, the file manager can define new fields at any time. The FOPT parameter is discussed in detail in the Model 204 Parameter and Command Reference.