Data Base Server API: Editing Utilities ICR (2053)

Name

Value

NUMBER

2053

IA #

2053

DATE CREATED

1997/07/02

CUSTODIAL PACKAGE

VA FILEMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

DIE

NAME

Data Base Server API: Editing Utilities

GENERAL DESCRIPTION

Editing Utilities

CHK: Data Checker FILE: Filer HELP: Helper UPDATE: Updater VAL: Validator WP:
Word Processing Filer $$KEYVAL^DIE( ): Key Validator VALS^DIE( ): Fields
Validator

STATUS

Active

DIE

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

CHK()

This procedure checks user-supplied data against the
data dictionary definition of a field.

Format CHK^DIE(FILE,FIELD,FLAGS,VALUE,.RESULT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	(Required) File or subfile number.
FIELD	Input	(Required) Field number for which data is being validated.
FLAGS	Input	(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	Input	(Required) Value to be validated, as entered by a user.
.RESULT	Both	(Required) Local variable that receives output from the call.
MSG_ROOT	Both	(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.

FILE()

This procedure: Puts validated data that is in
internal FileMan format into the database. OR: Validates data that is in
external (user-provided) format, converts it to internal FileMan format, and
files valid data into the database.

Format FILE^DIE(FLAGS,FDA_ROOT,MSG_ROOT)

VARIABLES

TYPE

VARIABLES DESCRIPTION

FLAGS

Input

(Optional) Flags to control processing. The possible
values are:

K  LocKing is done by the Filer. (See discussion of Locking below.)  S Save
FDA. If this flag is not set and there were no errors during the filing
process, the FDA is deleted. If this flag is set, the array is never deleted.
E  External values are processed. If this flag is set, the values in the FDA
must be in the format input by the user. The value is validated and filed if
it is valid.  If the flag is not set, values must be in internal format and
must be valid; no validation or transformation is done by the Filer

FDA_ROOT

Input

(Required) The root of the FDA that contains the data
to file.

MSG_ROOT

Both

(Optional) The root of an array (local or global)
into which error messages are returned. If this parameter is not included,
error messages are returned in the default array-^TMP("DIERR",$J).

HELP()

This procedure retrieves user-oriented help for a
field from the Data Dictionary and other sources.

Format HELP^DIE(FILE,IENS,FIELD,FLAGS,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	(Required) File or subfile number.
IENS	Input	(Optional) Standard IENS indicating internal entry numbers.
FIELD	Input	(Required) Field number for which help is requested.
FLAGS	Input	(Required) Flags used to determine what kind of help is returned by the call. If a lower case letter is shown, use it to suppress that kind of help-useful in conjunction with ? or ??. The possible values are: ? Help equivalent to user entering one "?" at an edit prompt. (Also help returned for an invalid response.) ?? Help equivalent to user entering "??" at an edit prompt. A All available help for the field. F Fields that can be used for lookups. Returned for top-level .01 fields and for pointed-to files for pointer data types. For pointed-to files, the "F" flag is effective only if the "G" flag is also sent. H Help prompt text. X Xecutable help-the MUMPS code contained in Xecutable Help is executed. In order to have the help returned in an array, the executed code must use EN^DDIOL to load the help message. D Description text for the field; this may be multiple lines. P Pointer screen description. C Set of Codes screen description. T Date/Time generic help. This help text is customized based on the allowable and required elements of the particular Date/Time field. S Set of codes possible choices. Any screen that exists on the set of codes field is applied so that only actually selectable choices are presented. U Unscreened set of codes choices. V Variable pointer help that lists the prefixes and messages associated with a particular variable pointer field. B (b) Brief variable pointer help. A single line beginning with "To see the entries ...". M More variable pointer help. Detailed description of how to enter variable pointer data. G (g) getting help from pointed-to file. Help for the .01 field of pointed-to file is returned.
MSG_ROOT	Both	(Optional) Closed root into which the output from the call is put. If not supplied, output is returned in ^TMP.
DIHELP	Output	Number of lines of help text returned
TMP("DIHELP",$J,n)	Output	Array containing the lines of help text. The text is found in integer subscripted nodes (n), beginning with 1. A blank node is inserted between each different type of help returned.

UPDATE()

This procedure adds new entries in files or subfiles.

Format UPDATE^DIE(FLAGS,FDA_ROOT,IEN_ROOT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FLAGS	Input	(Optional) Flags to control processing. The possible values are: E External values are processed. If this flag is set, the values in the FDA must be in the format input by the user. The Updater validates all values and converts them to internal format. Invalid values cancel the entire transaction. If the flag is not set, values must be in internal format and must be valid. S The Updater Saves the FDA instead of killing it at the end.
FDA_ROOT	Input	(Required) The name of the root of a FileMan Data Array, which describes the entries to add to the database.
IEN_ROOT	Both	(Optional) The name of the Internal Entry Number Array (or IEN Array). Output: As the Updater assigns record numbers to the records described in the FDA, it sets up nodes in the IEN Array to indicate how it decoded the sequence numbers.
MSG_ROOT	Both	(Optional) The array that should receive any error messages. If the MSG_ROOT is not passed, errors are returned descendent from ^TMP("DIERR",$J).

VAL()

The purpose of the Validator procedure is to take the
external form of user input and determine if that value is valid.

Format VAL^DIE(FILE,IENS,FIELD,FLAGS,VALUE,.RESULT,FDA_ROOT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	(Required) File or subfile number.
IENS	Input	(Required) Standard IENS indicating internal entry numbers.
FIELD	Input	(Required) Field number for which data is being validated.
FLAGS	Input	(Optional) Flags to control processing. The possible values are: E External value is returned in RESULT(0). F FDA node is set for valid data in array identified by FDA_ROOT. H Help (single ?) is returned if VALUE is not valid. R Record identified by IENS is verified to exist and to be editable. Do not include "R" if there are placeholders in the IENS.
VALUE	Input	(Required) Value to be validated as input by a user.
.RESULT	Both	(Required) Local variable which receives output from call.
FDA_ROOT	Both	(Optional; required if F flag present) Root of FDA into which internal value is loaded if F flag is present.
MSG_ROOT	Both	(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.

WP()

This procedure files a single word processing field.

Format WP^DIE(FILE,IENS,FIELD,FLAGS,WP_ROOT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	(Required) File or subfile number.
IENS	Input	(Required) Standard IENS indicating internal entry numbers.
FIELD	Input	(Required) Field number of the word processing field into which data is being filed.
FLAGS	Input	(Optional) Flags to control processing. The possible values are: A Append new word processing text to the current word processing data. If this flag is not sent, the current contents of the word processing field are completely erased before the new word processing data is filed. K LocK the entry or subentry before changing the word processing data.
WP_ROOT	Input	(Required) The root of the array that contains the word processing data to be filed.
MSG_ROOT	Both	(Optional) Root into which errors are put. If this parameter is not passed, these arrays are put into nodes descendent from ^TMP.

$$KEYVAL()

The Key Validator extrinsic function verifies that
new values contained in the FDA do not produce an invalid key. All keys in
which any field in the FDA participates are checked. If the value for a field
in a key being checked is not present in the FDA, the value used to verify the
key is obtained from the previously filed data.

Format $$KEYVAL^DIE(FLAGS,FDA_ROOT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FLAGS	Both	(Optional) Flags to control processing. The possible values are: Q = Quit when the first problem in the FDA is encountered.
FDA_ROOT	Both	(Required) The root of the FDA that contains the data to be checked. The array can be a local or global one. See the Database Server Introduction for details of the structure of the FDA. The value of fields in the FDA must be the internal value. Do not pass external (e.g., unresolved pointer values, non-FileMan dates) in the FDA. No action is taken on fields in the referenced FDA if those fields do not participate in a Key defined in the KEY file.
MSG_ROOT	Both	(Optional) The root of an array into which error messages are returned. If this parameter is not included, errors are returned in the default array: ^TMP("DIERR",$J).
0/1	Output	The function returns a 1 if key integrity is not violated by any value in the FDA and a 0 if an invalid key was produced by any of the values.

VALS()

The Fields Validator procedure validates data for a
group of fields and converts valid data to internal VA FileMan format. It is
intended for use with a set of fields that comprise a logical record; fields
from more than one file can be validated by a single call. By default, the
integrity of any keys affected by the new values is checked.

The Fields Validator performs the same checks performed by VAL^DIE (see for
details).

Format VALS^DIE(FLAGS,FDA_EXT_ROOT,FDA_INT_ROOT,MSG_ROOT)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FLAGS	Input	(Optional) Flags to control processing. The possible values are: K - If the file has a Primary Key, this flag indicates that the Primary Key fields, not the .01 field, are to be used for lookup in the Finding and LAYGO/Finding nodes of the FDA. Without this flag, VALS^DIE assumes that you want to file the fields in the Primary Key, rather than use them for lookup, and performs the uniqueness check. This flag is equivalent to the "K" flag in the Updater (UPDATE^DIE). R - Records identified by IENSs in the FDA_EXT are verified to exist and to be editable. (Same as R flag for VAL^DIE.) U - Don't perform key validation. Without this flag, the data in the FDA is checked to ensure that no duplicate keys are created and that key field values are not deleted.
FDA_EXT_ROOT	Input	(Required) The root of a standard FDA. This array should contain the external values that you want to validate. This is the input array. See the Database Server Introduction for details of the structure of the FDA.
FDA_INT_ROOT	Both	(Required) The root of a standard FDA. This FDA is the output array, and upon return is set equal to the internal values of each validated field. If a field fails validation, its value is set to an up-arrow (^). (NOTE: If a field is valid, the corresponding node in the output array is set to the internal value, not an up-arrow (^), even if that field violates key integrity.) See the Database Server Introduction for details of the structure of the FDA
MSG_ROOT	Both	(Optional) The root of an array (local or global) into which error messages are returned. If this parameter is not included, error messages are returned in the default array: ^TMP("DIERR",$J).