# Data Dictionary Maintenance

Element Description |

The Element Description window is used to add, edit, copy and delete a data element for a selected table. To make bulk changes to multiple data elements in the PxPlus data dictionary and apply the changes to selected tables, use the Bulk Edit Data Elements utility.

After a table is entered or selected on the Data Dictionary Maintenance Main Panel, click the Elements tab. Invoke the Element Description window by clicking the button in the Dtl column of the Data Elements grid.

This window is divided into four tabbed folders - Display, User Aids, Query and ODBC - for defining the attributes of an element.

Name | Unique name of the element - this is the variable name used in the primary IOList. Naming conventions for variables apply. Select from a drop-down list of data elements defined in the Data Dictionary for the selected table or type a new element name. A new element name must start with an alpha character (A-Z or a-z) or an_ (underscore), followed by any combination of A-Z, a-z, 0-9 or _ (underscore). If an element name contains a . (dot), a message will display, warning that column names containing a dot may not be ODBC-compliant. #### Note: When a new element name is entered, it will be checked against the Reserved Words list to determine if it is restricted for use in the Data Dictionary. If it is found, a warning message will display. (User Reserved Words Maintenance was added in PxPlus 2020.) Click the Browse buttons to browse to existing elements. Click the Copy Element button to copy an existing element to a new element. If unsaved changes are detected when selecting these buttons, a message will display to save the changes. The Update Global Dictionary Elements in other Files button is used to update other data files in the data dictionary when an element in the Global Dictionary has been changed. It is possible to restrict element names. To exclude names, such as SQL keywords, create a list of rejected names (one item per line) in the text file dde_exclude.txt located in the *ext directory; i.e. PathToPxPlus/lib/_ext/dde_exclude.txt. If you choose your own file/location for this list, the path must be loaded into the %DDE_Exclude$ variable. When this file is present, new names will be checked against the restricted list and rejected if found. No action is taken for elements that already exist. Text in this file is treated as case insensitive and spaces are stripped. If the Name field of an existing element is changed and that element name does not exist, a message will display. Responding Yes renames the current element. Responding No creates a new element. Responding Cancel puts back the original Name. Save any changes by clicking the OK or Apply buttons. (First/Last Element browse buttons were added in PxPlus 2019.) (The changed Name message was added in PxPlus 2020.)
(Copy Element) | (Available when an existing Element Name is selected) Button used to create a new element by copying the settings from an existing element. Once it is created, the new element must be saved, as the Copy process does not do this. (The Copy Element button was added in PxPlus 2014.)
(Update Global Dictionary Elements in other Files) | (Available when an existing Global Dictionary Element Name is selected) Button used to invoke the Update Global Dictionary Elements window only if both of these conditions are met:
1. | The element being updated is a Global Dictionary element. AND
2. | Elements with the same Name and Type as the global element exist in other data files. If no such elements exist, a message will display, and the Update Global Dictionary Elements window will not be invoked.
This button is disabled while a global element is being edited. When the element is recalled, this button is enabled. (The Update Global Dictionary Elements in other Files button was added in PxPlus 2019.)
Class | Enter a data class to load the information from the data class definition into the element's fields. See Data Classes. The class is also used to associate a control type (i.e. Multi-Lines, Drop Boxes, List Boxes, Radio Buttons and Check Boxes) with the element for use within NOMADS and its sub-systems, as well as in iNomads. To enter a data class, use any of the following methods: Click the Query button (binoculars) to select from a list of predefined data classes (if any). Type the name of an existing data class. Create a new data class by clicking the Data Class Maintenance button to launch Data Class Definitions maintenance. If the data class is changed, a message will display prior to overwriting any information. If the data class assigned to the element has been deleted in Data Class Definitions maintenance, the text ** Class not on File ** will display. (The dark red text indicating a deleted Data Class was added in PxPlus 2021.)
(Data Class Maintenance) | Button used to launch Data Class Definitions maintenance for creating or editing a data class.
(Reapply Data Class) | (Available when a Class is entered) Button used to update element fields with current information from the selected data class. A message will display only if element fields are found that are populated with existing values different from the values in the selected data class. Clicking Yes will overwrite existing values for the listed element fields. Clicking No will not overwrite existing values for the listed element fields but will update element fields not currently populated. Clicking Cancel will not make any changes. #### Note: If a Class is entered for the element, changes to that class will not be reflected in the element until the Reapply Data Class button is selected. Care should be taken when using the Reapply Data Class button or changing the Class entered for the element, as this will overwrite any existing values. (The Reapply Data Class button was added in PxPlus 2018.)
Alt. Name | Alternate name for use in the alternate IOList (for legacy programs). If an alternate IOList is defined, then you must define an alternate name for all elements in the file. The alternate name must be a variable name (e.g. A$ or A$[1]). Supports only fields that use the Delimited format mask. See Format Mask.
DB Null if Empty | (Not Applicable when File Type is a PxPlus Native File) Check box to indicate that a null value can be returned for the element when interacting with a Prefix or Link file created from an external database. See Using External Databases to Create a Data Dictionary. (The DB Null if Empty check box was added in PxPlus 2023.)
External Only | Check box to indicate that the element forms part of an external key and is not duplicated in the data portion of the record. This check box is enabled only when the Display tab is selected. Example: Key: CST_ID$ Data: CST_NM$, CST_ADDR$, CST_PHONE$ In this case, CST_ID$ forms the key and is not duplicated in the data portion of the record.
Required | Check box to indicate that the element is a required field and must contain data before the record can be written in File Maintenance.
Upper Case | Check box to indicate that the data should always be in uppercase letters. Used by NOMADS sub-systems.
Read Only | Check box to indicate that the element is designated as read only or locked. Used by NOMADS sub-systems. (The Read Only check box was added in PxPlus 2021.)
Display
Properties |
Type | Field indicates whether the element is Numeric or String.
Format Mask | Options that define the format for writing the data field to the file. See Format Mask Options.
Delimited | Delimited by field separator. Sample IOL format: DELIMITED$, NUMERIC_DLM
Fixed | Padded to the specified length when written but stripped of trailing spaces when read. Sample IOL format: FIXED$:[CHR(7)], NUM_FIXED:[NUM(7)]
Padded | Padded with spaces based on the defined length. Numerics are padded with leading zeros. Sample IOL format: PADDED$:[LEN(6)], NUM_PADDED:[NUM(7)]
Substring | Similar to Fixed, but if the stored data is shorter than the specified length, a READ will return up to but not including the field separator. (Used in conjunction with Last Substring.) This format is often used for flag fields. Sample IOL format: SUBSTRING$:[LEN(5,SEP=SEP)]
Last Substring | Similar to Fixed, but delimited by field separator. Sample IOL format: LAST_SUBSTRING$:[LEN(SEP,SIZ=4)]
Binary Numeric | Signed binary, maximum 6 bytes, no delimiter binary numeric. Sample IOL format: Binary_Num :[BIN(Length,Scale)] Example: Length=2 stores a value ranging from -32768 to +32767. Stores 1 as $0001$. Stores -1 as $FFFF$.
Decimal | Maintains the sign, decimal is explicit, no delimiter. Sample IOL format: [DEC(Length,Scale)] e.g. Length=10.2 Stores -1 as ^^^^^-1.00 (where ^ is a space). Stores 123.45 as ^^^^123.45 (where ^ is a space).
Decimal Delimited | Maintains the sign, decimal is explicit, delimited (same as Decimal, but followed by a delimiter). Sample IOL format: [DEC(Length,Scale,SEP=SEP)]
Signed Fixed Numeric | Maintains the sign, decimal is implied, no delimiter. Sample IOL format: [SGN(Length,Scale)] e.g. Length=10.2 Stores -1 as 000000100-. Stores 123.45 as 000012345+.
Unsigned Integer | Unsigned binary, maximum 6 bytes, no delimiter. Sample IOL format: [INT(Length,Scale)] e.g. Length=2 stores a value ranging from 0 to 65535. Stores 1 as $0001$. Stores 65535 as $FFFF$.
Short Description | Brief description of the element, which can be a Fixed value, Expression or Message Library Reference.
Default / Input Value | See Format Mask Options.
Validation / Rules | See Format Mask Options.
Print / Input Format | See Format Mask Options.
User Defined Tag Field | See Format Mask Options.
User Aids
Help Reference | Help text to be launched when the user presses Shift - F1. Click the drop-down arrow for selections to access form fields for specifying the different definitions (either External or Internal).
External | Standard (default) help definition. This assigns a predefined help file that can be Fixed text (string literal) or an Expression (or string variable). Specify the starting point in the help file by Keyword or by Reference. The Popup check box allows you to set the display to be a popup rather than an independent window.
Internal | Simplified help stored in the library file. This help consists of text only, Fixed, Expression or Message Library Reference. Because the help text is preserved in the library itself, it eliminates the need to create separate help files.
Floating Tip | Mouse pointer message for the control (Fixed value, string Expression or Message Library Reference). You can customize the floating tip by adding a tip title, descriptive tip text and a hyperlink. These features enhance the visual display and functionality of the tip by providing users with much needed information at their fingertips. You can define either a Standard tip or an HTML tip that provides a simplified HTML Editor for customizing the tip text. To do this, click the button to the right of the Floating Tip multi-line input to invoke the Define Info Tip dialogue. See Defining an Info Tip. #### Note: The Floating Tip drop box and multi-line input cannot be changed once an HTML tip has been defined. (The Floating Tip option was added in PxPlus 2021.)
Notes | A multi-line input control used for entering notes about the element. Press Enter to start a new line. Maximum 1024 characters. Alternatively, notes can be added or edited for an element by using the Add/Edit Notes button beside the Data Elements grid. (Support for increasing input maximum was added in PxPlus 2022.)
Query
Query Type | Type of query to associate to the control: Panel, Program, Non-Query Logic, Spinner. Depending on the Query Type selected, different information is entered. For an explanation of each type and the information to enter, see Query Type. (Support for Non-Query Logic was added in PxPlus 2018.)
Panel/Program Attributes | (Available if Query Type is Panel or Program)
Panel | Process a query panel (from the specified Library). Can be either a Fixed value or an Expression (evaluated at run time). See Panel Information. The Define button uses the Panel name to either create a new or edit an existing query definition.
Program | Execute a specified Query Program. Can be either a Fixed value or an Expression (evaluated at run time).
(The Define button was added to Element Description in PxPlus 2023 Update 1.)
Non-Query Logic | (Available if Query Type is Non-Query Logic) Select the type of logic (Link, Perform, Call, Execute, etc.) and the program logic reference "program;label". Example: PERFORM "programs/browse;Browse_Directory" (Support for Non-Query Logic was added in PxPlus 2018.)
Spinner Attributes | (Available if Query Type is Spinner) (Numeric Only) Associate a spinner control with the element in place of a query. Sets the Increment value for scrollbar movement, as well as the Start (initial) and End (maximum) values. Example: If Increment = 1, Start = 1, and End = 9999, then the initial value would be 1, scrollbar movement would increase/decrease by 1 and the maximum would be 9999.
ODBC
ODBC Hide/No Show Options |
Show Column | (Default) Indicates no data suppression.
Hide Column (Column is suppressed) | Indicates that the field will not be presented to the user. Primarily used for filler values.
No Show (Value is not displayed) | Indicates that the field name will be presented to the user; however, the data will never be returned.
Security | Button used to set up and access the optional security system that controls user access to the system. See Security Manager.
Clear | Button used to clear the current record and put focus on the Name field.
Delete | (Available when an existing element is selected) Button used to delete the selected data element. When selected, a message asks to confirm the deletion.
OK | Adds or updates the current element, then closes the Element Description window. The new element is added to the bottom of the Data Elements grid. Use the Move Up/Move Down buttons beside the grid to change the position of the new element. If saving changes to a Global Dictionary element and elements with the same Name and Type exist in other data files, a message asks if you want to apply the same changes to the other elements. Responding Yes invokes the Update Global Dictionary Elements window for updating all or only selected elements. Responding No does not change the other elements. (Update Global Dictionary Elements was added in PxPlus 2019.)
Cancel | Closes the Element Description window without saving any changes and returns to the Elements tab.
Apply | Allows you to consecutively insert or update multiple data elements to the Data Dictionary for the current table without having to exit the Element Description window. After entering all the details for the element being added or modified, select Apply. A message displays to confirm that the element has been added or updated. The Element Description window is then cleared, and you can add or modify another element. If saving changes to a Global Dictionary element and elements with the same Name and Type exist in other data files, a message asks if you want to apply the same changes to the other elements. Responding Yes invokes the Update Global Dictionary Elements window for updating all or only selected elements. Responding No does not change the other elements. New elements that are entered consecutively and then saved using the Apply button are added to the bottom of the Data Elements grid in the same entry order. Use the Move Up/Move Down buttons beside the grid to change the order of the elements. (Update Global Dictionary Elements was added in PxPlus 2019.)

#### Note:
A Space-Padded format is also available for numeric table elements, which results in a non-delimited fixed-length numeric field padded with spaces on the left. It applies the existing LEN( ) format. This type is not supported by the PxPlus SQL ODBC Driver, and it is only available in the Data Dictionary Maintenance window if the global variable %ALLOW_NON_ODBC_TYPE_LEN is set to non-zero.

## Data Storage Formats

Data Storage Formats
String Formats | IOL Format (l = length) | Size | Dlm | Sign | Decimal | Pad
Delimited |  | Variable | Y | N/A | N/A | N/A
Fixed | [CHR(l)] | Fixed | N | N/A | N/A | Right/Space
Padded | [LEN(l)] | Fixed | N | N/A | N/A | Right/Space
Substring | [LEN(l,SEP=sep$)] | Fixed | N | N/A | N/A | Right/Space
Last Substring | [LEN(sep$, SIZ=l)] | Fixed | Y | N/A | N/A | Right/Space

Data Storage Formats
Numeric Formats | IOL Format (l = length, s = scale) | Size | Dlm | Sign | Decimal | Pad
Delimited |  | Variable | Y | Explicit | Explicit | N/A
Fixed | [NUM(l,s)] | Fixed | N | None | Implied | Left/Zero Right/Zero
Padded | [NUM(l,s)] | Fixed | N | None | Implied |
Substring | [NUM(l,s)] | Fixed | N | None | Implied |
Last Substring | [NUM(l,s,SEP=sep$)] | Fixed | Y | None | Implied |
Signed Fixed Numeric | [SGN(l,s)] | Fixed | N | Explicit | Implied | Left/Zero Right/Zero
Decimal | [DEC(l,s)] | Fixed | N | Explicit | Explicit | Left/Space Right/Zero
Decimal Delimited | [DEC(sep$, SIZ=l,s)] | Fixed | Y | Explicit | Explicit |
Binary Numeric* | [BIN(l,s)] | Fixed | N | Implied | Implied | Left/$00$
Unsigned Integer* | [INT(l,s)] | Fixed | N | N/A | Implied | Left/$00$

Examples (Space characters are represented by "^" and field delimiters by "|")
String Formats | Length | Stores null as | Stores "abc" as …* | Stores "abcdef" as …*
Delimited | 5 | | | abc| | abcdef|
Fixed | 5 | ^^^^^ | abc ^^ | abcde
Padded | 5 | ^^^^^ | abc ^^ | abcde
Substring | 5 | ^^^^^ | abc ^^ | abcde
Last Substring | 5 | ^^^^^| | abc ^^| | abcde|
Numeric Formats | Length | Stores 0 as …* | Stores -1.1 as …* | Stores 12345.678 as … *
Delimited | 6.2 | 0| | -1.1| | 12345.678|
Fixed | 6.2 | 000000 | 000110 | 234567
Padded | 6.2 | 000000 | 000110 | 234567
Substring | 6.2 | 000000 | 000110 | 234567
Last Substring | 6.2 | 000000| | 000110| | 234567|
Signed Fixed | 6.2 | 00000+ | 00110- | 34567+
Decimal | 6.2 | ^^ 0.00 | ^ -1.10 | Error #43
Decimal Delimited | 6.2 | ^^ 0.00| | ^ -1.10| | Error #43
| 1 / 32767 | -1 / 65535
Binary Numeric | 2 | $0000$ | $0001$ / $7FFF$ | $FFFF$
Unsigned Integer | 2 | $0000$ | $0001$ / $7FFF$ | $FFFF$

## Format Mask Options

The following Format Mask options apply to key fields that are external only; i.e. not found in the data portion of the record:

Padded Key | Field padded with spaces based on the defined length.
Fixed Key | Field padded to the specified length, unless it is the last key component. For redundant external key fields (i.e. fields that form both the external key, as well as part of the data portion of the record), define the format as it should be defined for the data portion. Depending on the format chosen, the format for the corresponding key field defaults to the following:
Data Field Format | Resulting Key Format
Delimited | Fixed [CHR(n)]
Fixed [CHR(n)] | Fixed [CHR(n)]
Padded [LEN(n)] | Padded [LEN(n)]
Substring [LEN(n,SEP=SEP)] | Padded [LEN(n)]
Last Substring [LEN(SEP,SIZ=n)] | Padded [LEN(n)]
Length | Set the maximum length of the data field. Numeric field lengths can be defined using implied decimal format. Example: 6.2: 6 represents total length of the field, including explicit signs and decimals, where applicable; 2 represents scaling factor or number of decimal places.
Occurs | Dimension, if element represents an array (e.g. 1:3). If a single number (e.g. 3), represents a single element in the third position of an array (e.g. X$[3]) rather than the entire array. #### Note: Arrays are not supported by the File Maintenance and Query utilities.
Default Value | Value to be loaded when the field is first initialized. Can be a Fixed value, Expression or Message Library Reference.
Validation | Comma-separated validation rules; e.g. 1-3,9 or Y,N,M. Can be Fixed text or an Expression.
Print Format | Output format mask, either Fixed text (string literal) or Expression.
User Defined Tag Field | Data/tag field used to pass information on such things as formatting, error messages and validation rules. Can be Fixed text (string literal) or an Expression (evaluated when the object is created). NOMADS places the contents of this field in a variable using the element name with a .TAG$ extension.