Class Reference
IRIS for UNIX 2018.1.1
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

class %SYSTEM.Process extends %SYSTEM.Help

The %SYSTEM.Process class allows manipulation and display of the current process. Some of the class methods defined here have restrictions on where they may be called. Read the descriptions carefully.

There are two different syntaxes that can be used to call the class methods in this package: one uses the usual ##class syntax and the other uses $system. Here are two examples of calling ThrowError to signal the <UNIMPLEMENTED> error.

	do $system.Process.ThrowError(22)
	do ##class(%SYSTEM.Process).ThrowError(22)

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
70


Summary

Methods
AsyncDisconnectErr AsynchError BatchFlag BreakMode
Broadcast CSPSessionID CallingDatabase CallingRoutine
ClientExecutableName ClientIPAddress ClientNodeName CurrentDevice
CurrentDirectory DX DisableDiskReadTiming DisconnectErr
DiskReadMilliseconds EnableDiskReadTiming ErrorLine ExceptionLog
FileMode FixedDate FrameStackExpanded FrameStackSize
GetCPUTime GlobalKillDisabled GlobalReferences Help
IEEEError IODollarTest IPv6Format IsGhost
IsProgrammerMode JobType KillAllPrivateGlobals LanguageMode
LineRecall LinesExecuted MVUndefined MemoryAutoExpandStatus
NameSpace NodeNameInPid NullSubscripts OSError
OldZU5 OpenMode PopError PrivateGlobalLocation
RefInKind ResetDiskReadTiming Routine ScientificNotation
SetZEOF State StepInfo StoreErrorReason
SwitchOSdir SynchCommit SysRoutinePath TelnetNUL
TerminalPrompt Terminate ThrowError TimeZone
TransactionsSuspended TruncateOverflow Undefined UserName
UserRoutinePath ZDateNull


Methods

• classmethod AsyncDisconnectErr(switch As %Boolean) as %Boolean
The AsyncDisconnectErr(switch) class method specifies the asynchronous disconnect error handling for the current process. AsyncDisconnectErr is only applicable to Telnet connections on Windows. It has no effect on any other device type or operating system.

For the asynchronous disconnect error switch to be operational, the DisconnectErr() class method must set disconnect error switch to 1 for the current process.

Parameters

switch -- a boolean value that specifies the default mode for asynchronous disconnect errors:
0 -- the process receives a <DSCON> error at the next READ or WRITE command.
1 -- The process receives an asynchronous <DSCON> error immediately when a disconnect occurs on the device. This error occurs at the next command executed. HANG commands will be interrupted.

Invoking AsyncDisconnectErr() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the AsyncDisconnectErr method.

• classmethod AsynchError(switch As %Boolean) as %Boolean
The AsynchError(switch) class method specifies whether asynchronous errors can interrupt the current process.

Parameters

switch -- a boolean value that specifies the process behavior in response to asynchronous errors:
0 -- disables the reception of asynchronous errors.
1 -- enables the reception of asynchronous errors. (1 is the usual default)

Invoking AsynchError() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the AsynchError method.

• classmethod BatchFlag(switch As %Boolean) as %Boolean
The BatchFlag(switch) class function specifies either batch or interactive status for the current process. This allows you to balance resources more effectively.

Parameters

switch -- a boolean value that controls the status of the issuing process:
0 -- Clears batch status and gives the process interactive status. (0 is the usual default)
1 -- Gives the process batch status.

Invoking BatchFlag() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the BatchFlag method.

• classmethod BreakMode(switch As %Boolean) as %Boolean
The BreakMode(switch) class method enables or disables the processing of argumentless BREAK commands by the current process.

Parameters

switch -- a boolean value that specifies the default behavior of argumentless BREAK:
0 -- Treats an argumentless BREAK as a no-op.
1 -- Executes BREAK on an argumentless BREAK. (1 is the usual default)

Invoking BreakMode() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the BreakMode method.

• classmethod Broadcast(pid As %Integer, message As %String, timeout As %Integer, noxy As %Boolean) as %Boolean
The Broadcast(pid,message,timeout,noxy) class method sends a message to the principal device of the process you indicate.

Broadcast passes the message to the target process. The target process then writes the message to its principal output device. The target process must be running the InterSystems IRIS kernel. If you send a message to your own process, you do not see the message on the screen of your principal device.

Broadcast does not add any carriage controls to the message it sends. To include any carriage control (carriage returns or line feeds), you must include them in the message, using $CHAR(13) and $CHAR(10).

%SYSTEM.Process.Broadcast complements %Library.Device.Broadcast. %Library.Device.Broadcast sends a message to a specified device while %SYSTEM.Process.Broadcast sends a message to the principal device of a specified process. Be sure that you use the right function for the right purpose.

Parameters

pid -- The Process ID of the target process. The System Management Portal provides a Processes option, which list the pids of all running processes. Select [Home] > [Processes].
message -- The message to send, specified as a string.
timeout -- Optional -- An integer specifying the number of seconds to wait before timeout. If omitted, no timeout occurs.
noxy -- Optional -- If 0, $X and $Y are updated in the receiving process to indicate the location of the end of the broadcast message. If 1, $X and $Y are not updated. The default is 0. This parameter does not apply to OpenVMS systems, which do not update $X and $Y following a broadcast message.

Return value -- 1 if pid belongs to an InterSystems IRIS process and the message was sent to that process; 0 otherwise.

• classmethod CSPSessionID(pid As %Integer = "") as %String
The CSPSessionID(pid) class method returns the CSP session ID of the client that initiated the connection to a process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the CSP session ID of the client that initiated the connection to the specified process.

• classmethod CallingDatabase() as %String
The CallingDatabase() class method returns the name of the namespace of the calling routine of the last DO or user-defined call made to the current routine issuing a call to this function. If no calling routine exists, CallingDatabase() returns the null string.
• classmethod CallingRoutine() as %String
The CallingRoutine() class method returns the name of the calling routine name of the last DO or user-defined call made to the current routine issuing this function. If no calling routine exists, CallingRoutine() returns the null string.
• classmethod ClientExecutableName(pid As %Integer = "") as %String
The ClientExecutableName(pid) class method returns the name of the executable that called a process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the executable name of the client that initiated the connection to the specified process

• classmethod ClientIPAddress(pid As %Integer = "") as %String
The ClientIPAddress(pid) class method returns the IP address of the system that initiated the connection a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the IP Address of the system that initiated the connection to the specified process.

• classmethod ClientNodeName(pid As %Integer = "") as %String
The ClientNodeName(pid) class method returns the name of the client system that connected to, or initiated the connection to, a process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the system name for the client that connected to, or initiated the connection to, the specified process

• classmethod CurrentDevice(pid As %Integer = "") as %String
The CurrentDevice(pid) class method returns the device name of a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the device name of the specified process.

• classmethod CurrentDirectory(dir As %String) as %String
The CurrentDirectory(dir) class method sets your current working directory for sequential file output to the directory named by the parameter. If the directory cannot be set as the current working directory, CurrentDirectory issues a <DIRECTORY> error, and ^SYSLOG will show the cause of the error. This directory should not be confused with the default directory for globals in the current namespace.

Note: On Windows systems, CurrentDirectory(dir) sets as the current directory a directory name entirely in lowercase letters, regardless of the case of dir. Because Windows and ObjectScript are not case-sensitive, this is usually irrelevant. However, this may affect some Windows applications (such as Java) which are case-sensitive.

Parameters

dir -- Name of directory to set as working directory for sequential file output.

Invoking CurrentDirectory() without specifying the dir parameter returns the current working directory setting.

Return value -- the working directory prior to calling the CurrentDirectory method.

• classmethod DX(switch As %Integer) as %Integer
The DX(switch) class method specifies how the current process handles escape sequences when updating the $X special variable. When reading a string containing an escape sequence, various InterSystems products handle updating the $X special variable differently. You can control the way the system updates $X when writing a string containing an escape sequence. Default behaviors for various implementations are:

Unix parses the ANSI-standard escape sequence and counts the rest of the non-escape characters in the string against $X.

Open M [DSM] counts all characters in a string, including the escape character, against $X.

MSM counts all characters in the string, except for the escape character, against $X.

Alpha OpenVMS does not count any more characters in the string against $X after encountering an escape character ($CHAR(27)).

Parameters

switch -- an integer that specifies the method of updating $X for an individual process:
0 -- Specifies Unix and Windows default behavior.
1 -- Specifies Open M [DSM] default behavior.
2 -- Specifies MSM default behavior.
3 -- Specifies Alpha/VAX default behavior.

Invoking DX() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the DX method.

• classmethod DisableDiskReadTiming()
The DisableDiskReadTiming class method disables timing of disk reads for the current process.

Return value -- none

• classmethod DisconnectErr(switch As %Boolean) as %Boolean
The DisconnectErr(switch) class method determines how the system responds to the disconnection of the principal I/O device being accessed from the current process. When set to 1, the process receives a <DSCON> error when a disconnect is detected during an ObjectScript READ or WRITE command to the device. This is known as "error on disconnect." When set to 0, the process exits without reporting an error to the application when a disconnect is detected.

Parameters

switch -- a boolean value that specifies whether the system detects I/O device disconnection:
0 -- Disables disconnection detection. (0 is the usual default)
1 -- Enables disconnection detection.

Invoking DisconnectErr() without specifying the switch parameter returns the current switch setting.

Return value -- The switch state prior to calling the DisconnectErr method.

• classmethod DiskReadMilliseconds(pid As %Integer = "") as %Integer
The DiskReadMilliseconds class method returns the total recorded time spent in disk reads for a given process ID.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the total recorded time spent in disk reads for that process, in milliseconds

• classmethod EnableDiskReadTiming()
The EnableDiskReadTiming class method enables timing of disk reads for the current process.

Return value -- none

• classmethod ErrorLine() as %String
The ErrorLine() class method returns source file and line of code for last ObjectScript error. The source file and line number usually refer to the kernel code that was written by InterSystems. This information is useful when requesting InterSystems support for help recovering from an error.

The name of the last ObjectScript error that occurred is contained in the $ZERROR special variable.

• classmethod ExceptionLog(switch As %Boolean) as %Boolean
The ExceptionLog(switch) class method specifies the display of a Windows message box. When enabled, this box displays stack and register usage information when a cache.exe process encounters an exception. Because processing cannot proceed until the user responds to this message box, ExceptionLog(switch) provides the option to suppress the display of this message box to facilitate unattended system operation, such as scripted shutdown and restart.

Parameters

switch -- a boolean value that specifies whether or not the system should display or suppress the Windows stack and register usage box for the current process when it encounters an exception:
0 -- suppress display of the message box. (0 is the usual default)
1 -- enable display of the message box.

Invoking ExceptionLog() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the ExceptionLog method.

• classmethod FileMode(switch As %Boolean) as %Boolean
The FileMode(switch) class method specifies if a sequential file is created automatically in response to an OPEN command that specifies a file that does not already exist. If you attempt to open a file in "W" or "RW" mode, but that file does not yet exist, the default behavior is platform-dependent. On Windows and Unix systems, the default is for the process to hang until the file is actually created, or until the process is resolved by a timeout expiration or by calling the RESJOB utility. On OpenVMS systems, the default is to create a new sequential file.

Calling FileMode(switch) can override the default. Calling FileMode(1) causes the system to create a sequential file automatically when you issue the OPEN command in "W" or "RW" mode for a file that does not already exist; calling FileMode(0) prevents the OPEN command from automatically creating a sequential file when the file does not already exist. This FileMode setting governs all sequential file opens in the current process.

Parameters

switch -- a boolean value that specifies whether or not a file is created when the process attempts to open a nonexistent file for writing:
0 -- automatic new file creation is disabled. (0 is the usual default for Unix and Windows systems)
1 -- automatic new file creation is enabled. (1 is the usual default for VMS systems)

Invoking FileMode() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the FileMode method.

• classmethod FixedDate(date As %Integer) as %Integer
The FixedDate(date) class method sets the date internally stored in the $HOROLOG special variable to a specified fixed value for the current process. Calling FixedDate(0) turns off this function, restoring $HOROLOG to the current local date.

Using this function to set a fixed value for the date causes all subsequent calls to $HOROLOG from that process to return that fixed value as the date. A date set using FixedDate(date) is a fixed date; it does not increment at midnight.

FixedDate(date) has no effect on the time portion of $HOROLOG, which continues to represent the current time.

To restore $HOROLOG to the current date, issue FixedDate(0). This call reverts $HOROLOG to the current date.

Parameters

date -- A positive integer that represents a date in $HOROLOG format. An integer that falls between 1 (January 1, 1841) and 2980013 (December 31, 9999) inclusive fixes that date. A date parameter of 0 turns off this function.

Invoking FixedDate() without specifying the date parameter returns the current FixedDate value with no effect on $HOROLOG. FixedDate() returns zero if $HOROLOG is not set to a fixed value

Return value -- the FixedDate value prior to calling the FixedDate method.

• classmethod FrameStackExpanded() as %Boolean
Indicates whether the frame stack has been expanded following a <FRAMESTACK> error.
If it is 1, another <FRAMESTACK> will terminate the process without running any error trap.
It will automatically return to 0 after enough stack entries are popped to return to normal operation.
• classmethod FrameStackSize() as %Integer
Returns the frame stack size, in bytes, for the current process.
• classmethod GetCPUTime() as %String
Get CPU time used for current process.

Returns two comma-delimited pieces, "system" CPU time and "user" CPU time (except on VMS where no separate times are available). Time is returned as milliseconds of CPU time.
• classmethod GlobalKillDisabled(switch As %Boolean) as %Boolean
The GlobalKillDisabled(switch) class function specifies whether a Kill of a root-level global node is disabled as a command to an interactive terminal session. This switch does not affect the Kill command applied interactively to a subscripted global nor does it affect any Kill used as a command within a routine.

Setting the GlobalKillDisabled() switch provides some minimal protection against certain typing errors involving the KILL command while directly entering interactive commands to a InterSystems IRIS terminal session. It does not prevent a user from entering the XECUTE "KILL ^a" command to kill all of global variable ^a. The switch also has no effect on commands typed interactively to other command shells, such as the MV (MultiValue) shell.

Parameters

switch -- a Boolean value that specifies whether the current process allows a Kill of a root-level global node as an interactive terminal command:
0 -- Root-level global node kills are allowed. (0 is the default)
1 -- Root-level global node kills are not allowed from the command line, but are allowed from routines.

Invoking GlobalKillDisabled() without specifying the switch parameter returns the current switch setting.

Return Value -- the switch state prior to calling the GlobalKillDisabled method.

• classmethod GlobalReferences(pid As %Integer = "") as %Integer
The GlobalReferences(pid) class method returns the number of global references made by a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the number of global references made by the specified process.

• classmethod IEEEError(switch As %Boolean) as %Boolean
The IEEEError(switch) class method specifies the issuing of INF, -INF, and NAN when a $DOUBLE numeric operation encounters an overflow, divide-by-zero or invalid-operation exception. It does not control the issuing of INF, -INF, and NAN in all cases. Regardless of the ExceptionLog() setting, $DOUBLE operations return INF, -INF, or NAN when you supply one of these values as an operand and an overflow, divide-by-zero or invalid-operation exception does not occur. Operations that can generate IEEE Exceptions when encountering $DOUBLE values include conversions from a numeric string, arithmetic operations, exponentiation, and logarithmic and trigonometric functions.

Parameters

switch -- a boolean value that specifies the $DOUBLE exception mode setting for the current process:
0 -- $DOUBLE operations return INF, -INF, or NAN when encountering an IEEE exception.
1 -- $DOUBLE operations generate <MAXNUMBER>, <ILLEGAL VALUE>, and <DIVIDE> errors when encountering an IEEE exception. (1 is the usual default)

Invoking IEEEError() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the IEEEError method.

• classmethod IODollarTest(flag As %Boolean) as %String
The IODollarTest(flag) class method specifies how to handle the $TEST special variable on return from I/O redirection by issuing this function. By default, the value of $TEST is preserved (stored and restored) across a call to extrinsic code, such as I/O redirection code. However, you may wish to return the setting of $TEST from I/O redirection code. For example, if application code invokes a READ command with I/O redirection, and the READ times out, this timeout sets $TEST in your application. To preserve this setting of $TEST upon returning from I/O redirection code, you must invoke LanguageMode within the I/O redirection code.

Note: LanguageMode can only be invoked from extrinsic code. It cannot be called directly from the terminal. Attempting to do so results in a <FUNCTION> error.

Parameters

flag -- boolean value used to set the $TEST special variable upon return from I/O redirection code.
0 -- Clears $TEST (sets to 0) on return from the redirected READ.
1 -- Sets $TEST (sets to 1) on return from the redirected READ.

• classmethod IPv6Format(switch As %Boolean) as %Boolean
The IPv6Format(switch) class method specifies the types of IP address formats supported by the current process. When IPv6 is enabled, the system accepts an IP address on the OPEN command in either IPv6 or IPv4 format, or as a host name, with or without domain qualifiers. The system first checks for an IPv4 format address, then for an IPv6 format address; it accepts the first successful connection.

Parameters

switch -- a boolean value that specifies IP address format:
0 -- IPv6 format disabled--IPv4 only. (0 is the usual default)
1 -- IPv6 format enabled--both IPv4 and IPv6 supported.

Invoking IPv6Format() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the IPv6Format method.

• classmethod IsGhost(pid As %Integer) as %Boolean
The IsGhost(pid) class method returns 1 if a specified process has been killed at the O/S level and has not yet been cleaned by the CLNDMN process. Until the process is cleaned, their may be outstanding locks or resources which may be unavailable to other processes. Otherwise, this method returns 0.

Parameter

pid -- Process id of the process being queried

Return value -- 1 if the specified process is a Ghost process;
0 otherwise

• classmethod IsProgrammerMode() as %Boolean
The IsProgrammerMode() class method returns 1 if the current process started in programmer mode, zero otherwise. Equivalent to $zjob#2.
• classmethod JobType(pid As %Integer = "") as %Integer
The JobType(pid) class method returns the job type of a specified process. The job type is a number which tells what type of process it is. See the %syPidtab.inc include file for a definition of macros for these fields. Only use the defined macros in %syPidtab when referencing these fields. For example:
If $SYSTEM.Process.JobType(pid)=$$$WDTYPE {
   w !,"Process ",pid," is the write daemon"
}

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the job type of the specified process.

• classmethod KillAllPrivateGlobals() as %Status
Kill all process private globals for the calling process.
• classmethod LanguageMode(mode As %Integer) as %Integer
The LanguageMode(mode) class method returns or changes the current language mode.

You can use LanguageMode to change the language mode at the programmer prompt.

When the system executes a routine, it automatically changes the language mode to the routine's language mode. A DO command or a $$ extrinsic function temporarily changes the language mode to that of the called routine. The system then restores the previous language mode when the routine terminates. Therefore, you need not (and cannot) change the language mode during runtime execution of a routine.

The ZLOAD command changes the language mode to the loaded routine's language mode. However, ZLOAD does not restore the previous language mode upon termination of the routine. One use of LanguageMode is to set the language mode following a ZLOAD operation.

LanguageMode can change the process' language mode at any time. However, when executing a routine you should only do this under XECUTE, and restore before leaving the XECUTE operation. This technique is commonly used to set language mode when compiling a routine.

The object code (tokens, mcode, and so on) for a routine is generated at compile time according to the language mode in effect at that time. This language mode determines the routine's runtime behavior, except for a few cases where language mode is tested at runtime.

Any form of indirection (for example, an XECUTE command, or the @ indirection operator) is evaluated at runtime according to the current language mode. This language mode may not be the same as the language mode of the running routine.

Parameters

mode -- Optional -- A numeric code specifying what language mode to set.

Language Mode Codes

0 -- Set language mode to ObjectScript. (0 is the usual default)
1 -- Set language mode to DSM-11.
2 -- Set language mode to Open M [DTM].
5 -- Set language mode to DSM for OpenVMS.
6 -- Set language mode to DSM-J (Japanese) for OpenVMS.
7 -- Set language mode to DTM-J (Japanese) for OpenVMS.
8 -- Set language mode to MSM. MSM mode changes the use of the $ZC ($ZCHILD) special variable.

Notes:

If you change the language mode with the LanguageMode class method so that it does not match that of the loaded routine, and then attempt to do a ZINSERT, you will get a <LANGUAGE MISMATCH> error message.

In language modes 1 (DSM-11) and 8 (MSM) five-character error codes are used: <FUNCT>, <UNDEF>, <SYNTX>, <DIVER> (division error), and so forth.

Invoking LanguageMode() without specifying any parameter codes returns the language mode code as an integer.

Return value -- the language mode integer code prior to calling the LanguageMode method.

• classmethod LineRecall(switch As %Boolean) as %Boolean
The LineRecall(switch) class method enables or disables read line recall for terminal devices opened by the current process. Read line recall is only used by terminal devices. The current LineRecall setting is only applied when a terminal device is explicitly opened using the OPEN command.

Parameters

switch -- a boolean value that controls read line recall mode:
0 -- Disables read line recall mode.
1 -- Enables read line recall mode. (1 is the usual default)

Invoking LineRecall() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the LineRecall method.

• classmethod LinesExecuted(pid As %Integer = "") as %Integer
The LinesExecuted(pid) class method returns the number of lines executed by a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the number of lines executed by the specified process.

• classmethod MVUndefined(switch As %Boolean) as %Boolean
The MVUndefined(switch) class method specifies MVBasic behavior for the current process when it encounters a reference to an undefined variable. By default, if the current MVBasic routine references an undefined variable, the system generates an <UNDEFINED> error. You can change this default behavior to have the system substitute an empty string for an undefined variable, without signaling an error.

Parameters

switch -- a boolean value that specifies whether or not the system should issue an error when the current MVBasic routine references an undefined variable:
0 -- issue an <UNDEFINED> error for an undefined variable. (0 is the usual default)
1 -- substitute the empty string for an undefined variable.

Invoking MVUndefined() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the MVUndefined method.

• classmethod MemoryAutoExpandStatus() as %Integer
The MemoryAutoExpandStatus() class method returns a value that allows the caller to determine the reason for the last <STORE> error that has been thrown.

Return value -- one of the following values can be returned:

0 -- The job has never had a <STORE> error thrown.
1 -- The <STORE> error was thrown because the process exceeded the $ZSTORAGE value and there was no auto expansion of the $ZSTORAGE value.
2 -- The <STORE> error was thrown because the process exceeded the $ZSTORAGE value and the $ZSTORAGE value was auto expanded by 1M.
3 -- The <STORE> error was thrown because of reasons other than exceeding the $ZSTORAGE value.

Return value 3 is typically returned when the operating system refuses to give more memory to the process. Typical reasons (but not an exhaustive list) can be because the operating system has run out of swap space. On Unix based systems it could be because you have exceeded a system enforced limit (for example 'ulimit -v' on some platforms sets a limit on the maximum virtual memory size).

• classmethod NameSpace(pid As %Integer = "") as %String
The NameSpace(pid) class method returns the namespace name of a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the namespace name of the specified process.

• classmethod NodeNameInPid(switch As %Boolean) as %Boolean
The NodeNameInPid(switch) class method specifies the format that the $JOB special variable returns for the current process.

This function provides for a unique value for $JOB on networked systems. This is useful when using $JOB to index globals accessed by more than one networked system. In the form NodeNameInPid(1), the $JOB special variable returns a string of the format processid:nodename.

Parameters

switch -- a boolean value that specifies the string format that $JOB returns:
0 -- specifies the standard $JOB format. (0 is the usual default)
1 -- specifies the format as processid:nodename.

Invoking NodeNameInPid() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the NodeNameInPid method.

• classmethod NullSubscripts(switch As %Boolean) as %Boolean
The NullSubscripts(switch) class method allows setting and referencing globals with null subscripts within the current process.

If null subscripted globals are not enabled (switch=0), attempting to set a null subscripted variable, such as SET ^x("")=99, or to reference a null subscript, such as WRITE ^x(""), results in a <SUBSCRIPT> error.

If null subscripted globals are enabled (switch=1), you can set a null subscripted variable, such as SET ^x("")=99, just like any other variable. Referencing an undefined null subscripted variable results in a <UNDEFINED> error.

Parameters

switch -- a boolean value that specifies the null subscript mode setting for the current process:
0 -- Disables setting/referencing null subscripted globals. (0 is the usual default)
1 -- Enables setting/referencing null subscripted globals.

Invoking NullSubscripts() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the NullSubscripts method.

• classmethod OSError() as %String
The OSError() class method returns the operating system error code for a sequential file error.

When a sequential file I/O operation fails, the operating system returns an error code to InterSystems IRIS. InterSystems IRIS, in turn, issues its own corresponding error code. OSError() returns the operating system error code number (in angle brackets) followed by the operating system error message. These operating system errors are specific to the operating system being used.

• classmethod OldZU5(switch As %Boolean) as %Boolean
The OldZU5(switch) class method specifies whether or not issuing the $ZUTIL(5) function with the current namespace clears global vectors for the current process.

OldZU5(1) provides compatibility with $ZUTIL(5) behavior before Cache version 3.1; this call enables the clearing of global vectors for the current process when $ZUTIL(5) is issued with the current namespace.

Parameters

switch -- a boolean value that specifies whether or not there is global vector clearing:
0 -- (default behavior) disables global vector clearing. (0 is the usual default)
1 -- (legacy behavior) clears global vectors.

Invoking OldZU5() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the OldZU5 method.

• classmethod OpenMode(switch As %Boolean) as %Boolean
OpenMode(switch) is a class method that specifies the open mode for sequential files opened by the current process. When the current process issues an OPEN command for a sequential file, that file is opened either in read-only mode (R) or read/write mode (RW). Calling OpenMode(switch) specifies this open mode for the current process, overriding the system-wide default setting.

Parameters

switch -- a boolean value that specifies the default mode for sequential files on OPEN for the current process:
0 -- read-only (R) is the OPEN default. (0 is the usual default)
1 -- read and write (RW) is the OPEN default.

Invoking OpenMode() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the OpenMode method.

• classmethod PopError(switch As %Boolean) as %Boolean
The PopError(switch) class function specifies whether a process uses InterSystems IRIS-style error handling (the default) or legacy (DSM) error handling.

When a InterSystems IRIS-style error handler is invoked, that error handler remains on the stack of established error handlers. Therefore, if an error occurs while the InterSystems IRIS-style error handler is executing, that error handler attempts to invoke itself, receives the same error again and enters an infinite loop, unless that error handler explicitly sets the $ZTRAP special variable to a new value.

When an error handler is invoked in DSM, the DSM-style error handler is unwound from the stack. Therefore, if an error occurs while the DSM-style error handler is executing, that error is handled by the previous error handler on the stack.

Parameters

switch -- a boolean value that specifies whether or not a process uses InterSystems IRIS-style error handling:
0 -- specifies InterSystems IRIS-style behavior. (0 is the usual default)
1 -- specifies DSM-style behavior.

Invoking PopError() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the PopError method.

• classmethod PrivateGlobalLocation() as %String
The PrivateGlobalLocation() class method returns the location of the process-private globals database in the form sfn^dir. If no process-private globals are defined, this defaults to 15999^0.
• classmethod RefInKind(switch As %Boolean) as %Boolean
The RefInKind(switch) class method specifies whether $QUERY and $NAME return an extended global reference when the first argument of $QUERY or $NAME contains an extended global reference. A switch value of 0 returns the extended global reference. A switch value of 1 strips the extended global reference before returning the global. Invoking the ZWRITE command returns the extended global reference regardless of the RefInKind setting.

Parameters

switch -- a boolean value that specifies whether $QUERY or $NAME return an extended global reference:
0 -- Retains the extended global reference; this enables reference-in-kind. (0 is the usual default)
1 -- Strips the extended global reference and returns just the global; this disables reference-in-kind.

The 1 value for the switch is provided for backward compatibility.

Invoking RefInKind() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the RefInKind method.

• classmethod ResetDiskReadTiming()
The ResetDiskReadTiming class method resets the recorded time of disk reads for the current process to 0.

Return value -- none

• classmethod Routine(pid As %Integer = "") as %String
The Routine(pid) class method returns the routine name of a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the routine name of the specified process.

• classmethod ScientificNotation(switch As %Boolean) as %Boolean
The ScientificNotation(switch) class method specifies the evaluation of the lowercase letter "e" as a scientific notation exponent symbol for the current process. ScientificNotation has no effect on the evaluation of uppercase "E" as an exponent symbol.

Parameters

switch -- a boolean value that specifies whether or not a process should treat lowercase "e" as a scientific notation base-10 exponent symbol:
0 -- do not evaluate "e" as an exponent symbol.
1 -- evaluate "e" as an exponent symbol. (1 is the usual default)

Invoking ScientificNotation() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the ScientificNotation method.

• classmethod SetZEOF(switch As %Boolean) as %Boolean
The SetZEOF(switch) class method specifies end-of-file flagging format. This function is provided to support interoperability, and the porting of MSM routines that use the MSM $ZC function to check for end of file on sequential file reads. This MSM function should not be confused with the ObjectScript $ZC function (which is an abbreviation for $ZCHILD).

A switch value of 1 eliminates the <ENDOFFILE> error for sequential files for the current process. Instead, when the end of a file is reached, the READ command returns a null string, the $ZPOS special variable is set to "" (the null string), and the $ZEOF special variable is set to -1.

Parameters

switch -- a boolean value that specifies end-of-file handling for the current process:
0 -- default format.
1 -- end-of-file flagging format.

Invoking SetZEOF() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the SetZEOF method.

• classmethod State(pid As %Integer) as %String
The State(pid) class method returns the current state of a specified process.

The current state of a process is determined by the processes state bits.
The following are all the different states a process can be in. The process may also have a number of different flags within these states which are appended to the end of the state name:
LOCK - Executing a Lock command
OPEN - Opening a device
CLOS - Closing a device
USE - Using a device
READ - Read command
WRT - Write command
GGET - Executing a $Get on a global
GSET - Setting a global
GKLL - Killing a global
GORD - $Order on a global
GQRY - $Query on a global
GDEF - $Data on a global
ZF - Executing a $ZF command
HANG - Executing a Hang command
JOB - Executing a Job command
EXAM - Executing a variable exam
BRD - Executing a broadcast
SUSP - Process is suspended
INCR - Executing a $Increment
BSET - Set $bitset
BGET - Get $bitset
EVT - Waiting on event RUN - Process is running

Here are the flags which can be appended to the state:

CS - cluster slave job waiting for net answer
NL - Net lock waiting
DT - The dead job has open transaction
S - Suspension requested
GW - Global Wait
NR - Net Read
D - Dead
H - Halting
NH - Netharden
N - Remote network
W - Hibernating

Parameter

pid -- Process id of the process being queried

Return value -- the process state string described above

• classmethod StepInfo() as %String
The StepInfo() class method is invoked during debugging and returns information about the location of the last single step entered.

Return Values

This function returns the following information about the last single step entered:
<stacklevel><xeclevel><lineref><srcoffset><src>
where:

stacklevel -- $STACK level of the breakpoint.
xeclevel -- XECUTE level of the breakpoint.
lineref -- Line reference of the breakpoint.
srcoffset -- 0-based offset to the location in the source line where the break has occurred.
src -- Source line of the breakpoint.

This function is a useful primitive in the development of trace capabilities beyond what is offered by the "T" action.

You can invoke StepInfo() only in the condition expression or the execute code associated with a
ZBREAK $::condition:execute
breakpoint, or in routines and functions invoked from these contexts.

You must have the %Development:Use privilege to execute the StepInfo function.

• classmethod StoreErrorReason() as %Integer
Returns the possible reasons for the last <STORE> error as follows.

0 - No <STORE> error has yet occurred for this proces.
1 - The value of $STORAGE went negative.
2 - The value of $STORAGE went below its emergency margin of -1048576 (-1MB).
3 - The OS refused to give any more memory resources to the process.
4 - Attempt to set $ZSTORAGE to a value that would cause $STORAGE to become negative.
• classmethod SwitchOSdir(switch As %Boolean) as %Boolean
The SwitchOSdir(switch) class method specifies whether changing the namespace also changes the default directory. By default, changing to a new namespace causes InterSystems IRIS to change the directory at the operating system level to the default directory for that namespace.

Parameters

switch -- a boolean value that specifies the default behavior when changing namespaces:
0 -- Changing the namespace automatically changes the default directory to the directory for that namespace. (0 is the usual default)
1 -- Changing the namespace does not change the default directory.

Invoking SwitchOSdir() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the SwitchOSdir method.

• classmethod SynchCommit(switch As %Boolean) as %Boolean
The SynchCommit(switch) class method sets the synchronous transaction commit mode for the current process. This enables or disables synchronizing TCOMMIT with the corresponding journal write operation. Every TCOMMIT command requests a flush of the journal data involved in that transaction to disk. When SynchCommit is enabled (set to 1) a TCOMMIT does not complete until the journal data write operation completes. When set to 0, TCOMMIT does not wait for the write operation to complete.

Parameters

switch -- a boolean value that specifies the default mode for synchronous transaction commit:
0 -- TCOMMIT completion does not wait for journal file write completion. (0 is the usual default)
1 -- TCOMMIT completion waits for the journal file write operation to complete.

Invoking SynchCommit() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the SynchCommit method.

• classmethod SysRoutinePath(primary As %String, second As %String, third As %String) as %String
The SysRoutinePath() class method specifies the namespace(s) that contains the routine dataset for system routines that begin with per cent (%).

To change the source from which you want to draw system routines, use SysRoutinePath to specify the namespace that contains the routine dataset in which the system routines you want to use are located.

Parameters

primary -- Optional -- Specify the primary namespace that contains the system routine dataset. If used alone, this is the namespace that will be searched for all system routines. If used in conjunction with second and third, primary will be the first namespace searched for system routines.
second -- Optional -- Specify the second namespace to search for system routines. If the system does not find a system routine in primary, it will search for it in second.
third -- Optional -- Specify the third namespace to search for system routines. If the system does not find a system routine in primary or second, it will search for it in third.

If there are no parameters passed to SysRoutinePath() then the method returns the current primary namespace as a string and the System Routine Path is unchanged. If there are parameters then the entire System Routine Path is replaced with the newly specified path.

Calling SysRoutinePath("") with a null string as a parameter resets the current namespace for system routine access to the default namespace.

The namespace strings you specify can be either an explicit namespace or an implied namespace (a directory path or OpenVMS file specification preceded by two caret characters (^^)).

To understand SysRoutinePath, you need to keep the following in mind. When a process starts, it uses routines in the current namespace. After you issue $system.Process.SysRoutinePath(new), all subsequent system routines come from new.

If you issue $system.Process.SysRoutinePath(new,second,third), all subsequent system routines located in namespace new will come from new. If the system does not find a system routine in new, the system looks for the routine in namespace second. If the system does not find the system routine in second, the system looks for the routine in namespace third.

Note: Using routines in second is VERY slow! You should use second as an aid to program development, not as a normal running procedure.

To use SysRoutinePath as a development aid, make new your development area and use second as a storage area of routines that work. When you issue ZSAVE, the system routine you save always goes into new, even if you loaded it from second. As you edit and file system routines, they appear in new without affecting the library in second, and subsequent calls for the system routines get the new version from new.

The method does not affect globals; the original namespace still defines access privileges for globals. Your process uses globals in the current namespace unless you make explicit or implicit references to globals in other namespaces. In other words, the system routines come from primary (or from second or third), while the globals come from the process's current namespace.

This method does not affect user routines whose names do not begin with a per cent (%). For user routines see the UserRoutinePath method.

Return value -- the primary namespace for system routine access that was set before you called SysRoutinePath.

• classmethod TelnetNUL(switch As %Boolean) as %Boolean
The TelnetNUL(switch) class method specifies the issuance of a NUL character (ASCII 0) following a CR character (ASCII 13) at end-of-line during Telnet transmission. On output, a Telnet network virtual terminal (NVT) performs the following default end-of-line behavior: either issues a CR (carriage return character) followed by a LF (linefeed character), or issues a CR (carriage return character) followed by a NUL character (if no LF is issued). TelnetNUL(switch) affects the issuance of the NUL character in this second case.

Parameters

switch -- a boolean value that specifies whether or not the system should suppress NUL following a CR at end-of-line:
0 -- do not suppress NUL. (0 is the usual default)
1 -- suppress NUL.

Invoking TelnetNUL() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the TelnetNUL method.

• classmethod TerminalPrompt(p1 As %Integer, p2 As %Integer, p3 As %Integer, p4 As %Integer, p5 As %Integer, p6 As %Integer, p7 As %Integer, p8 As %Integer) as %String
The TerminalPrompt(p1,p2,...) class method specifies what information should appear in the programmer-mode prompt for InterSystems IRIS Terminal.

Issuing TerminalPrompt() (with no arguments) does not change the terminal prompt but it does return the current state of the prompt setting as a comma-separated list of integer codes.

Issuing TerminalPrompt(0) clears the setting, so that no prompt information is displayed.

Issuing TerminalPrompt(p1,...), where none of the parameters are 0, sets the prompt to include the information specified by the parameter codes. The order of the parameter codes is the order the information appears in the prompt.

Parameters

p1 -- Optional -- Code for the 1st field of the terminal prompt.
p2 -- Optional -- Code for the 2nd field of the terminal prompt.
...
p8 -- Optional -- Code for the 8th field of the terminal prompt.

Prompt Codes

0 -- Reset the prompt.
1 -- Host name, also known as the current system name. The name assigned to your computer. For example, LABLAPTOP>. This is the same for all of your terminal processes.
2 -- Namespace name. For example, %SYS>. The current namespace name is contained in the $NAMESPACE special variable. It can be an explicit namespace name or an implied namespace name.
3 -- Config name. The name of your system installation. For example, DEVELOPMENT>. This is the same for all of your terminal processes.
4 -- Current time, expressed as local time in 24-hour format with whole seconds. For example, 15:59:36>. This is the static time value for when the prompt was returned. This value changes for each prompt.
5 -- pid. The Process ID for your terminal. For example, 2336>. This is different for each terminal process. This value can also be returned from the $JOB special variable.
6 -- Username. For example, fred&gr;. This is the same for all of your terminal processes.
7 -- Elapsed time executing the last command, in seconds.milliseconds. For example, .000495>. Leading and trailing zeros are suppressed. This changes for each prompt.
8 -- Transaction Level. For example, TL1>.

Invoking TerminalPrompt() without specifying any parameter codes returns the current prompt codes.

Return value -- the prompt codes prior to calling the TerminalPrompt method. This return value is a list of comma separated integers. It consists of the single integer 0 if no prompt codes are set.

• classmethod Terminate(pid As %Integer = "", ExitStatus As %Integer = 1) as %Integer
The Terminate(pid, ExitStatus) class method terminates a specified process and causes it to return a specified exit status to the O/S.

Parameters

  • pid -- Process id of the process being terminated
    Defaults to current process, $JOB, if parameter is missing

  • ExitStatus A nonnegative parameter value is the exit status returned to the O/S by the terminated process. Negative values are reserved to InterSystems except that -65 can be used to terminate a InterSystems IRIS instance daemon or a process in an unresolved transaction state.
    Defaults to 1 if the ExitStatus parameter is missing.

Return values

  • 1 -- Success
  • 0 -- Failure - Process exempt from termination (eg. GARCOL/DAEMON). It can only be terminated if you specify an ExitStatus parameter value of -65.
  • -1 -- Failure - Process is non-responsive
  • -2 -- Failure - Process is inactive, a ghost or a "dead" process
  • -3 -- Failure - Process pid does not reference an InterSystems IRIS process
  • -4 -- Failure -- The process has an open transaction that is currently in a halt or rollback state. The process cannot be terminated unless you specify an ExitStatus parameter value of -65.
• classmethod ThrowError(errnum As %Integer) as %String
The ThrowError(errnum) class method signals the error message that corresponds to the value of errnum. The error message occurs at the first stack level above the level that was pushed onto the stack by the invocation of a user-defined command. Refer to %ZLANG for further information on user-defined commands in ObjectScript.

Parameters

errnum -- A system error number, specified as an expression that resolves to a positive integer. This parameter is optional and if the parameter is missing then the most recently thrown system error number is thrown again.

• classmethod TimeZone(newTZ As %String) as %String
The TimeZone(newTZ) class method changes the time zone for the process.

Parameter

newTZ -- string specifying the time zone that will be assigned to the environment variable TZ. The time zone is usually specified in POSIX or Olson format. Check the OS manuals to see the appropriate syntax.

Invoking TimeZone() without an argument just returns the previous value of TZ.

Return value -- the previous value of the TZ environment variable or -1 if it was undefined.

• classmethod TransactionsSuspended(switch As %Boolean) as %Boolean
The TransactionsSuspended(switch) class method controls a switch that will allow a process to temporarily suspend transactions.

Warning: Changing a global variable during a transaction, then changing that same global while the transaction is suspended, can result in an error being logged if the transaction is ultimately rolled back. A global variable modification during the transaction suspension is not rolled back. This may prevent rolling back an earlier modification of that same variable that occured while the transaction was not suspended.

Parameters

switch -- a boolean value that specifies whether transactions are to be suspended or are to be resumed
1 -- Transactions are to be suspended.
0 -- Transactions are to be resumed.

Invoking TransactionsSuspended() without specifying the switch parameter returns the current switch setting without changing that setting.

Return value -- the TransactionsSuspended switch state prior to calling the TransactionsSuspended method.

• classmethod TruncateOverflow(switch As %Boolean) as %Boolean
The TruncateOverflow(switch) class method specifies whether or not the current process truncates very large numbers. The default behavior is not to truncate numbers.

Normally, when the system encounters a numeric string larger than 9223372036854775807E127 it converts the number to an IEEE double-precision number. This conversion only occurs during string-to-number conversions. A <MAXNUMBER> error can still occur during arithmetic operations. This conversion extends the numeric range available to literal numbers, but reduces the numeric precision by roughly 3 decimal digits. When the system encounters a number too large to be represented by an IEEE double-precision number, it either issues a <MAXNUMBER> error or returns INF, depending on the setting of ##class(%SYSTEM.Process).IEEEError().

When the TruncateOverflow switch is set, this automatic conversion of large numeric strings to the $DOUBLE type does not occur nor does an error occur. Instead, the largest positive decimal value, 9223372036854775807E127, or the largest negative decimal, -9223372036854775808E127, as appropriate, is returned. In addition, setting the TruncateOverflow switch will cause an overflow that occurs during decimal arithmetic operations to return these largest values rather than issuing a <MAXNUMBER> error.

Parameters

switch -- a boolean value that specifies whether number truncation occurs:
0 -- preserves large numbers and performs IEEE double-precision conversion on these numbers when necessary. (0 is the usual default)
1 -- truncates large numbers during the string-to-number conversion and suppresses IEEE conversion and <MAXNUMBER> errors.

Invoking TruncateOverflow() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the TruncateOverflow method.

• classmethod Undefined(switch As %Integer) as %Integer
Undefined(switch) is a class method used to specify the default behavior for the current process when handling undefined variables. Setting the Undefined switch changes this behavior for local variables, process-private globals, and global variables system-wide; it has no effect on special variables.

Parameters

switch -- a numeric code that specifies how ObjectScript treats an undefined variable. It takes on the following values:
0 -- Issues the <UNDEFINED> error for any undefined variable. (0 is the usual default)
1 -- Returns a null string for a reference to an undefined variable with subscripts, and issues the <UNDEFINED> error for undefined variables without subscripts.
2 -- Returns a null string (instead of issuing an <UNDEFINED> error) for any undefined variable.

Invoking Undefined() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the Undefined method.

• classmethod UserName(pid As %Integer = "") as %String
The UserName(pid) class method returns the user name of a specified process.

Parameter

pid -- Process id of the process being queried
Current process, $JOB, if parameter is missing

Return value -- the user name of the specified process.

• classmethod UserRoutinePath(primary As %String, second As %String, third As %String) as %String
The UserRoutinePath() class method specifies the namespace(s) that contains the routine dataset.

To change the source from which you want to draw routines, use UserRoutinePath to specify the namespace that contains the routine dataset in which the routines you want to use are located.

Parameters

primary -- Optional -- Specify the primary namespace that contains the routine dataset. If used alone, this is the namespace that will be searched for all routines. If used in conjunction with second and third, primary will be the first namespace searched for routines.
second -- Optional -- Specify the second namespace to search for routines. If InterSystems IRIS does not find a routine in primary, it will search for it in second.
third -- Optional -- Specify the third namespace to search for routines. If InterSystems IRIS does not find a routine in primary or second, it will search for it in third.

If there are no parameters passed to UserRoutinePath() then the method returns the current primary namespace as a string and the User Routine Path is unchanged. If there are parameters then the entire User Routine Path is replaced with the newly specified path.

Calling UserRoutinePath("") with a null string as a parameter resets the current namespace for routine access to the default namespace.

The namespace strings you specify can be either an explicit namespace or an implied namespace (a directory path or OpenVMS file specification preceded by two caret characters (^^)).

To understand UserRoutinePath, you need to keep the following in mind. When a process starts, it uses routines in the current namespace. After you issue $system.Process.UserRoutinePath(new), all subsequent routines come from new.

If you issue $system.Process.UserRoutinePath(new,second,third), all subsequent routines located in namespace new will come from new. If the system does not find a routine in new, the system looks for the routine in namespace second. If the system does not find the routine in second, the system looks for the routine in namespace third.

Note: Using routines in second is VERY slow! You should use second as an aid to program development, not as a normal running procedure.

To use UserRoutinePath as a development aid, make new your development area and use second as a storage area of routines that work. When you issue ZSAVE, the routine you save always goes into new, even if you loaded it from second. As you edit and file routines, they appear in new without affecting the library in second, and subsequent calls for the routines get the new version from new.

The method does not affect globals; the original namespace still defines access privileges for globals. Your process uses globals in the current namespace unless you make explicit or implicit references to globals in other namespaces. In other words, the routines come from primary (or from second or third), while the globals come from the process's current namespace.

This method does not affect system routines whose names begin with a per cent (%). For % routines see the SysRoutinePath method.

Return value -- the primary namespace for user routine access that was set before you called UserRoutinePath.

• classmethod ZDateNull(switch As %Boolean) as %Boolean
The ZDateNull class method performs two process-specific operations:

It specifies how the $ZDATE function behaves when it receives invalid input.

It specifies the default range of valid dates for $ZDATE. (This provides backward-compatibility with ISM.)

Setting the Behavior for Invalid Dates

An invalid date is either not a positive integer, or is not a value within the range of valid dates.

ZDateNull(0) causes $ZDATE to issue the error message <ILLEGAL VALUE> or <VALUE OUT OF RANGE> if you submit an invalid date. The behavior can be overridden by supplying an erropt parameter to the $ZDATE call.

ZDateNull(1) causes $ZDATE to return the null string if you submit an invalid date. This behavior is set for any $ZDATE function call, regardless of the number of parameters.

Setting the Range of Valid Dates

ZDateNull(0) sets the default range of valid dates to be the default. This range is from 0 through 2980013, inclusive, which corresponds to dates from 12/31/1840 through 12/31/9999. This range can be restricted by setting the $ZDATE mindate and maxdate parameters.

ZDateNull(1) sets the default range of valid dates for ISM compatibility. This range is from 1 through 94232, inclusive, which corresponds to dates from 01/01/1841 through 12/30/2098. This date range is set for any $ZDATE function call which has three or fewer parameters. If a $ZDATE function call has more than three parameters, the valid date range is taken either from the $ZDATE mindate and maxdate parameters (if specified) or from the date range established for the current locale.

Parameters

switch a boolean value that specifies $ZDATE behavior:
0 -- specifies InterSystems IRIS-style behavior. (0 is the usual default)
1 -- specifies ISM-style behavior.

Invoking ZDateNull() without specifying the switch parameter returns the current switch setting.

Return value -- the switch state prior to calling the ZDateNull method.



Copyright © 1997-2018 InterSystems Corporation, Cambridge, MA