Classic VA FileMan API

EN1^DIP: Input Variables

Input Variables

L

(Required) A required variable which should be set to zero or some string whose numeric evaluation is zero, e.g., "LIST DRUGS". If set to a text string, the string is used to replace the word "SORT" in the "SORT BY:" prompts, when FileMan asks the user for sort values:

    LIST DRUGS BY: NAME//

DIC

(Required) The open global root of the file in the usual format, e.g., "^DIZ(16540," or the file number.

FLDS

(Optional) The various fields to be printed. If this parameter is not sent, the user will be prompted for fields to print. FLDS can contain the following:

• The numbers or names of the fields to be printed, separated by commas. These fields are printed in the order that they are listed. Print qualifiers which determine column width, caption contents, and many other features of the output may be included exactly as they are when answering the "PRINT FIELD:" prompt. (See the "Print" chapter in the "VA FileMan Getting Started Manual" for details on print qualifiers.) For example:

      FLDS=".01,.03,1;C20"
  

  If there are more fields than can fit on one string, FLDS can be subscripted (FLDS(1), FLDS(2), and so forth), but FLDS as a single-valued variable must exist.

  
  
  
• The name of a PRINT template preceded by an open bracket ([) and followed by a close bracket (]). For example:

      FLDS="[DEMO]"

BY

(Optional) The fields by which the data is to be sorted. If BY is undefined, the user is prompted for the sort conditions. You can sort by up to seven fields; that is, you can have up to a 7-level sort.

You can set BY to:

• The numbers or names of the fields separated by commas. Sort qualifiers which determine aspects of the sort and of the printout may be included exactly as they are when answering the "SORT FIELD:" prompt. For example:

      BY=".01;C1,1"
  

  If one of the comma pieces of the BY variable is the @-sign character, the user will be asked for that SORT BY response. So if you want to sort by DIAGNOSIS but allow the user to order the sort within DIAGNOSIS, set BY="DIAGNOSIS,@".

  
  
  
• The name of a SORT template preceded by an open bracket ([) and followed by a close bracket (]). For example:

      BY="[DEMOSORT]"

NOTE: You cannot use the name of a SORT template in the BY variable if the BY(0) input variable has been set. If you want to create such complex sorts, you can include the BY(0) information within the SORT template. See the section Storing BY(0) Specifications in SORT Templates, within the Details and Features section: Controlling Sorts with BY(0).  

• The name of a SEARCH template, preceded by an open bracket ([) and followed by a close bracket (]). The SEARCH template must have results stored in it. Only those records in the SEARCH template will print, and they will print in IEN order. For example:

      BY="[DEMOSEARCH]"

NOTE: If more than one field is included in the BY variable, separate the fields with commas. The same comma-pieces will identify the field in the FR and TO variables. If, for example, you wanted a sorted report of entries with DOBs in 1960 and with ZIP CODEs in the 90000s, you could define the variables by writing:

    BY="DOB,ZIP CODE"
    FR="01/01/60,90000"
    TO="12/31/60,99999"

Since the delimiter of BY is a comma, the value placed in the variable should not contain a comma. Therefore, if your field name contains a comma, use the field number in the BY variable instead of its name. For the same reason, if sort from or to values contain commas, the alternate FR(n) and TO(n) input arrays described below should be used instead of the FR and TO input variables.

FR

(Optional) The START WITH: values of the SORT BY fields. If FR is undefined, the user will be asked the START WITH: question for each SORT BY field. If FR is defined, it consists of one or more comma pieces, where the piece position corresponds to the order of the sort field in the BY variable. Each comma piece can be:

• The value from which the selection of entries will begin.
  
  
• Null. If a comma piece of FR is null, then the sort will start from the very beginning of the file for that field.
  
  
• ?. The question mark as one of the comma pieces causes the "START WITH:" prompt to be presented to the user for the corresponding SORT BY field.
  
  
• @. The at-sign indicates that the sort should begin with null values, that is, with entries that have no data on file. If the corresponding piece of the TO variable or array also is set to @, then only entries with null values for this sort field will be selected during the sort. If TO does not contain @, then after the null values, the sort will start at the first non-null value and will go to the value indicated by TO.

NOTE: If BY contains the name of a SORT template and if the developer answered NO to the question SHOULD TEMPLATE USER BE ASKED 'FROM'-'TO' RANGE... for a field at the time the template was defined, then the information in the FR and TO variables is ignored for that field. Instead, the from/to ranges stored in the sort template are used.

If you customize sorts using BY(0), see special note on FR in that section.

FR(n)

(Optional) An alternate way to provide the START WITH: values of the SORT BY fields. If FR is defined, it will override this array. The subscript n corresponds to the comma piece in the BY variable (i.e., the sort by field number). This alternate way of inputting the from and to values allows the use of values containing commas, such as PATIENT NAMEs. Each nth entry in the array corresponds to, and can have the same value as, the nth comma piece in the FR variable. The only difference is that any nth entry, FR(n), can be undefined, causing the START WITH: question to be asked for the nth SORT FIELD.

For example, if you were using the unsubscripted TO and FR variables to do a sort on two fields, you might do as follows:

    S FR="A,01/01/95",TO="Zz,01/31/95"

To set up the same sort using the subscripted forms of TO and FR, you would set them up as follows:

    S FR(1)="A",FR(2)="01/01/95"
    S TO(1)="Zz",TO(2)="01/31/95"

NOTE: If you customize sorts using BY(0), see special note on FR in that section.

TO

(Optional) The GO TO: values of the SORT BY fields. Its characteristics correspond to the FR variable. If undefined, the user will be asked the GO TO: questions for each SORT BY field. If TO is defined, it consists of one or more comma pieces. Each comma piece can be:

• The value at which the selection of entries will end.
  
  
• Null. If TO is null, then the sort will go from FR to the end of the file.
  
  
• ?. The question mark as one of the comma pieces causes the "GO TO:" prompt to be presented to the user for the corresponding SORT BY field.
  
  
• @. The at-sign indicates that the sort should include null values, that is, entries that have no data on file. If the corresponding piece of the FR variable or array also is set to @, then only entries with null values for this sort field will be selected during the sort. If FR does not contain @, then after the null values, the sort will start at the FR value and include all other non-null values to the end of the file.

NOTE: If BY contains the name of a SORT template and if the developer answered NO to the question SHOULD TEMPLATE USER BE ASKED 'FROM'-'TO' RANGE... for a field at the time the template was defined, then the information in the FR and TO variables is ignored for that field. Instead, the from/to ranges stored in the SORT template are used.

TO(n)

(Optional) An alternate way to provide the GO TO: values of the SORT BY fields. If TO is defined, it will override this array. The subscript "n" corresponds to the comma piece in the BY variable. This alternate way of inputting the from and to values allows the use of values containing commas, such as PATIENT NAMEs. Each nth entry in the array corresponds to, and can have the same value as, the nth comma piece in the TO variable. The only difference is that any nth entry, TO(n), can be undefined, causing the GO TO: question to be asked for the nth SORT BY field.

If you customize sorts using BY(0), see special note on TO(n) in that section.

DHD

(Optional) The header desired for the output. DHD can be one of the following:

• @ if header is not desired.
  
  
• @@ if header and formfeed are not desired.
  
  
• A literal which will be printed, as is, in the upper left hand corner of the printout. The date, page and field headings will be in their normal places.
  
  
• A line of M code which must begin with a write statement, e.g., DHD="W ?0 D ^ZZHDR".
  
  
• A PRINT template name preceded by an open bracket ([) and followed by a close bracket (]). In this case, the template replaces all parts of the header that VA FileMan normally generates.
  
  
• Two PRINT templates separated by a minus sign. The first will be used as the header and the second will be used as the trailer. For example:

      DHD="[HEADER]-[TRAILER]"
  

DIASKHD

(Optional) If this variable is defined, the user will be prompted to enter a header. Set it equal to null (""). If this variable is undefined, the user will not have the opportunity to change the header on the print.

DIPCRIT

(Optional) If this variable is set to 1, the SORT criteria will print in the header of the first page of the report.

PG

(Optional) Starting page number. If variable is undefined, page 1 will be assumed.

DHIT

(Optional) A string of M code which will be executed for every entry after all the fields specified in FLDS have been printed.

DIOEND

(Optional) A string of M code which is executed after the printout has finished but before returning to the calling program.

DIOBEG

(Optional) A string of M code which is executed before the printout starts.

DCOPIES

(Optional) If %ZIS chooses an SDP device, and if multiple copies are desired, you can call for them by setting DCOPIES equal to the number (greater than one) of copies desired. For more information about SDP devices, see the "Kernel Systems Manual."

IOP

(Optional) EN1^DIP calls the ^%ZIS entry point to determine which device output should go to. This requires user interaction unless you preanswer the DEVICE prompt. You can do this by setting IOP equal to the name of the device (as it is stored in the DEVICE file) to which the output should be directed. You can also set IOP in any of the additional formats recognized by ^%ZIS to specify the output device (see the "Kernel Systems Manual" for more information on ^%ZIS and IOP).

If you need to call ^%ZIS beforehand to obtain the name of the device in question from the user, call it with the %ZIS N flag set so that ^%ZIS doesn't actually open the device. The name of the device is then returned in the ION output variable. EN1^DIP will open and close the device you specify in IOP on its own; don't open it yourself beforehand.

In addition to setting IOP equal to a device for printing, you can use this variable (in conjunction with the DQTIME variable described immediately below) to queue the printing of a report. This functionality is only available if Kernel is present. Also, you must set up all of the input variables for EN1^DIP so that the user is not asked any questions. For example, the BY, FR, and TO variables must be defined. To establish queuing, IOP should equal Q;output device. For example:

    S IOP="Q;MY PRINTER - NLQ"

DQTIME

(Optional) If output is queued, this variable contains the time for printing. You can set it equal to any value that %DT recognizes. For example:

    S DQTIME="NOW"

OR:

    S DQTIME="T@11PM"

DIS(0)

(Optional) You can screen out certain entries so that they do not appear on the output by setting the optional array DIS. The first subscript in this array can be 0 (zero). This variable (as well as all the others) contains an executable line of M code which includes an IF-statement. If the execution of the IF sets $T to 1, then the entry will print. The internal number of the entry being processed is in D0.

DIS(n)

(Optional) You can set other elements in the DIS array: DIS(1), DIS(2), DIS(3), etc. The subscripts must be consecutive integers starting at 1. Again, they must contain M code that sets $T. If many elements are defined, then DIS(0) (if it exists) must be true and any one of the other elements in the array must be true for the entry to print.

DISUPNO

(Optional) If this variable is set to 1 and if no records are found within the sort ranges specified for the print, the report header and the "No Records to Print" message is not printed.

DISTOP

(Optional) If Kernel is present, by default, prints queued through the EN1^DIP call can be stopped by the user with a TaskMan option. However, if this variable is set to 0, users will not be able to stop their queued prints.

DISTOP can also be set equal to M code that will be executed once near the start of a queued print. If the code sets $T to true, the user will be able to stop the job; if $T is false, the user will not be able to. For example:

    S DISTOP="I DUZ(0)=""@"""

would mean that only those with programmer access could stop the print.

DISTOP("C")

(Optional) If the user stops a queued print job by using TaskMan's option, code in this optional variable will be executed before the output device is closed. It might, for example, do clean up necessary because the job did not run to completion.

Reviewed/Updated: March 10, 2007