Data Base Server API: DD Modification Utilities    ICR (2916)

(Required) File or subfile number.

(Required) Field number.

(Required) Cross-reference number. Traditional
cross-references are defined in the data dictionary under:

^DD(file#,field#,1,cross reference number)

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

K      For Regular, KWIC, Mnemonic, and Soundex-type cross-references, delete
the data in the index. For MUMPS and Trigger-type cross-references, execute
the kill logic of the cross-reference for all entries in the file.  For
Bulletin-type cross-references, the "K" flag is ignored; the kill logic for
Bulletin-type cross-references is never executed by this procedure.

W      Write messages to the current device as the index is deleted and
cross-references and input templates are recompiled.

(Optional) Input: The name of the array that should
receive information about input templates and cross-references that may have
been recompiled and a flag to indicate that the deletion was audited in the DD
Audit file (#.6).  This must be a closed root, either local or global.

Output: If the field on which the deleted cross-reference was defined is used
in any compiled input templates, those input templates are recompiled.
Information about the recompiled input templates is stored descendant from
OUTPUT_ROOT("DIEZ"):

OUTPUT_ROOT("DIEZ",input template #) =
input template name ^ file # ^ compiled routine name

If cross-references for the file are compiled, they are recompiled, and the
compiled routine name is stored in OUTPUT_ROOT("DIKZ"):

OUTPUT_ROOT("DIKZ") = compiled routine name

If the data dictionary for the file is audited, an entry is made in the DD
Audit file (#.6) and OUTPUT_ROOT("DDAUD") is set to 1:

OUTPUT_ROOT("DDAUD") = 1

(Optional) The name of the array that should receive
any error messages.  This must be a closed root, either local or global. If
not passed, errors are returned descendent from ^TMP("DIERR",$J).

(Required) File or subfile number. For whole-file
indexes, this is the number of the file at the upper level where the data in
the index resides.

(Required) Index name.

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

K      For Regular indexes, delete the data in the index. For MUMPS indexes,
execute the kill logic for all entries in the file.

W      Write messages to the current device as the index is deleted and
cross-references and input templates are recompiled.

(Optional) Input: The name of the array that should
receive information about input templates and cross-references that may have
been recompiled. This must be a closed root, either local or global.

Output: If a field used in the index is used in any compiled input templates,
those input templates are recompiled. Information about the recompiled input
templates is stored descendant from OUTPUT_ROOT("DIEZ"):

OUTPUT_ROOT("DIEZ",input template #) =
input template name ^ file # ^ compiled routine name

If cross-references for the file are compiled, they are recompiled, and the
compiled routine name is stored in OUTPUT_ROOT("DIKZ"):

OUTPUT_ROOT("DIKZ") = compiled routine name

(Optional) The name of the array that should receive
any error messages.  This must be a closed root, either local or global. If
not passed, errors are returned descendent from ^TMP("DIERR",$J).

(Required) File number. (Cannot be less than 2.)

(Required) Array of new security access codes:

SECURITY_CODES("AUDIT") = Audit Access SECURITY_CODES("DD") = Data Dictionary
Access SECURITY_CODES("DEL") = Delete Access SECURITY_CODES("LAYGO") = LAYGO
Access SECURITY_CODES("RD") = Read Access SECURITY_CODES("WR") = Write Access

(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).

(Optional) Local variable that receives the IEN of
the entry that was created in the INDEX file (#.11), if the call is
successful, and the Name of the new index. If the cross-reference could not be
created, a value of null ("") is returned.

RESULT = IEN in Index file ^ cross-reference name or
RESULT = "" if cross-reference could not be created

(Required) This input array contains information
about the new-style cross-reference to be created. The elements in this array
are as follows:

XREF("FILE") = The number of the file or subfile on which the index physically
resides. For whole-file indexes, this should be the file number of the upper
level file, not the subfile that contains the fields in the index. For MUMPS
cross-references that don't set an index, XREF("FILE") should be the file that
contains the fields in the cross-reference.  (Required)

XREF("TYPE") = "R" or "REGULAR" for regular indexes; or "MU" or "MUMPS" for
MUMPS-type cross-references. (Required)

XREF("NAME") = The name of the cross-reference. If XREF("NAME") is not passed,
CREIXN^DDMOD gets the next available name based on the XREF("FILE") and
XREF("USE"). In most cases, however, you should explicitly give your new
cross-reference a name. (Required if XREF("USE") is not passed.)

XREF("ROOT FILE") = For whole-file indexes, the number of the file or subfile
that contains the fields in the cross-reference. This is the subfile number,
not the upper level file number where the index physically resides. XREF("ROOT
FILE") should only be set for whole-file indexes.  (Required for whole-file
indexes.)

XREF("SHORT DESCR") = Short description of the cross-reference (Required)

XREF("DESCR",1) = Line 1 of the cross-reference description.  XREF("DESCR",n)
= Line n of the cross-reference description. (Optional)

XREF("USE") = "LS" or "LOOKUP & SORTING" for indexes used for both lookup and
sorting; "S" or "SORTING ONLY" for indexes used for sorting only; or "A" or
"ACTION" for MUMPS cross-reference that do not set an index.

"LS" ("LOOKUP & SORTING") - The cross-reference sets an index and the
index name must start with "B" or a letter that alphabetically follows "B".
Calls to Classic FileMan lookup (^DIC) or the Finder (FIND^DIC or $$FIND1^DIC)
where the index is not specified will include this index in the search. The
index will be available for use by the FileMan Sort and Print (EN1^DIP).

"S" ("SORTING ONLY") - The cross-references sets an index, and the index
name must start with "A". Calls to Classic FileMan lookup (^DIC) or the Finder
(FIND^DIC or $$FIND1^DIC) will not use this index unless it is specified in
the input parameters to those calls. The index will be available for use by
the FileMan Sort and Print (EN1^DIP).

"A" ("ACTION") -This is used for MUMPS cross-references that perform some
action(s) other than building an index. The cross-reference name must start
with "A".

If XREF("USE") is not passed, CREIXN^DDMOD assumes a value based on the
cross-reference name and type. If the name starts with "A", XREF("USE") is
assumed to be "S" (Sorting Only) for Regular indexes, and "A" (Action) for
MUMPS cross-references. If the name doesn't start with an "A", XREF("USE") is
assumed to be "LS" (Lookup & Sorting). Note that for clarity, however, it is
recommended that you explicitly set XREF("USE").

(Required if XREF("NAME") is not passed.)

XREF("EXECUTION") = "F" or "FIELD" for field-level execution; or "R" or
"RECORD" for record-level execution.

This indicates whether the cross-reference logic should be executed after
a field in the cross-reference changes, or only after all fields in a record
are updated in an editing session. The logic for most simple (single-field)
cross-references should be executed immediately after the field changes, and
so should have an Execution of "F". The logic for most compound (multi-field)
cross-references should be executed only once after a transaction on the
entire record is complete, and so should have an Execution of "R".

(Optional) (Defaults to "F" for simple cross-references, and "R" for
compound cross-references.)

XREF("ACTIVITY") = One or both of the following codes:

I = Installing an entry at a site
R = Re-cross-referencing this index

If Activity contains an "I", FileMan fires the cross-references during a
KIDS installation. If Activity contains an "R", FileMan fires the
cross-reference during a re-cross-referencing operation.

Note that FileMan automatically fires cross-references during an edit,
regardless of Activity, although you can control whether a cross-reference is
fired by entering set and kill conditions.

Also, if you explicitly select a cross-reference in an EN^DIK, EN1^DIK,
or ENALL^DIK call, or in the UTILITY FUNCTIONS/RE-INDEX FILE option on the VA
FileMan menu, that cross-reference will be fired whether or not its Activity
contains an "R".

(Optional) (Defaults to "IR")

XREF("SET CONDITION") = MUMPS code that sets the variable X. The set logic of
the cross-reference is executed only if the set condition, if present, sets X
to Boolean true, according the M rules for Boolean interpretation.

The MUMPS code can assume the DA array describes the record to be
cross-referenced, and that the X(order#) array contains values after the
transform for storage is applied, but before the truncation to the maximum
length. The variable X also equals X(order#) of the lowest order number.

When fields that make up a cross-reference are edited and the kill and
set conditions are executed, the X1(order#) array contains the old field
values, and the X2(order#) array contains the new field values. If a record is
being added, and there is an X1(order#) array element that corresponds to the
.01 field, it is set to null. When a record is deleted, all X2(order#) array
elements are null.

(Optional)

XREF("KILL CONDITION") = MUMPS code, that sets the variable X. The kill logic
of the cross-reference is executed only if the kill condition, if present,
sets X to Boolean true, according the M rules for Boolean interpretation.

See XREF("SET CONDITION") above for a description of the DA, X, X1, and
X2 arrays that can be used in the MUMPS code.

(Optional)

For MUMPS cross-references, you can also set the following nodes in the XREF
array. (For Regular Indexes, the set and kill logic is determined
automatically for you, and so these nodes, if passed in, are ignored.) The
code can also make use of the DA, X, X1, and X2 arrays as described in
XREF("SET CONDITION") above.

XREF("SET") = M code that FileMan should be executed when the values of
fields that make up the cross-reference are set or changed. (Optional)
(Defaults to "Q")

XREF("KILL") = M code that FileMan should be executed when the values of
fields that make up the cross-reference are changed or deleted.

(Optional) (Defaults to "Q")

XREF("WHOLE KILL") = M code that can be executed to remove an entire
index for all records in a file. When an entire fire is reindexed, FileMan
executes this code rather than looping through all the entries in the file and
executing the kill logic once for each entry. (Optional)

Each value in the cross-reference is described in the XREF("VAL",order#)
portion of the XREF array. The order numbers must be positive integers
starting from 1, and determine the order in which FileMan evaluates the
cross-reference values to place in the X(order#) array during cross-reference
execution.

XREF("VAL",order#) = The field number (for field-type xref values); or M
code that sets X to the cross-reference value (for computed-type xref values).
For computed-type cross-reference values, the X(order#) array is available for
those cross-reference values with lower order numbers, and the DA array
describes the IEN of the current record. (Required)

XREF("VAL",order#,"SUBSCRIPT") = The subscript position number in the
index, if this cross-reference value is used as a subscript in the index.  The
first subscript to the right of the index name is subscript number 1.  All
subscripts must be consecutive integers starting from 1. (Optional)

XREF("VAL",order#,"LENGTH") = The maximum length of the cross-reference
value FileMan should use when storing the value as a subscript in the index.
(Optional).

XREF("VAL",order#,"COLLATION") = "F" for "forwards"; "B" for "backwards".
This indicates the direction FileMan's lookup utilities should $ORDER through
this subscript when entries are returned or displayed to the user. (Optional)
(Defaults to "F".)

XREF("VAL",order#,"LOOKUP PROMPT") = Text that becomes the prompt to the
user when this index is used for lookup, and a value is requested for this
subscript. (Optional)

For field-type cross-reference values only, the following nodes can also be
set:

XREF("VAL",order#,"XFORM FOR STORAGE") = M code that sets the variable X
to a new value. X is the only variable guaranteed to be defined and is equal
to the internal value of the field. The Transform for Storage can be used to
the transform the internal value of the field before it is stored as a
subscript in the index.

XREF("VAL",order#,"XFORM FOR LOOKUP") = M code that sets the variable X
to a new value. X is the only variable guaranteed to be defined and is equal
to the lookup value entered by the user. During lookup, if the lookup value is
not found in the index, FileMan executes the Transform for Lookup code to
transform the lookup value X and tries the lookup again.

XREF("VAL",order#,"XFORMFOR DISPLAY") = M code that sets the variableX to
a new value. X is the only variable guaranteed to be defined and isset equal
to the value of the subscript of in the index. During lookup, ifa match or
matches are ma de to the lookup value, the Transform for Display code is
executed before displaying the index value to the user.

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

k  - When CREIXN^DDMOD calls DELIXN^DDMOD to initially delete the old
cross-reference with the same name as the one it is creating, don't kill the
data in the old index if it is a Regular indexes, and don't execute the old
Kill logic if it is a MUMPS cross-references. Whether or not this flag is
passed, CREIXN^DDMOD deletes the old cross-reference definition, if it exists,
before bringing in the new definition.

S - For Regular indexes, set the data in the index. For MUMPS
cross-references, execute the Set logic for all entries in the file.

W - Write messages to the current device as the index is created and
cross-references and input templates are recompiled.

(Optional) The name of the array that should receive
any error messages. This must be a closed root, either local or global. If not
passed, errors are returned descendent from ^TMP("DIERR",$J).

(Optional) The name of the array that should receive
information about input templates and cross-references that may have been
recompiled. See Output below. This must be a closed root, either local or
global.