You can use the DEFINE procedure to define the fields in a structure. The DEFINE procedure is also used to modify and delete field definitions.

When the Define fields menu option is selected, the field definition input screen is displayed.

Example 16-4 Field Definition Input Screen

SETUP Vn.n Definitions for CUSTOMER.STR Fieldname : Classification : Description : Data type : First position : length: Occurs: Semantics : Prompt text : Report heading : Print mask : Screen mask : Help text : Access rules : Validation rules: Field name? _________________________________ Enter -fieldname to delete a field EXIT = Exit \ = Back HELP = Help

You will be asked first for the name of the field you wish to add, modify or delete. You will then be prompted for information about the field.

16.4.1 Field name

If you wish to delete a field, enter a minus sign (-) followed by the field name. For example:

Field name? -phone

The field name:

• must begin with a letter.
• can consist of numbers, letters, underscores and dollar signs.
• can be up to 32 characters long.
• The last character of the field name can be a "$" or "%".

If you are modifying a field, the defaults for the rest of the DEFINE prompts will be your original responses. You can keep these defaults by pressing the [Return] key at the prompt. You can change the defaults by typing over the responses.

16.4.2 Classification

The classification is optional.

Classification refers to a field class in the CLASSIFICATION data dictionary. Field classes are pre-defined commonly used data fields.

Using Classifications

There are cases when you use the same field type in a record or in several datasets. When this occurs, setting up a field class will save time in defining fields and help to ensure data integrity.

If, for example, you had a home phone field, work phone field and alternate phone field in your record, you would need to define the three phone fields using different field names but the same characteristics. The phone fields would all be 10 numeric characters in length and be printed in the format (123) 456-7890.

To ensure that all the phone numbers are defined exactly the same, you could define a phone class in the CLASSIFICATION data dictionary. The class name could be PHONE and be defined with the length (10), semantics (num), print mask ((###~)~ ###~-####) and validations (digits; minlength 10).

Then, whenever you want to define a phone number type field, you would enter the field name, HOME_PHONE for example, with PHONE as the classification and the classification data would automatically become the default answers to the remaining DEFINE prompts. If you did not want to use a particular default, you can simply type in a different answer at the prompt.

You would also be able to use the PHONE classification when defining phone fields in other dataset records.

Before you can use field classifications, you must first define the field classes in the CLASSIFICATION data dictionary.

Creating Field Classes

Field classes are defined the same way as any other data field. However, these fields are located in a specific data file called TTI_RUN:CLASSIFICATION. To create a field class, perform the following steps:

1. Get into SETUP.
2. Enter TTI_RUN:CLASSIFICATION as the structure name. The following information will be displayed:

   Structure name : TTI_RUN:CLASSIFICATION.STR Database engine: RMS Dataset : NONE Data dictionary: TTI_RUN:CLASSIFICATION.DEF

3. Select the Define fields procedure.
4. At the field name prompt, enter the field class name you want to use (i.e. PHONE).
5. Go through each of the prompts and set up the characteristics you want this field class to have.

You can set up as many field classes as you wish.

Using an Alternate Classification File

If you do not want to use the provided TTI_RUN:CLASSIFICATION data file, you can create one of your own. For example, you could create a structure such as CLASS_NAMES for your field classes. However, if you choose to do this, you MUST define the file as follows:

• DEFINE TTI_CLASSIFICATION device:[directory]CLASS_NAMES.DEF

SETUP will then retrieve classification data from CLASS_NAMES instead of TTI_RUN:CLASSIFICATION.

Generated Defaults

After the classification prompt is answered, SETUP displays either the class defaults or defaults generated by SETUP to assist you in defining the field.

Example 16-5 DEFINE Screen showing field class generated defaults

SETUP Vn.n Definitions for CUSTOMER.STR Fieldname : HOME_PHONE Classification : PHONE Description : Home phone Data type : CH First position : 14 length: 10 Occurs: 1 Semantics : NUM, RJ Prompt text : Home phone Report heading : Home Phone Print mask : (###~)~ ###~-#### Screen mask : none Help text : none Access rules : NORMAL Validation rules: digits; minlength 10 Description? Home phone____________________ EXIT = Exit \ = Back HELP = Help

Example 16-6 DEFINE Screen showing SETUP generated defaults

SETUP Vn.n Definitions for CUSTOMER.STR Fieldname : HOME_PHONE Classification : none Description : Home phone Data type : CH First position : 14 length: Occurs: 1 Semantics : UC Prompt text : Home phone Report heading : Home Phone Print mask : none Screen mask : none Help text : none Access rules : NORMAL Validation rules: none Description? Home phone____________________ EXIT = Exit \ = Back HELP = Help

16.4.3 Description

If you are adding this field, the default description is the field name with any "$", "%", "_" characters changed to spaces.

The description will be used as the default prompt text.

16.4.4 Data type

The DATE (DS) attribute is currently only used by applications and has no effect within INTOUCH.

16.4.5 First position

Figure 16-1 Character Positions

ID CONTACT ----------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | | | | | | | | positions 1 5 10 15 20

In the above diagram, the ID field starts at position 1 and ends at position 5. The CONTACT field starts at position 6, etc.

Fields generally follow each other directly. Therefore, the first position of a new field is usually one more than the last position used. If the last position used was ten, the next field would start at eleven. INTOUCH automatically defaults to the correct sequential position.

Defining existing RMS file fields

If you are defining fields for an existing RMS file, you must keep in mind that the starting position of an RMS file record is 0 and in INTOUCH, the starting position is 1. (RMS is 0 oriented, whereas INTOUCH is 1 oriented.) For example, if the RMS file field starts in position 0, when you define this field in INTOUCH, you must define the field as starting in position 1. If the RMS field starts in position 20, you would use 21 as the starting position, etc.

16.4.6 Field length

You can also enter the ending position for the field length. You enter "P" followed by the ending position. For example: P5

Variable Length Fields

If a CH or UN data type field has a first position that starts at or before the end of a logical record, that field will have its length adjusted upon reference. The new length will reflect the actual end of the logical record.

For example, a field could start in position one, and have its length set to the maximum record length. When the field is referenced, its length will be adjusted to the actual record length. This field is variable length.

16.4.7 Number of occurrences

If the field being defined is an array, enter the number of elements in the array.

16.4.8 Semantics

The semantics are entered as a list of descriptors separated by commas. When you have completed your list, enter GOLD/F (i.e. press [PF1] and then the [F] key).

The valid semantics are:

	NUM	Indicates a numeric field which allows only numbers. The semantic RJ, right-justified, is automatically appended when NUM is selected.
	NUM:scale	SCALE specifies the scale factor---how many decimal places to use. Scale factors can be positive or negative (from -99 to 99).
	RJ	The data will be right-justified in the field.
	UC	All letters will be stored in upper-case format. Additionally, field comparison data will be upper-cased prior to any comparison.
	ZF	The data will be zero filled.
	ZS	Causes all leading zeros to be suppressed
	DATE[:YMD|MDY]	This field contains a date. The field must be six or eight digits long. The default date format is YMD. You can enter DATE or optionally, specify the date format. The date format is currently only used by applications. INTOUCH does NOT automatically switch date values into or out of the format specified.
	FULLTIME	Indicates that the field contains a date-time stamp and the time value is to be preserved. By default, INTOUCH stores/retrieves only the date portion of a date stamp field.
	APPLICATION:name	This is a user defined semantic and is not used by INTOUCH. A user can assign a name to indicate that the field is related to a specific application (i.e. accounting). Application programs can then ask for the application name and perform some action based on the data.
	DBFLD:fieldname	This is a special semantic for augmented definition files only. The DBFLD semantic is used to associate an augmented field definition with an actual database field. Fieldname is the actual name of the field in the database.

If you do not want any of the semantics, you can enter NONE.

If you are modifying an existing field, the default will be the semantics you have previously specified.

16.4.9 Prompt text

• can be any characters on the keyboard.
• can be up to 30 characters long.

If you are adding this field, the default will be the description you entered for this field.

16.4.10 Report heading

The heading can be up to 30 characters long.

To make a multi-line heading, separate the heading for each line with a comma (i.e. Cust,No).

16.4.11 Print mask

Print masks are created with the #, @ and % characters. SETUP will automatically provide the tilde (~) character for any literal (non-masking) characters found in the entered mask. Some examples:

Example 1 Example 2 ---------------- ------------- Data to be masked: AB1234XY AB1234XY Data to print as : (AB-1234-XY) AB 1234 XY Mask you enter : (##-####-##) ## #### ## SETUP displays : (##~-####~-##~) ##~ ####~ ##

You can refer to the chapter "Printing and Displaying Data" for more information on print masks.

16.4.12 Screen mask

16.4.13 Help text

The help text:

• can be up to 60 characters long.
• can consist of any characters on the keyboard.

16.4.14 Access rules

Access rules have the following formats:

• READ:read_access, WRITE:write_access
• NORMAL

NORMAL denotes READ:N, WRITE:N.

A is the most restricted access level. Z is the least restricted access level.

The access_rules are used in conjunction with the structure security level to determine whether or not a user can access the field.

When a user attempts to access a field, the structure security level is compared to the read or write access level defined for the field. If the field's access level is lower than the structure security level, access is allowed. For example:

If the structure READ access is J and the field READ access is T, the field data CAN be read. However, if the structure WRITE access is J and the field WRITE access is E, the field CANNOT be written to or changed.

16.4.15 Validation rules

The data entry program can access these validation rules to make sure that the data entered is valid prior to storing the data into the field.

Any rule that is valid to the INTOUCH VALID function can be entered here.

The validation rules are entered as a list of items separated by semicolons. For example:

required; digits; minlength 10

When you have completed your list, enter GOLD/F (i.e. press [PF1] and then the [F] key).

Please refer to Appendix A of this manual for detailed information on the VALID function.

When you have answered all the field prompts, the field definition will be added to the data dictionary. The screen will clear and you can define the next field or enter "\" or "EXIT" to return to the SETUP procedures menu.

16.4.16 Field Definitions and Key Fields --- General Information

There are times when you want to process two or more adjoining fields. For example, if you have a last name field, first name field and initial field and you want to sort the records by name, you would sort the three separate fields--last name, first name and initial.

To simply this process, you can define an additional field, FULL_NAME, which can consist of the three fields. When you define the FULL_NAME field, the starting position would be the first position of the last name and the length would be the total number of characters in the three fields. Then, when you want to sort or print the full name, you need only refer to one field, the FULL_NAME field.

Redefining fields becomes very useful when you need to set up unique key fields for RMS indexed files.

Key Fields

If you are creating an RMS indexed file, you will be designating one or more fields as key fields. RMS indexed files require at least one key field. When you use the CREATE procedure to create an RMS indexed file, you will be prompted for a primary key field and alternate key fields.

Key fields contain unique data which enables programs to locate records very quickly. For example, the customer number field could be a key field because all the customer numbers in all the records would be different. This type of key field is called a unique key field.

Duplicate key fields contain unique types of data but the data might be found in more than one record in the file.

Any defined or redefined field can be designated as a key field. However, it is best to use fields that normally will contain unique data as key fields. Common practice is to set up the first field as a key field.