VA FileMan Programmer Manual: EXTRACT^DIAXU

Contents:

Main

Extract Tool API

EXTRACT^DIAXU: Extract Data

EXTRACT^DIAXU is a new entry point. It is the preferred entry point for extracting data records. The principal features introduced with this entry point for extracting data are:

More than one record can be extracted in a call.
Subrecords can be extracted as individual transactions. Previously, an entire record including all subrecords had to be extracted as a single entity.
DBS-style error reporting is used.

Like EN^DIAXU, this entry point extracts data from the fields specified in the EXTRACT template and places that data in an entry in a destination file. You can optionally delete the source entry after the extract process is completed.

Format

D EXTRACT^DIAXU(FILE,SOURCE,EXTRACT_TEMPLATE,FLAGS,.SCREENS,
  .FILING_LEVEL,TARGET_ROOT,MSG_ROOT)

Input

FILE	(Required) File number of source file.
SOURCE	(Required) Can be 1 of 2 formats: IEN: The record number of a single record, at the top level of the file, to extract. SEARCH template name: The name of a SEARCH template, in brackets, that contains SEARCH results (a list of record numbers). For example, S SOURCE="[TEMPLATE_NAME]"
EXTRACT_TEMPLATE	(Required) The name of the EXTRACT template, in brackets, containing what fields to move.
FLAGS	(Optional) A string of characters to modify the behavior of the Extract tool. Permissible characters in the string are:
	D	Tells the extract tool to Delete source records if they were moved successfully. Note that deletion is only done for entire (top-level) records. Subrecords are not individually deleted, even if they are individually extracted. NOTE: If the SOURCE parameter is set to a SEARCH template, and you include a D in the FLAGS parameter, the record numbers of any successfully extracted records are removed from the list of record numbers in the SEARCH template. But if an error is encountered, the source record is not deleted and the record number is not removed from the list of record numbers in the SEARCH template.
.SCREENS	(Optional) Local array containing screen(s) to apply to subrecords at various subrecord levels. The screens determine whether to move individual subrecords at a given level or not. The screens can be any valid M code that sets $TEST to 1 if the subrecord at a given level should be moved, or 0 if not. Set up nodes in this array subscripted by subfile# for each subrecord level you want to screen. For a list of the variables you can reference and change in the screen, please refer to the SCREEN parameter description in the LIST^DIC DBS call. Example: S MYARRAY(999.01)="I $P(^(0),U,2)=""Y"""
.FILING_LEVEL	(Optional) Local array you can use to tell the Extract tool to file subrecords as individual transactions, at one or more subfile levels. The default filing mode is to file an entire record - including all subrecords - as a single transaction. You should consider using the FILING_LEVEL feature when extracting records with many subrecords at a given subfile level. This lets you restrict the scope of an extract transaction (every part of the transaction must succeed or the entire transaction fails) to individual subrecords rather than to a record and all of its subrecords. For example, suppose the records you are extracting have one multiple field in particular in which there may be a thousand or more subrecords for every record. The subfile level of this multiple is a very good candidate to be filed individually: Without filing individually, failure to successfully extract any one of a record's thousand subrecords will abort the extract for the top level record and all of its subrecords (no changes will be filed). With filing individually, if any data in the subrecord causes an error, the subrecord will not be extracted, but the extract for the top level record and its other subrecords will continue. Another drawback of filing a record and a large number of subrecords as a single transaction is that a very large FDA array can be created; this can be resource intensive and could exhaust scratch storage space in ^TEMP. To file subrecords at any given subfile level individually, set up an array with a node subscripted by subfile# and pass the array by reference as this parameter. You can set more than one subfile level to file individually, by passing one node for each subfile level in the array. Example: S F_ARRAY(999.01)=""
TARGET_ROOT	(Optional) Array that should receive the results generated during the extract tool process. This must be a closed array reference and can be either local or global. If you specify your own array for results, make sure it's empty before calling EXTRACT^DIAXU. If you do not pass this parameter, the results are returned in ^TMP("DIAXU",$J).
MSG_ROOT	(Optional) Array that should receive error messages generated during the extract tool process. This must be a closed array reference and can be either local or global. If you specify your own array for error messages, be sure it's empty before calling EXTRACT^DIAXU. If you do not pass this parameter, error messages are returned in ^TMP("DIERR",$J).

Output

DIERR

This variable is returned if an error condition occurred. It contains two ^-pieces of information:

Number of errors generated during the call
Total number of lines of the error messages

Associated error messages are stored, DBS-style, in MSG_ROOT.

TARGET_ROOT

One "RESULT" node is returned for each record extracted (or attempted to be extracted).

The format of the "RESULT" node(s) for a successful extract is:

TARGET_ROOT parameter passed
TARGET_ROOT("RESULT", source_file, source_ien) = destination_file_ien
No TARGET_ROOT parameter passed
^TMP("DIAXU", $J, "RESULT", source_file, source_ien) = destination_file_ien

The format of the "RESULT" node(s) for an unsuccessful extract is:

TARGET_ROOT parameter passed
TARGET_ROOT("RESULT", "ERR", source_file, source_ien) = error_list
No TARGET_ROOT parameter passed
^TMP("DIAXU", $J, "RESULT", "ERR", source_file, source_ien) = error_list

The error list for an unsuccessful extract contains the error numbers, each followed by a semicolon. For example, if a "RESULT" node is:

TARGET_ROOT("RESULT", "ERR", 16151, 6)=1;2;

This means that errors 1 and 2 are caused by the extract of record 6. Errors one and two are returned in the MSG_ROOT array.

If the FILING_LEVEL parameter is being used such that subrecords are being filed individually at some subfile levels, results (successful or unsuccessful) are returned for each individual subrecord extracted, in the same format as above, except that:

"source_file" will be the subfile number
"source_ien" will be the IENS string for the subfile entry
"destination_file_ien" will be the IENS string for the destination subfile entry

If one or more subrecords extracted unsuccessfully using the FILING_LEVEL parameter, a single error (1300) is returned for the top-level record in a "RESULT","ERR" node, but this does not abort the extract. So in this case a top-level extracted record can have both a "RESULT" node (indicating success at the top level and the destination file ien) and a "RESULT","ERR" node (indicating error[s] during subfile filing).

If the extract fails for any subrecord at some subfile level not filed individually via the FILING_LEVEL parameter, a "RESULT","ERR" node is returned for the top-level record, and the extract for the top-level record aborts.

MSG_ROOT

Error messages are returned in MSG_ROOT("DIERR") (if the MSG_ROOT input parameter is passed) or ^TMP("DIERR",$J) (if no array is specified). Errors are returned in DBS-style format.

For more information on the format of DBS-style error arrays, see the "DIERR" section of "Contents of Arrays" in the "How to Use the Database Server" section.

Examples

Example 1

In this example, EXTRACT^DIAXU is called with a SEARCH template containing a list of three record numbers to extract. Two records (#7 and #32) are moved successfully and one record (#34) fails to be moved. As a result of the error, the variable DIERR would be returned (set to "1^1"). The call might look like:

  D EXTRACT^DIAXU(16151,"[EXTRACT SEARCH]","[EXTRACT TEMPLATE]")

The results messages would be returned as follows:

^TMP("DIAXU",627068728,"RESULT",16151,7) = 1
^TMP("DIAXU",627068728,"RESULT",16151,32) = 13
^TMP("DIAXU",627068728,"RESULT","ERR",16151,34) = 1;

The error messages would be returned as follows:

^TMP("DIERR",627068728,1) = 701
^TMP("DIERR",627068728,1,"PARAM",0) = 3
^TMP("DIERR",627068728,1,"PARAM",3) = NEWONE
^TMP("DIERR",627068728,1,"PARAM","FIELD") = .01
^TMP("DIERR",627068728,1,"PARAM","FILE") = 16299
^TMP("DIERR",627068728,1,"TEXT",1) = The value 'NEWONE' for
   field NAME in file FTEXT EXTRACT is not valid.
^TMP("DIERR",627068728,"E",701,1) =

Example 2

Suppose that the call to EXTRACT^DIAXU is made using the FILING_LEVEL array. This means that subrecords at some subfile levels are extracted individually. Let's suppose only one record is being extracted (ien #5), and two subrecords are extracted individually with the FILING_LEVEL array. Subrecord #1 extracts successfully, and subrecord #2 fails. The results and error messages would be returned as follows:

^TMP("DIAXU",541074770,"RESULT",662001,5) = 75                 (record #5, success)
^TMP("DIAXU",541074770,"RESULT",662001.1,"1,5,") = 1,75,       (subrecord #1, success)
^TMP("DIAXU",541074770,"RESULT","ERR",662001,5) = 2            (record #5, error 2
from subrecord failure)
^TMP("DIAXU",541074770,"RESULT","ERR",662001.1,"2,5,") = 1;    (subrecord
#2, error 1)
^TMP("DIERR",541074770,1) = 330                                (error 1)
^TMP("DIERR",541074770,1,"PARAM",0) = 2                         
^TMP("DIERR",541074770,1,"PARAM",1) = 99
^TMP("DIERR",541074770,1,"PARAM",2) = pointer to File #200
^TMP("DIERR",541074770,1,"TEXT",1) = The value '99' is not 
  a valid pointer to File #200.
^TMP("DIERR",541074770,2) = 1300                                (error 2)
^TMP("DIERR",541074770,2,"PARAM",0) = 1
^TMP("DIERR",541074770,2,"PARAM","IEN") = 5 
^TMP("DIERR",541074770,2,"TEXT",1) = "The entry encountered an err
  or during subfile filing.
^TMP("DIERR",541074770,"E",330,1) =
^TMP("DIERR",541074770,"E",1300,2) =

Error Codes Returned

This entry point calls $$FIND1^DIC, LIST^DIC, UPDATE^DIE, $$GET1^DIQ, and GETS^DIQ; any errors returned by these entry points can also be returned by EXTRACT^DIAXU.

In addition, the following errors may be returned:

202	An input parameter is missing or not valid.
601	The entry does not exist.
1300	The entry encountered an error during subfile filing.

Reviewed/Updated: March 10, 2007