Enter the length of this field. The length should be the number of character positions this field will contain. Fields can be any length. The length must be given as an integer number.
You can also enter the ending position for the field length. You enter "P" followed by the ending position. For example: P5
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.
Enter the number of times that this field occurs in the data record. The default number of occurrences is "1".
If the field being defined is an array, enter the number of elements in the array.
Enter the semantics (attributes) that apply to this field. The semantics describe what type of data will be in the field. For example, if this is a dollar amount field you would select NUM:2 which means that this is a numeric field with two decimal places.
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.
Enter the prompt text for this field. The prompt text will be used when data is entered for this field. The prompt text:
If you are adding this field, the default will be the description you entered for this field.
Enter the heading you want to appear on reports. This heading will appear at the top of the report column containing this field's data. If you are adding a new record, the default report heading is the field name you entered.
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).
Enter a print mask for this field. The print mask is used to display information entered into this field. The print mask will be used whenever you use INTOUCH's PRINT statement to print this field's information, or when you use one of the INTOUCH programs such as Guided Query Language.
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.
The screen mask is used by applications to enter data into this field. A program can ask for the screen mask and use it in whatever manner that is desired. The format should be the same as for the print mask.
HELP text can be entered for this field. The help text can be displayed during data entry if the user types "HELP" or presses the Help key at this field prompt when in MAINTAIN. Custom applications can also display this help text.
The help text:
Enter the access rules for this field. The access rules determine who will have access to this field. NORMAL allows users to read, add and change field information.
Access rules have the following formats:
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.
You can enter validation rules for this field. The validation rules will be used to validate data entered by a data entry program.
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
Normally, when you define the record fields, each defined field represents a single piece of data in the record. This allows your programs access to all of the record data.
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.
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.
A key field can be defined which consists of two or more fields. If the fields which make up this key field are not adjoining (i.e. one after the other), this is called a segmented key field. Key fields consisting of two or more fields, whether segmented or not, must have a length that equals the total length of all the segments that make up the key field.
The SHOW procedure displays information about the fields defined in the data dictionary and also displays structure information.
You can use the arrow keys to select the Show procedure from the SETUP procedures menu.
SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +---Setup Procedure---+ | Define fields +------Show Option-------+ | Show | Brief field display | | Modify structure | Full field display | |-------------------| List fields | | Create data file | Structure | | EXIT +------------------------+ +---------------------+ EXIT = Exit \ = Back HELP = Help
The SHOW procedure has four options:
SETUP creates the listings in report format so that you can display the field and structure information on your screen, print a hardcopy or save the information on disk.
After a report is created, you can select an output option from the Output Options menu. The default is Screen which will display the report to your screen. The line under the Output Options menu tells you the name of the temporary report file that was created.
+--------------------- Output Options ---------------------+ | Screen | System Printer | Laser Printer | | Printer Port | Save to Disk | EXIT | +----------------------------------------------------------+ Ready to print user:[tester]setup_show_definition_210006.tmp
If you are in the middle of displaying a report and want to exit out of the display, enter CTL/Z and you will return to the Output Options menu.
To return to the SETUP procedures menu, you can use the arrow keys to select the EXIT option or press "\" (backslash key).
The Brief Field Display shows the field name, description, first position of the field, field length, number of occurrences, last field position, data type, print mask and semantics.
Example 16-7 SHOW - Brief Field Display Example
08-Mar-1995 Definitions for: CUSTOMER.DEF Page: 1 Field Name Description First Length Occurs Last Dtype Print Mask --------------- ----------------- ----- ------ ------ ----- ----- ---------- CUSTNBR Customer number 1 5 1 5 CH none Semantics : none NAME Customer name 6 25 1 30 CH none Semantics : none ADDR1 Address line 1 31 25 1 55 CH none Semantics : none ADDRESS Address array 31 25 1 55 CH none Semantics : none
The Full Field Display shows all of the definition information. Example 16-8 SHOW - Full Field Display Example
08-Mar-1995 Definitions for: CUSTOMER.DEF Page: 1 Field Name Description First Length Occurs Last Dtype Print Mask --------------- ----------------- ----- ------ ------ ----- ----- ---------- CUSTNBR Customer number 1 5 1 5 CH none Semantics : none Prompt text: Customer number Heading : Cust# Help : none Screen mask: none Validations: none NAME Customer name 6 25 1 30 CH none Semantics : none Prompt text: Customer name Heading : Customer name Help : none Screen mask: none Validations: none
The List Fields Display shows the field name, description, first position of the field, field length and data type. Example 16-9 SHOW - Fields List Display Example
08-Mar-1995 CUSTOMER.DEF - FIELDS Page: 1 Field Name Description First Length DT -------------------------------- ------------------------------ ----- ------ -- CUSTNBR Customer number 1 5 CH NAME Customer name 6 25 CH ADDR1 Address line 1 31 25 CH ADDRESS Address array 31 25 CH ADDR2 Address line 2 56 25 CH CITY City 81 20 CH STATE State 101 2 CH ZIP Zip 103 5 CH
The Structure option of SHOW displays information about the structure and security access levels.
Example 16-10 SHOW - Structure Display Example
08-Mar-1995 Structure: CUSTOMER.STR Page: 1 Structure name : CUSTOMER.STR Dataset : CUSTOMER.DAT Record system : RMS Data dictionary: CUSTOMER.DEF Access levels : SECURITY:N, READ:N, WRITE:N, UPDATE:N, DELETE:N
16.6 MODIFY STRUCTURE Procedure
The MODIFY STRUCTURE procedures allow you to:
SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +---Setup Procedure---+ | Define fields | | Show +----Modify structure-----+ | Modify structure | General information | |-------------------| Security information | | Create data file +-------------------------+ | EXIT | +---------------------+ EXIT = Exit \ = Back HELP = Help
You can use the arrow keys to select the Modify structure procedure from the SETUP procedures menu and then select one of the two modify structure options.
16.6.1 Modify Structure General Information
When you select the modify structure General information option, SETUP will display the current structure information.
SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +Database Engine+ | RMS | | RDB | | DBMS | | USERBASE | | POISE | | FASTFILE | | S1032 | | INGRES | | DBASE3 | | ADABAS | | ORACLE | |---------------| | EXIT | +---------------+ EXIT = Exit \ = Back HELP = Help
You will be prompted for:
You can either press Return at the prompts to keep the current information or enter new information. If you need clarification on any of the prompts, you can refer back to the SETUP Prompts section in this chapter.
After the last prompt is answered, the STR file will be updated with the new information.
You will be returned to the SETUP procedures menu where you can select another option or exit SETUP.
16.6.2 Modify Structure Security Information
When you select the modify structure Security information option, SETUP will display the current security information.
SETUP V4.2 Structure Security and Access Levels Structure security level: N Read access level : N Update access level : N Write access level : N Delete access level : N Structure security level? N Security levels are A to Z EXIT = Exit \ = Back HELP = Help
You will be prompted for:
You can either press Return at the prompts to keep the current information or enter new information.
Enter the security level associated with this structure.
The security level is a single letter in the range of A to Z.
Security level A is the highest level of security. Security level Z is the lowest level of security.
Enter the access level required to read a data record in this structure.
The read access level is a single letter in the range A to Z. A is the most restricted access level. Z is the least restricted.
When an attempt is made to read a record from this structure, INTOUCH will compare the structure security level to the read access level. If the read access level is lower than the structure security level, the read request will be allowed.
For example:
Structure level Read access level Access
--------------- ----------------- ------
K R Allowed
K E Denied
K K Allowed
Enter the access levels required to update, write, delete data records in this structure. Answer each of the prompts with a letter from A to Z.
After the last prompt is answered, the STR file will be updated with the new security information.
You will be returned to the SETUP procedures menu where you can select another option or exit SETUP.
SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +---Setup Procedure---+ | Define fields | | Show [>| | Modify structure [>| |---------------------| | Create data file | | EXIT | +---------------------+ EXIT = Exit \ = Back HELP = Help
Selecting the Create data file option from the SETUP procedures menu will allow you to create a data file.
After the CREATE option has been selected, the create screen will be displayed and you will be prompted for some information.
Note
If the database engine is RMS, the following screen is displayed. If the database engine is not RMS, a similar screen will be displayed. The screen heading shows the database engine and name of the file that will be created.
Example 16-11 CREATE Procedure RMS Input Screen
SETUP V4.2 Creating RMS data file: CUSTOMER.DAT File organization: Recordsize : +RMS File Organization+ | Indexed | | Sequential | +---------------------+ EXIT = Exit \ = Back HELP = Help