Print Page as PDF
Data Base Server API: Editing Utilities ICR (2053)

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
ID DIE
COMPONENT/ENTRY POINT
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).

MAIL MESSAGE 30004955
Generated from SEP 10, 2019@ IA Listing Descriptions