|
|
|
The &NDBDEF verb adds, updates, or deletes field definitions to/from an NDB database. This feature is described for completeness. Use the NDB FIELD command (which provides a better way to perform these functions) instead.
This verb has the following format:
&NDBDEF dbname { [ ADD ] field-entry | UPDATE field-entry | DELETE field-entry }
where field-entry is (minimum acceptable abbreviations are in uppercase):
{ fieldname | ( fieldname
[ { Fmt= | Format= } { Char | Num | Float | Hex | X | Date |
Cdate | Time | Timestamp } ]
[ Key={ No | Yes | Unique | Sequence } ]
[ NULLField={ Yes | No } ]
[ NULLValue={ Yes | No } ]
[ Update={ Yes | No } ]
[ Caps={ Yes | No | Search } ]
[ Description=description ]
[ { USER1= | U1= } value ]
[ { USER2= | U2= } value ]
[ { USER3= | U3= } value ]
[ { USER4= | U4= } value ]
[ NEWNAME=name ]
[ BASE={ NONE | DECIMAL | HEX } ] ) }
Note: Specifying KEY=SEQUENCE changes the default of NULLFIELD=YES to NULLFIELD=NO, and UPDATE=YES to UPDATE=NO. Specifying NULLFIELD=YES or UPDATE=YES is invalid in this case. The default values shown apply for ADD only. For UPDATE, all operands that are not specified for the field name on the &NDBDEF statement, remain unchanged.
When an NDB is created (using the NDB CREATE command), there are no field definitions. Use the &NDBDEF ADD statement to insert at least one field definition into the database.
Field definitions can also be removed from an NDB. When field definitions are removed, any index tables associated with the field are removed, and the field data in any record becomes inaccessible. Whenever a record is updated, the deleted fields are removed from that record.
Operands:
Specifies the name of the NDB that you want to add or delete field definitions in is a required operand. An &NDBOPEN statement must have opened this NDB previously.
(Optional) Adds field definitions to the database.
At least one field definition must follow the ADD keyword.
Updates the listed fields.
At least one field definition must follow the UPDATE keyword.
The UPDATE option allows the following attributes to be updated at any time:
Deletes the listed fields from the database.
At least one field definition must follow the DELETE keyword.
Specifies the field to add or delete.
More than one field is added or deleted in one &NDBDEF statement, up to the maximum permissible NCL statement continuation limit.
fieldname is the name of the field. The name has the same format as an NCL variable name; that is, 1 through 12 characters alphanumeric, and, if the first character is numeric, the entire name must be numeric. Field names must be unique within an NDB. Do not precede the name with an ampersand (&), unless you want the actual field name to be the contents of the named variable.
The optional field operands for format, key, and so on, are ignored for a delete request (however, they must be valid).
If a field entry that follows the optional ADD keyword has no parenthesis around it, all the default values are used.
The optional operands are:
Specifies the field format. Valid values are:
Character data. Any character value may be provided. The data is stored internally as entered, with trailing blanks removed.
Numeric data. Values provided must be numeric, range -2147483648 to 2147483647. The data is stored internally as a binary fullword. If keyed, the keys collate correctly (that is, -1 before 0 before 1 if reading sequentially).
Floating-point data. The data is stored internally in IBM 8-byte normalized floating-point format. 15 significant digits and exponent ±70. If keyed, the keys collate on ascending numeric value.
Hexadecimal data. Values provided must be valid expanded-hexadecimal data. The data is stored internally in the hexadecimal-compressed format.
Note: Trailing zeros are significant, and the values ABCD and ABCD00 are regarded as different. If keyed, the keys collate on the binary value.
Date data. Values must be a valid date, the input format depending on the &NDBCTL DATEFMT option. The data is stored internally as unsigned packed, 3 bytes in DDMMYY format. If keyed, the keys collate on ascending dates.
Data is provided in one of several formats, controlled by the user, system language code, or both, and the current &NDBCTL DATEFMT setting. The data is stored internally as a 3-byte binary number being the number of days from 1/1/0001.
Data is provided in HHMMSS.TTTTTT format (the decimal point and fraction is truncated or omitted). The data is stored internally as a 5-byte binary number, being the number of microseconds since midnight.
Data is provided in YYYYYMMDDHHMMSS.TTTTTT format. The data is stored internally as a concatenation of a 3-byte CDATE and 5-byte TIME.
Default: Char
Note: For the UPDATE keyword, the field format can only be changed if the NDB is empty.
The keying option. Valid values are:
The data is not keyed.
The data is keyed, with duplicate key values permitted.
The data is keyed, with duplicate key values not permitted.
The data is keyed, with duplicate key values not permitted. In addition, the key is used as the data sequence key, similar to a VSAM primary key.
Default: No
Note: KEY=SEQUENCE forces NULLFIELD=NO and UPDATE=NO.
Specifies whether a field is absent in a record. Absent means not provided, and is not the same as present, with a null value (for example, all blank for a character field).
Means that the field is not required when a record is added, or the field can be set to null on update.
Means that the field must be present when a record is added, and the field cannot be set null on update.
Default: Yes
Specifies whether a field can be added with, or updated to, the null value (all blank for character, 0 for numeric, blank for hexadecimal, and 000000 for date).
Means that the null value is acceptable as a value for this field.
Means that the null value is invalid for this field. An attempt to add a record with this field containing the null value, or to update the field to a null value causes an error.
Default: Yes
Specifies whether the field value can change on an update statement.
Means that the value is changed on an &NDBUPD statement.
Means that the field value cannot be changed on an &NDBUPD statement.
Note: The field and its value are specified on an &NDBUPD statement in this case, but the value must be identical to the current value.
Default: Yes
Specifies the presence and preservation of lowercase data in FMT=CHAR fields. Specify this operand as CAPS=YES if coded on other field formats.
Lowercase data is folded to uppercase data in the stored value, and for the key value if the data is keyed. Key values on &NDBSEQ and &NDBGET, and search arguments on &NDBSCAN are also folded to uppercase.
Lowercase data is not folded to uppercase data in either the stored value, or the key value if the data is keyed. Key values on &NDBSEQ and &NDBGET, and search arguments on &NDBSCAN are not folded to uppercase.
Lowercase data is not folded to uppercase in the stored value, but is folded to uppercase for the key value if the data is keyed. Key values on &NDBSEQ and &NDBGET, and search arguments on &NDBSCAN are folded to uppercase. Retrieved data is as originally entered (subject to &CONTROL UCASE/NOUCASE).
Default: Yes
Note: NDBs are language-specific. The LANG operand on the NDB CREATE command specifies the language code when the NDB is created. The uppercase translation table for that language code is used for search arguments and CAPS=YES fields when translating to uppercase.
Allows an optional description of the field, up to 60 characters, to be stored with the field definition. This description is retrieved with the &NDBINFO statement. If there are special characters or blanks in the description, surround it with quotes.
Allows the storage of an optional user-defined piece of information, for example, a formatting indicator. The format is like description, but limited to eight characters.
Like USER1, USER2, USER3, and USER4 allow eight characters of extra, user-defined information to be stored.
This optional operand is used to rename the field, for UPDATE only.
Specifying NONE or DECIMAL for a numeric field results in an external representation as a signed decimal number (on output, a minus sign only is used, if necessary). Specification of HEX causes the external representation to be a hexadecimal string, with leading zeros suppressed on output. For negative numbers, the full seven hexadecimal digits are used (leading X'f').
For a field format other than NUMERIC, the BASE operand is ignored, but its syntax is checked.
Update a field definition to change the BASE operand—either by the &NDBDEF verb or the NDB FIELD command.
If the NDB is in load mode or newly created, the following attributes can also be updated: KEY (to/from anything except SEQ), and CAPS=N to CAPS=S and conversely. In addition, the field is renamed at any time.
The NDB ALTER command allows a field to be dynamically indexed without using this facility. However, if you want to alter many fields, using LOADMODE and a full rebuild of indexes would be faster than several passes, one per field.
Examples: &NDBDEF
This example adds four fields to the NDB named MYNDB:
&NDBDEF MYNDB (SURNAME FMT=C KEY=YES NULLFIELD=NO +
UPDATE=NO)+
(FIRSTNAME FMT=C KEY=N) +
(DOB FMT=DATE DESC='Date of birth') +
COMMENT
This example deletes two fields from the NDB named MYNDB:
&NDBDEF MYNDB DELETE DOB COMMENT
This example adds the field SUBURB to the NDB named MYNDB, as a non-keyed character field that can be updated:
&NAME = SUBURB &NDBDEF MYNDB ADD &NAME
Notes:
If the database is to have a sequence key, it must be the first field ever defined, and the field definition cannot be deleted. There can only be one sequence key.
Currently there is no facility for making a field keyed, or removing the keys on a field, once it is defined.
The NDB RESET command removes all data from an NDB, but leaves the field definitions intact.
If there are any errors in the definitions, none of the definitions are added or deleted.
The NCLEX01 security interface can disable the &NDBDEF verb. If you disable the verb, the NDB FIELD command becomes the only way to alter NDB field definitions. This feature allows protection of NDB field definitions.
Note: See also the NDB CREATE and NDB RESET commands in the Online Help.
| Copyright © 2009 CA. All rights reserved. |
|