| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This procedure creates a new-style cross-reference definition in the INDEX file (#.11). Optionally, it builds the data in the index (for Regular cross-references) or executes the set logic (for MUMPS cross-references) for all entries in the file. Compiled input templates that contain one or more of the fields defined in the cross-reference are recompiled. If cross-references on the file are compiled, they are recompiled.
One use of CREIXN^DDMOD is in the pre-install or post-install routine of a KIDS (Kernel Installation and Distribution System) Build to create a new-style cross-reference at the installing site.
See the API DELIX^DDMOD for information on the call to delete a new-style cross-reference definition.
See ^DIKCBLD for information on a programmer mode utility that can be used to help create a routine that calls CREIXN^DDMOD.
CREIXN^DDMOD(.XREF,FLAGS,.RESULT,OUTPUT_ROOT,MSG_ROOT)
| .XREF | (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("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 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#,"XFORM FOR DISPLAY") = M code that sets the variable X to a new value. X is the only variable guaranteed to be defined and is set equal to the value of the subscript of in the index. During lookup, if a match or matches are made to the lookup value, the Transform for Display code is executed before displaying the index value to the user. |
|
| FLAGS | (Optional) Flags to control processing. The possible values are: | |
| 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. | |
| .RESULT |
(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. |
|
| OUTPUT_ROOT | (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. | |
| MSG_ROOT | (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). | |
| RESULT |
See .RESULT under "Input Parameters." RESULT = IEN in INDEX file ^ cross-reference name or RESULT = "" if cross-reference could not be created. |
| OUTPUT_ROOT | See OUTPUT ROOT under
"Input Parameters."
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
|
Example 1
In this example, a new-style compound "C" index is created on File #16000. It contains two field-type cross-reference values, Fields #1 and #2, both of which are used as subscripts in the index. The "S" flag indicates that the index should be built after its definition is created, and the "W" flag indicates that messages should be written to the current device as the index is created and built, and as templates and cross-reference are recompiled.
ZZTEST ;Test routine
EXAMP1 ;Create a Regular "C" compound index
S MYARRAY("FILE")=16000
S MYARRAY("NAME")="C"
S MYARRAY("USE")="LS"
S MYARRAY("TYPE")="R"
S MYARRAY("SHORT DESCR")="Regular compound index on fields 1
and 2."
S MYARRAY("DESCR",1)="This cross-reference contains as subscripts
the values of"
S MYARRAY("DESCR",2)="fields #1 and #2 in the file #16000."
S MYARRAY("VAL",1)=1
S MYARRAY("VAL",1,"SUBSCRIPT")=1
S MYARRAY("VAL",2)=2
S MYARRAY("VAL",2,"SUBSCRIPT")=2
D CREIXN^DDMOD(.MYARRAY,"SW",.MYRESULT,"MYOUT")
Q
>D EXAMP1^ZZTEST
Cross-reference definition created.
Building index ...
Compiling ZZTEST Input Template of File 16000...
'ZZCT' ROUTINE FILED.
'ZZCT1' ROUTINE FILED.
Compiling Cross-Reference(s) 16000 of File 16000.
...SORRY, HOLD ON...
'ZZCR1' ROUTINE FILED.
'ZZCR' ROUTINE FILED.
>ZW MYRESULT
MYRESULT=214^C
>ZW MYOUT
MYOUT("DIEZ",125)=ZZTEST^16000^ZZCT
MYOUT("DIKZ")=ZZCR
The MYRESULT output variable indicates that the "C" index
definition was created with the internal entry number of 214 in the INDEX
file.
The MYOUT output array indicates that one or both of the fields in the index
are also used in the compiled input template ZZTEST (#125), and that input
template was recompiled. Cross-references on File #16000 were also recompiled
into the ZZCR namespaced routines.
The following is a data dictionary listing of the index that was created:
C (#214) RECORD REGULAR IR LOOKUP & SORTING
Short Descr: Regular compound index on fields 1 and 2.
Description: This cross-reference contains as subscripts the values of
fields #1 and #2 in the file #16000.
Set Logic: S ^DIZ(16000,"C",X(1),X(2),DA)=""
Kill Logic: K ^DIZ(16000,"C",X(1),X(2),DA)
Whole Kill: K ^DIZ(16000,"C")
X(1): AFIELD (16000,1) (Subscr 1) (forwards)
X(2): BFIELD (16000,2) (Subscr 2) (forwards)
Example 2
In this example, a new-style "AC" index is created. It is a whole-file index based on fields in Subfile #16000.02, but stored one level up, at the Subfile #16000.01 level. (One level above #16000.01, is the top level of the file, which has file number 16000.) The "AC" index contains two field-type cross-reference values, Fields #.01 and #1, neither of which are used as subscripts in the index. The third cross-reference value is computed and is the only subscript in the index. This computed subscript consists of the first five characters of Field #.01, which is the first cross-reference value, concatenated with Field #1, the second cross-reference value.
The "S" flag in the CREIXN^DDMOD call indicates that the index should be built after its definition is created.
ZZTEST ;Test routine
EXAMP2 ;Create a whole-file "AC" index
S MYARRAY("FILE")=16000.01 ;the file on which the index resides
S MYARRAY("ROOT FILE")=16000.02 ;the file in which the fields in
the index are defined.
S MYARRAY("NAME")="AC"
S MYARRAY("USE")="SORTING ONLY"
S MYARRAY("TYPE")="REGULAR"
S MYARRAY("SHORT DESCR")="Whole-file regular 'AC' index."
S MYARRAY("DESCR",1)="This index stores at the 16000.01 file
level values from fields"
S MYARRAY("DESCR",2)="in subfile #16000.02."
;
;Cross-reference values 1 and 2 are field values
;defined so that cross-reference value 3 can
;reference their values via X(1) and X(2).
S MYARRAY("VAL",1)=.01
S MYARRAY("VAL",2)=1
;
;Cross-reference value 3 is a computed value
;based on cross-reference values 1 (field #.01)
;and 2 (field #1). It is used as a subscript in
;the index.
S MYARRAY("VAL",3)="S X=$E(X(1),1,5)_X(2)"
S MYARRAY("VAL",3,"SUBSCRIPT")=1
;
D CREIXN^DDMOD(.MYARRAY,"S",.MYRESULT)
Q
>D EXAMP2^ZZTEST
>ZW MYRESULT
MYRESULT=216^AC
The MYRESULT output variable indicates that the
"AC" index definition was created with the internal entry number of
216 in the INDEX file.
The resulting data dictionary listing of the new index definition is as
follows:
AC (#216) RECORD REGULAR IR SORTING ONLY WHOLE FILE
(#16000.01)
Short Descr: Whole-file regular 'AC' index.
Description: This index stores at the 16000.01 file level values from
fields in subfile #16000.02.
Set Logic: S ^DIZ(16000,DA(2),100,"AC",X(3),DA(1),DA)=""
Kill Logic: K ^DIZ(16000,DA(2),100,"AC",X(3),DA(1),DA)
Whole Kill: K ^DIZ(16000,DA(2),100,"AC")
X(1): MULTIPLE NAME (16000.02,.01)
X(2): CODE (16000.02,1)
X(3): Computed Code: S X=$E(X(1),1,5)_X(2)
(Subscr 1) (forwards)
Example 3
In this example, a new-style MUMPS cross-reference is created with the name "AD". It has one cross-reference value, Field #1 in File #16000. Whenever the value of Field #1 is deleted, the MUMPS cross-reference files today's date into the DATE DELETED field (#2). When the value of Field #1 changes from null to some non-null value, the MUMPS cross-reference deletes the contents of DATE DELETED. Since this cross-reference should not be executed during a reindexing operation or during a KIDS install, the Activity is set to null.
ZZTEST ;Test routine
EXAMP3 ;Create MUMPS cross-reference
S MYARRAY("FILE")=16012
S MYARRAY("NAME")="AD"
S MYARRAY("USE")="ACTION"
S MYARRAY("TYPE")="MUMPS"
S MYARRAY("ACTIVITY")=""
S MYARRAY("SHORT DESCR")="This MUMPS cross-reference updates
field #2 when field #1 is deleted."
S MYARRAY("DESCR",1)="The kill logic of this cross-reference
calls the Filer to stuff today's"
S MYARRAY("DESCR",2)="date into field #2 whenever the value of
field #1 is deleted."
S MYARRAY("DESCR",3)=""
S MYARRAY("DESCR",4)="The set logic calls the Filer to delete the
contents of field #2"
S MYARRAY("DESCR",5)="when a value is placed into field #1."
;
S MYARRAY("SET")="N ZZFDA,ZZMSG,DIERR
S ZZFDA(16012,DA_"","",2)=""""
D FILE^DIE("""",""ZZFDA"",""ZZMSG"")"
S MYARRAY("SET CONDITION")="S X=X1(1)="""""
S MYARRAY("KILL")="N ZZFDA,ZZMSG,DIERR
S ZZFDA(16012,DA_"","",2)=DT
D FILE^DIE("""",""ZZFDA"",""ZZMSG"")"
S MYARRAY("KILL CONDITION")="S X=X2(1)="""""
;
S MYARRAY("VAL",1)=1
D CREIXN^DDMOD(.MYARRAY,"W",.MYRESULT)
Q
>D EXAMP3^ZZTEST
Cross-reference definition created.
>ZW MYRESULT
MYRESULT=220^AD
The
MYRESULT output variable indicates that the "AD" cross-reference
definition was created with the internal entry number of 220 in the INDEX
file.
The
new cross-reference definition is:
AD (#220) FIELD MUMPS ACTION
Short Descr: This MUMPS cross-reference updates field #2 when field #1 is
deleted.
Description: The kill logic of this cross-reference calls the Filer to
stuff today's date into field #2 whenever the value of field
#1 is deleted.
The set logic calls the Filer to delete the contents of field
#2 when a value is placed into field #1.
Set Logic: N ZZFDA,ZZMSG,DIERR S ZZFDA(16012,DA_",",2)="" D FILE^DIE("",
"ZZFDA","ZZMSG")
Set Cond: S X=X1(1)=""
Kill Logic: N ZZFDA,ZZMSG,DIERR S ZZFDA(16012,DA_",",2)=DT D FILE^DIE("",
"ZZFDA","ZZMSG")
Kill Cond: S X=X2(1)=""
X(1): MYFIELD (16012,1)
Error Codes Returned
202 The specified parameter is missing or invalid.
401 The
file does not exist.
402 The global root is missing or invalid.
406 The file has not .01 field definition.
407 A word-processing field is not a file.
502 The field has a corrupted definition.
The New-Style Cross-Reference Creator may also return any error returned
by:
CHK^DIE
UPDATE^DIE
WP^DIE
Reviewed/Updated: March 10, 2007