VA FileMan V. 22.2 Programmer Manual Banner

 

Contents: Main Chapter See Also: Getting Started Manual Advanced User Manual

Create SORT Templates Silently API

BUILDNEW^DIBTED(): SORT Template Builder

Reference Type Category ICR #
Supported Create Sort Templates Silently TBD
Description

The BUILDNEW^DIBTED API silently creates an entry in the SORT TEMPLATE (#.401) file. SORT templates can be used for any purpose; however, you primarily use them with the LIST^DIC(): Lister API. The SORT templates created “on-the-fly” by the BUILDNEW^DIBTED API can be used in the LIST^DIC(): Lister API in conjunction with the X flag to control the output of that procedure.

Format
    BUILDNEW^DIBTED(.RETURN,FILE,SORT_CRITERIA,TEMPLATE_NAME)
Input Parameters
.return

(Required) This parameter is passed by reference. It contains the result of the API call.

Possible returned values are:

  • -1—Failure; no returned error message.
  • -1^error—Failure; with a returned error message.
  • Template_IEN^Template_Name^1—Success; with a new entry in the SORT TEMPLATE (#.401) file at Template_IEN and with the name indicated. The name should be the SORT template name passed into the API in the template_name parameter.
  • Template_IEN^Template_Name—Success; with an existing entry in the SORT TEMPLATE (#.401) file being overwritten with the new sort criteria. The SORT template name passed into the API already existed in the SORT TEMPLATE (#.401) file.
file (Required) Number of the file on which the SORT template is created.
sort_criteria (Required) Name of the array containing the sort criteria. The array should be subscripted with positive numbers. The contents of the array must match exactly the format expected by the SORT template engine. The best way for the developer to create the array is to make a SORT template using the Print File Entries [DIPRINT] option and copy the array produced. The properly formatted elements of the array can be found using the Template Edit [DITEMP] option on the second page of the screen mode form.
template_name (Required) Name you want to give the SORT template. Do not include brackets. If a SORT template with that name already exists, it is overwritten with the new sort criteria.
Output

The primary output is the creation of a new SORT template. A description of the result of the call is returned in the .return parameter as described in the “Input Parameters” section.

Example

The example below illustrates the creation of a SORT template using BUILDNEW^DIBTED API. Note the specific spacing in the nodes of SORT().

The RET variable returns the IEN of the entry in the SORT TEMPLATE (#.401) file (i.e., 922) as well as the name of the new SORT template, which is the same name passed into the API.

The “1” in the third piece of RET indicates that a new template was created. The LIST^DIC(): Lister call makes use of the newly created template.

NOTE: Brackets are added to the Template Name for the LIST^DIC(): Lister call.

>S SORT(1)="SORT BY: -COUNT(COUNTY)"
>S SORT(2)="FROM:"
>S SORT(3)="TO:"
>S SORT(4)="   WITHIN COUNT(COUNTY), SORT BY: $E(NAME,1,3)=""NEW"""
>S FILE=5
>N RET
>S TNAME="ZZD STATE SORT 1"
>D BUILDNEW^DIBTED(.RET,FILE,$NA(SORT),TNAME)
>W RET
922^ZZD STATE SORT 1^1
>D LIST^DIC(FILE,,".01;COUNT(COUNTY)","X",,,,"[ZZD STATE SORT 1]")

 

Reviewed/Updated: May 2026