Process-private Globals

A process-private global is a variable that is only accessible by the process that created it. When the process ends, all of its process-private globals are deleted.

Process-specific: a process-private global can only be accessed by the process that created it, and cease to exist when the process completes. This is similar to local variables.
Always public: a process-private global is always a public variable. This is similar to global variables.
Namespace-independent: a process-private global exists independent of namespace. It is mapped to be accessible from all namespaces. Thus it can be created, accessed, and deleted regardless of current namespace. This differs from both local variables and global variables, which are both namespace-specific.
Unaffected by argumentless KILL, NEW, WRITE, or ZWRITE. A process-private global can be specified as an argument to KILL, WRITE, or ZWRITE. This is similar to global variables.

Process-private globals are intended to be used for large data values. They can serve, in many cases, as a replacement for the use of the Mgr/Temp directory, providing automatic cleanup at process termination.

Caché does not treat a SET or KILL of a process-private global as a journaled transaction event; rolling back the transaction has no effect on these operations.

Naming Conventions

A process-private global name takes one of the following forms:

^||name 
^|"^"|name 
^["^"]name 
^["^",""]name

These four prefix forms are equivalent, and all four refer to the same process-private global. The first form (^||name) is the most common, and the one recommended for new code. The second, third, and fourth forms are provided for compatibility with existing code that defines globals. They allow you to specify a variable that determines whether to define name as a process-private global or a standard global. This is shown in the following example:

  SET x=1       // toggle storage type
  IF x=1 {
    SET a="^"   // for a process-private global
  }
  ELSE {
    SET a=""    // for a standard global
  }
  SET ^|a|name="a value"

Process-private globals use the following naming conventions:

A process-private global name must be a valid identifier. Its first character (after the second vertical bar) must be either a letter or the percent (%) character. The percent (%) character can only be used as the first character of a process-private global name. Only percent variables that begin with “%Z” or “%z” are available for application code (such as ^||%zmyppg or ^||%Z123); all other percent variables are reserved for system use according to the rules described in “Rules and Guidelines for Identifiers” in the Caché Programming Orientation Guide.
The second and subsequent characters of a process-private global name may be letters, numbers, or the period character. A period cannot be used as the first or last character of the name.
A process-private global name cannot contain Unicode letters (letter characters above ASCII 255). Attempting to include a Unicode letter in a process-private global name results in a <WIDE CHAR> error.
Process-private global names are case-sensitive.
A process-private global name must be unique within its process.
Process-private global names are limited to 31 characters, exclusive of the prefix characters. You may specify a name longer than 31 characters, but only the first 31 characters are used. Therefore, a process-private global name must be unique within its first 31 characters.
Process-private globals can take subscripts. By using subscripts, you can define a process-private global as an array of values. A subscript can be a number or a character string; it can include Unicode characters. For subscript conventions, limitations on the number of subscript levels, and other information about use of subscripts, refer to Global Structure in Using Caché Globals.

Listing Process-private Globals

You can use the ^$||GLOBAL() syntax form of ^$GLOBAL() to return information about process-private globals belonging to the current process.

You can use the ^GETPPGINFO utility to display the names of all current process-private globals and their space allocation, in blocks. ^GETPPGINFO does not list the subscripts or values for process-private globals. You can display process-private globals for a specific process by specifying its process Id (pid), or for all processes by specify the "*" wildcard string. You must be in the %SYS namespace to invoke ^GETPPGINFO.

The following example uses ^GETPPGINFO to list the process-private globals for all current processes:

  SET ^||flintstones(1)="Fred"
  SET ^||flintstones(2)="Wilma"
  ZNSPACE "%SYS"
  DO ^GETPPGINFO("*")

^GETPPGINFO has the following syntax:

^GETPPGINFO("pdf","options","outfile")

The pdf argument can be a process Id or the * wildcard. The options argument can be a string containing any combination of the following: b (return values in bytes), Mnn (return only those process-private variables that use nn or more blocks); S (suppress screen display; used with outfile); T (display process totals only). The outfile argument is the file path for a file in CSV (comma-separated values) format that will be used to receive ^GETPPGINFO output.

The following example writes process-private variables to an output file named ppgout. The S option suppresses screen display; the M500 option limits output to only process-private variables that use 500 or more blocks:

  ZNSPACE "%SYS"
  DO ^GETPPGINFO("*","SM500","/home/myspace/ppgout")