| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This procedure checks user-supplied data against the data dictionary definition of a field. If the input data passes the validation, the internal and, optionally, the external forms of the data are returned. In this respect, CHK^DIE is the inverse of the $$EXTERNAL^DILFD call.
While this procedure indicates that a user's response is valid according to a field's definition, it does not assure that a value can be filed in a particular record. In order to verify that a value can be filed, use the VAL^DIE or FILE^DIE calls (with the E flag). CHK^DIE does not have IENS as input; it is ignorant of the state of the data.
Do not pass a VALUE of null or "@" to CHK^DIE. This procedure cannot verify that deletion of values from the database is appropriate. Again, use VAL^DIE or FILE^DIE (with E flag) for this purpose.
CHK^DIE(FILE,FIELD,FLAGS,VALUE,.RESULT,MSG_ROOT)
| FILE |
(Required) File or subfile number. |
|
| FIELD |
(Required) Field number for which data is being validated. |
|
| FLAGS |
(Optional) Flags to control processing. The possible values are: |
|
| H | Help (single "?") is returned if VALUE is not valid. | |
| E | External value is returned in RESULT(0). | |
| VALUE |
(Required) Value to be validated, as entered by a user. VALUE can take several forms depending on the data type involved, e.g., a partial, unambiguous match for a pointer or any of the supported ways to input dates (such as "TODAY" or "11/3/93"). |
|
| .RESULT |
(Required) Local variable that receives output from the call. If VALUE is valid, the internal value is returned. If not valid, ^ is returned. If the E flag is passed, external value is returned in RESULT(0). NOTE: This array is killed at the beginning of each call. |
|
| MSG_ROOT |
(Optional) Root into which error, help, and message arrays are put. If this parameter is not passed, these arrays are put into nodes descendent from ^TMP. |
|
See input parameters .RESULT and MSG_ROOT.
RESULT = internal value or ^ if the passed VALUE is not valid.
RESULT(0) = external value if the passed VALUE is valid and E flag is present.
In the following example, data for a date/time data type is being checked. Note that the external form of the user's input, which was "T-180", is passed. In this case, the value was acceptable, as shown below:
>S FILE=16200,FIELD=201,FLAG="E",VALUE="T-180"
>D CHK^DIE(FILE,FIELD,FLAG,VALUE,.RESULT)
>ZW RESULT
RESULT=2930625
RESULT(0)=JUN 25,1993
In addition to errors that indicate that the input parameters are invalid, the primary error code returned is:
| 120 | Error occurred during execution of a FileMan hook. |
| 701 | Value is invalid. |
| What is checked |
This call verifies that the VALUE passed is valid by passing it through the field's INPUT transform. Also, if the field has any screens, those screens must be passed. If the field is a pointer or variable pointer, this call verifies that there is an unambiguous match (or partial match) for VALUE. |
| Entry number caution |
No internal entry numbers are available when the INPUT transform or screens for the field are executed. Therefore, the INPUT transform and screens cannot reference any entry numbers using either the DA() array or the D0, D1, D2, etc., variables. Likewise, Xecutable Help cannot reference an entry number if the H flag is sent. |
Reviewed/Updated: March 10, 2007