Kernel Toolkit 7.3 APIs Banner
Office of Information and Technology (OIT) Banner
[skip navigation]

$$SCREEN^XTID(): Get Screening Condition (Term/Concept)

Reference Type: Supported, Category: Toolkit—VHA Unique ID (VUID), ICR#: 4631

Description

The $$SCREEN^XTID extrinsic function retrieves the screening condition for a given term/concept reference and specified date/time. It returns whether or not a given entry should be screened out of selection lists. This API should not be used to determine if the given entry is active/inactive, since the API takes into consideration where in the standardization process the facility is. It returns the following values:

NOTE: This extrinsic function was released with Kernel Toolkit Patch XT*7.3*108.

Format

  $$SCREEN^XTID(file[,field],iref[,datetime][,.cached])

Input Parameters

file:

(required) VistA file/subfile number where term/concept is defined.
field:

(optional) Field number in the file input parameter where term/concept is defined:

  • Not Defined—If not defined, this field defaults to the .01 field number, and it represents the terms defined in the file entered in the file input parameter.

  • Defined:

    • Entered as .01; it represents the terms defined in the file entered in the file input parameter.

    • Otherwise, the field number entered must be a SET OF CODES data type field in the file entered in the file input parameter.
iref:

(required) Internal reference for term/concept:

  • File Entries—This is an IENS. For example:

    iref = "5,"

  • SET OF CODES—This is the internal value of the code. For example, any of the following:

    iref = 3
    iref = "f"
    iref = "M"
datetime:

(optional) VA FileMan date/time against which screening is checked. It defaults to NOW.

NOTE: If the value of the datetime parameter contains a date and no time, no entries are returned for the first day.

.cached:

(optional) Flag to indicate caching. Used mainly when defining the screen parameter [e.g., DIC("S")] while searching large files. This improves the speed of the search.

NOTE: It must be KILLed before initiating each search query (e.g., before calling the VA FileMan ^DIC API).

Output

returns:

Returns the screening condition as follows:

  • 0—When term/concept is selectable (i.e., do not screen it out).

  • 1—When term/concept is not selectable (i.e., screen it out).

Examples

Example 1

For terms defined in fields that are SET OF CODES:

>S file=2,field=.02,iref="M",datetime=$$NOW^XLFDT

>W $$SCREEN^XTID(file,field,iref,datetime)
0

Example 2

For terms defined in a single file:

>S file=16000009,field=.01,iref="3,",datetime=""

>W $$SCREEN^XTID(file,field,iref,datetime)
0

Example 3

When searching a large file:

>S file=120.52,field=.01,datetime=""
>S SCREEN="I '$$SCREEN^XTID(file,field,Y_"","",datetime,.cached)"
>. . .
>K cached
>D LIST^DIC(file,,".01;99.99",,"*",,,,SCREEN,,"LIST","MSG")
>K cached