Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).


Contains the ID of the principal I/O device.




$PRINCIPAL contains the ID of the principal I/O device for the current process. $PRINCIPAL operates like $IO. Refer to $IO for details of specific device types and system platforms.

If the principal device is closed, $PRINCIPAL does not change. If the principal input and output devices differ, $PRINCIPAL reflects the ID of the principal input device.

This special variable cannot be modified using the SET command. Attempting to do so results in a <SYNTAX> error.


This example uses $PRINCIPAL to test for a principal device.

   IF $PIECE($PRINCIPAL,"|",4) {
     WRITE "Principal device is: ",$PRINCIPAL }
   ELSE  { WRITE "Undefined" }

This example uses and writes to the principal device.

   WRITE "output to $PRINCIPAL"



$PRINCIPAL is functionally equivalent to the widely used, but nonstandard, USE 0. Use $PRINCIPAL instead of USE 0 because it is standard, and because it makes your code more flexible.

See Also

  • USE command

  • $IO special variable