From VistApedia
Jump to: navigation, search

^XTMP Global


There is a recurring need by VistA software to store data in a translated global for relatively short periods of time. However, this data needs to be accumulated for a period longer than an individual user's logon session and longer than the time a specific process/job might run. The ^UTILITY, ^TMP and ^XUTL globals do not meet the basic requirements for storing this type of data due to the following:

  • These globals are not translated, and thus, cannot be relied upon for transferring data from one job to another.
  • The data is not stored for excessively long periods of time and is constantly being processed and purged.
  • The data is stored in an intermediate form, temporarily, so that it can be further processed in an efficient manner.
  • The original data is stored in a VA FileMan file from which the temporary data can be recreated,
    or on another system (usually non-VistA) from which it can be resent, if necessary.
    Hence, the creation of a VA FileMan file, while feasible, would add unnecessary overhead to the VistA systems.

Therefore, the Standards and Conventions Committee (SACC) asked Kernel to establish the ^XTMP global, which can be used by any VistA software application. This global is dynamic in size and activity, with one copy accessible to all members of a UCI, and should be placed accordingly.

Rules for Use of the ^XTMP Global

The structure of each top node of the ^XTMP global shall have the following format:

^XTMP(namespaced- subscript,0)=purge date^createdate^optional descriptive information (both dates must be in VA FileMan internal date format)

As per the Standards and Conventions (SAC, Section 2.11.8), developers are encouraged to include other descriptive information on the third piece of the 0 node of the ^XTMP global (e.g., task description and creator DUZ).

1. First Subscript Must Be Namespaced

The first subscript of the ^XTMP global must be namespaced.
However, other characters can follow the namespace. For example, if the namespace for the software is "RA," the first subscript could be "RA"_DUZ, "RA"_literal, "RA"_$J, etc. This allows the developer to use the global in different parts of the software.

2. 0 Node Must Exist

There must be a 0 node for the global in which the first piece contains the PURGE DATE in VA FileMan internal date format, and the second piece contains the CREATE DATE in VA FileMan internal date format.
For example: ^XTMP("RA1",0)=2920416^2920401

3. KILL ^XTMP After Use

The developer is responsible for KILLing ^XTMP(x) when its use is complete (where "x" is their namespaced subscript).

4. Code Cleanup

Kernel has included the necessary code in the ^XQ82 routine to clean up the ^XTMP global (e.g., ^XTMP("RA1").
It KILLs this global under any of the following conditions:
a) There is no 0 node (e.g., ^XTMP("RA1",0).
b) The 0 node does not contain a purge date as the first piece.
c) The date in the first piece of the 0 node is the same as or before the system date.

SAC Exemptions

As of May 17, 2002, the Standards and Conventions (SAC) document has the following exemptions regarding the ^XTMP global:

  • Section—Subscripts used in the ^TMP and ^XTMP globals can be lowercase.
  • Section—The ^TMP, ^UTILITY, and ^XTMP globals do not have to be VA FileMan compatible.
  • Section—The ^XTMP global will be translated, with one copy for the entire VistA production system at each site.
  • Section—All documented temporary scratch global nodes (e.g., ^TMP and ^UTILITY) are created by a called supported reference, with the exception of ^XTMP global data.
  • Section—All local variables, locks, and scratch global nodes (except ^XTMP, or other scratch globals designed to be passed between parts of a package) are created by the application.
A new extension must be added to the SAC stating that this global should be used as a scratch area when a translated scratch global is required by software applications.

To view the entire SAC document, please visit the SACC home page at the following Web address: