%SYSTEM.Util
Class %SYSTEM.Util Extends Help [ Abstract, System = 4 ]
The %SYSTEM.Util class provides an interface for managing utility functions.
You can use it via the special $SYSTEM object:
You can call help to get a list of all entrypoints:
Do $SYSTEM.Util.Help()
Methods
InstallDirectory
ClassMethod InstallDirectory() As %String
Returns the location of where IRIS is installed.
ManagerDirectory
ClassMethod ManagerDirectory() As %String
Returns the location of the manager directory, where the IRISSYS database (mgr) is located.
BinaryDirectory
ClassMethod BinaryDirectory() As %String
Returns the location of the binaries directory (bin), where executables, DLL's, shared libraries, scripts, etc are kept.
DataDirectory
ClassMethod DataDirectory() As %String
Returns the location of the data directory, where the CPF file is located.
JavaHomeDirectory
ClassMethod JavaHomeDirectory() As %String
Returns the location of the Java Home directory.
This method returns the location of the Java Home directory on your system. The return value has been normalized, and is suitable for passing to $zf(-1) or $zf(-2).
The location of the Java Home directory which is returned is determined in the following order:
- The directory location returned by the configuration parameter JavaHome in the cache.cpf file.
- The directory location returned by the environment variable "JAVA_HOME".
- If none of the above, a null string.
Example:
s JavaHome=$SYSTEM.Util.JavaHomeDirectory()
JavaExe
ClassMethod JavaExe() As %String
Returns the path name of the Java executable, which can be used to build a command line.
This method returns the pathname of the Java executable, which can be used to build a command line on your system. The return value has been normalized, and is suitable for passing to $zf(-1) or $zf(-2).
The method uses the return value from the JavaHomeDirectory() method, appends the subdirectory "bin" to it, and then adds the Java executable name to the end. If the JavaHomeDirectory() method returns "", then it is assumed that the Java executable location is in the process path, and the return value of the method is simply the Java executable name.
Notes:
This method does not test for the existence of the Java executable. It assumes it is located in the "bin" directory if JavaHomeDirectory() returns a non-null value, otherwise it must be in the path of the process executing the method.
Example:
s JavaExe=$SYSTEM.Util.JavaExe()
s Status=$zf(-1,JavaExe_" -version")
GetEnviron
ClassMethod GetEnviron(VariableName As %String) As %String
Returns the value of an environment variable.
SetBatch
ClassMethod SetBatch(flag As %Integer, pid As %Integer = "") As %Integer [ Deprecated ]
Sets or clears batch mode for the calling process, or the one identified by pid
Processes that will access large portions of a database may be set into batch mode to limit their impact on other (non-batch mode) processes running on the system. In particular, batch mode processes are prevented from overwhelming the database cache with the database blocks that they read or modify.
Parameters
flag : 1 sets batch mode; 0 clears batch mode
pid : (optional) target pid; if null or omitted target is the calling process
Return Value
Returns the old value of the batch flag, or -1 if error
CreateGUID
ClassMethod CreateGUID(version As %Integer) As %String
Creates and returns a 128 bit globally unique identifier (GUID), also known as universally unique identifier (UUID).
Parameters
version -- an optional argument specifying the UUID version used to generate an identifier. Currently supports version 4 (random based) and version 1 (mac based). All output characters will be in lower-case if a version number argument is passed in, according to RFC4122.
Values for version:
default: Generate a v1 UUID for non-Windows or a v4 UUID for Windows. For non-Windows platforms, if the config section of the cpf has UUIDv1RandomMac=1, generate the UUID as in "1r", else generate the UUID as in "1o".
All the output characters are in upper case for code compatibility reasons.
"1o": Generate a v1 UUID. Ignore the cpf UUIDv1RandomMac setting. "o" is for original. Note the quotes.
The original behavior of IRIS is to try and detect one of your ethernet connections and use the mac from that. If the detection doesn't happen (rare), a combined value of several things is used for the mac address.
"1r": Generate a v1 UUID. Ignore the cpf UUIDv1RandomMac setting. "r" is for random. Note the quotes.
The mac is generated randomly as per RFC4122 section 4.5. See below for why you may need this.
1: Generate a v1 UUID. If the config section of the cpf has UUIDv1RandomMac=1, generate the mac as in "1r", else generate the mac as in "1o".
4: Generate a v4 UUID.
Why should you set UUIDv1RandomMac=1 in the [config] section of the cpf?
A large part of UUID v1 uniqueness depends on having a mac address that is unique in the particular domain where you wish things to be unique.
The domain could be one IRIS instance, or a multi-instance IRIS host, or the whole world.
You have to consider which domain you need, to see if the overall UUID v1 uniqueness is enough. In the situation where you have multiple IRIS instances on a host (i.e. they have the same mac), and wish the UUID to be unique for that host, you will be protected by less than 14 bits (only the UUID v1 clock seq field and not the mac) of randomness when creating UUIDs at the same time in 2 instances on your host.
This could definitely cause non uniqueness during a large deployment.
In the situation where you wish your UUIDs to be unique across all your deployments in the world and you stand up virtual instances where the mac address is the same, you may have only 14 random bits of protection against other instances creating UUIDs at the same time. Note the IP address might be the same, but maybe the mac is different.
If you set UUIDv1RandomMac=1 in the [config] section of the cpf, you always get 14+47=61 bits of random protection, which should be enough even for a large deployment.
Return value -- a 128 bit GUID/UUID string. It may be upper or lower case.
CreateDecimalGUID
ClassMethod CreateDecimalGUID() As %String
Creates and returns the decimal representation of a globally unique identifier (CreateGUID() without any arguments).
A GUID is a 16 byte (128 bit) globally unique identifier.
UUIDv1RandomMacMode
ClassMethod UUIDv1RandomMacMode(random As %Integer) As %String [ Internal ]
Used by stu.mac
Sets UUID v1 random mac mode in global memory (it applies to all UUID v1 created)
NumberOfCPUs
ClassMethod NumberOfCPUs() As %Integer
Returns the number of virtual CPUs (also known as logical CPUs or threads) on the system.
For more details see %SYSTEM.CPU.
JobPrio
ClassMethod JobPrio(jprio As %Integer) As %Integer
Sets the system-wide job priority delta to the specified number.
The priority of any jobbed process on the system = priority of parent + system job priority.
The new jobprio value is returned
Note: changing priority is almost never needed and can compromise system stability
GetPrio
ClassMethod GetPrio(pid As %Integer = "") As %Integer
Returns the priority of the current process or another process.
SetPrio
ClassMethod SetPrio(delta As %Integer, pid As %Integer = "") As %String
Adjusts the priority of the current process or another process up or down by delta amount.
The new priority is returned.
Note: changing process priority is almost never needed and can compromise system stability
GlobalBuffers
ClassMethod GlobalBuffers() As %List
Returns a list of the number of global buffers for each buffer size.
GetSwitch
ClassMethod GetSwitch(SwitchNumber As %Integer) As %Integer
Returns the value of one system switch, or the values of all switches.
When the SwitchNumber is not specified, GetSwitch returns one value containing the state of all system switches.
Each system switch is represented by a bit in this value, with switch 0 as the least significant bit and switch 31 as the most significant.
For example:
Switch 0 -> 1
Switch 1 -> 2
Switch 2 -> 4
...
Switch 31 -> 0x80000000
When the SwitchNumber is specified (0 to 31), GetSwitch returns the state of the specific switch represented by SwitchNumber.
The return value is 1 if this switch is set, or 0 if it is cleared.
For switch 10 and 11, it also returns the PID of the job that set this switch in the '1,PID' format.
Switch Definitions -
Switches 0 to 7 are not used by the system and are reserved for the user.
Switch 8 (0x100) : Inhibits responding to network request for DCP, DDP and DTM. It does not block ECP traffic.
Switch 9 (0x200) : Inhibits new network signons, this only apply for DCP.
Switch 10(0x400) : Inhibits all global and lock access except by the job setting this switch.
Switch 11(0x800) : Inhibits all global and lock access except by the job setting this switch. This overrides switch 10 and is reserved for use by the system (should only be set by the system).
Switch 12(0x1000) : Inhibits new users/JOB commands to signon the system.
Switch 13(0x2000) : Inhibits sets, kills, and zsaves.
Switch 14(0x4000) : Inhibits access to globals and routines.
Switch 15(0x8000) : Allow network references from peers, even if switch 10,13, or 14 would normally prevent the access.
Switch 16(0x10000) : Used in ^SHUTDOWN only.
Switch 17(0x20000) : Used internally by system to skip waiting in journal synch.
Switch 18(0x40000) : Used internally by system to disable pausing processes in gblkrd() if the queue for a block gets too long.
Switch 19(0x80000) : Inhibits TSTART.
SetSwitch
ClassMethod SetSwitch(SwitchNumber As %Integer, SwitchValue As %Integer) As %Integer
Sets the value of a system switch.
When one parameter is specified, SetSwitch(SwitchValue) sets the value of all system switches to SwitchValue.
It returns the original value of all switches.
This is not recommended to be used by users.
When two parameters are specified, SetSwitch(SwitchNumber,SwitchValue) sets the value of the specific switch SwitchNumber to SwitchValue.
It returns the original switch value.
To set switch 10 or (11 in cluster), if the switch was set then the SetSwitch won't do anything and the original value with the owner PID is returned in '1,PID' format..
To clear switch 10 or (11 in cluster), if the switch was cleared or was set by different process then the SetSwitch won't do anything and the original value is returned.
See GetSwitch for a definition of the switches.
CheckSwitch
ClassMethod CheckSwitch(SwitchNumber As %Integer) As %Integer
Check if this job could be blocked by the specific switch represented by 'SwitchNumber'.
Returns 1 if the job could pass this check (not blocked), returns 0 if this job will be blocked.
For switch 10 and 11, if the job could not pass this test it also returns the PID of the job who set this switch in the '0,PID' format.
RoutineBufferSize
ClassMethod RoutineBufferSize() As %Integer
Returns the largest routine buffer size that been configured.
RoutineBuffers
ClassMethod RoutineBuffers(Arg As %Integer) As %String
Returns information about the routine buffers that have been allocated.
The return value is a comma-delimited string with a value for each possible buffer size. The pieces correspond to buffer sizes 2K,4K,8K,16K,32K,64K.
If Arg is 0 or is omitted, the values are the amount of memory, in MegaBytes, allocated for each buffer size.
If Arg is 1, the values are the number of buffers allocated for each buffer size.
Compress
ClassMethod Compress(OriginalString As %String, Type As %String) As %String
Returns the compressed form of a given string.
When Type is specified, it is the compress algorithm used to compress the data. Its value can be "zlib", "zstd" or "lz4". If Type is not specified then the "zlib" compression algorithm is used. A compressed string is a compressed data block with a customized wrapper. Use Decompress to decompress it.
Decompress
ClassMethod Decompress(CompressedString As %String) As %String
Returns the original form of a compressed string (see Compress).
CompressionNameToID
ClassMethod CompressionNameToID(EngineName As %String) As %Integer
Converts a compression engine name to an internal id #. ID #'s are zero based. Returns -1 if the name is not a known engine. Passing "" for the name argument returns highest compression engine id. Names are lowercased for comparison purposes.
CompressionIDToName
ClassMethod CompressionIDToName(EngineID As %Integer) As %String
Converts an internal compression engine id to an engine name. ID #'s range from zero up to the # of engines-1. ID numbers which are out of range will return a null string. Engine Names are lowercase.
GetCompressionEngineFlags
ClassMethod GetCompressionEngineFlags(EngineID As %Integer) As %String
Returns a string representing the flags set for the specified compression engine ID. The 1st character of each name is in uppercase and every name including the last one is followed by a comma
CompressionNameList
ClassMethod CompressionNameList(ByRef EngineNames As %String) As %Integer
Returns an array of the valid Compression Engine Names currently supported which are not marked hidden. The count of the # of engines is returned as the value of the method. The value returned from the method call is the number of compression engines in the array. The format of the array is each engine's name is used as a subscript with the value set to "".
IsDST
ClassMethod IsDST(TimeStamp As %String) As %Integer
Determines whether $HOROLOG includes a daylight saving time adjustment.
TimeStamp is a UTC time stamp value (same format as $ZTIMESTAMP). If TimeStamp is not specified, the current time is used with $HOROLOG adjusted by the $ZTIMEZONE special variable.
The return value reports whether the corresponding $HOROLOG time is adjusted by an additional DST hour.
Changes to $ZTIMEZONE will change the value of $HOROLOG but the time zone rules do not change. The time zone rules are always those used by the operating system on which the process is running. The time zone rules of the process will be applied to the local time.
The UTC time stamp is converted to a time_t value (taking into account adjustments to $ztimezone) which is then used as input to call the C Programming Language standard library routine localtime(). The tm_isdst element of the returned tm struct is examined to determine if the daylight savings time is in effect.
Return Values:
0 - DST is not in effect.
1 - DST is in effect.
-1 - It cannot be determined if DST is in effect.
UTCtoLocalWithZTIMEZONE
ClassMethod UTCtoLocalWithZTIMEZONE(TimeStamp As %String) As %String
Converts UTC time to Local time.
Parameter
TimeStamp : A string representing a UTC time in the same format as that returned by $ZTIMESTAMP.
Return Value
A string representing the corresponding Local time in the same format as that returned by $HOROLOG.
Note: This method only supports dates between January 1, 1970 and January 18, 2038. Dates outside this range will give an
Note: $ZTIMEZONE Warning
This function is unusual in that it adjusts the Local time by any changes made to the $ZTIMEZONE special variable. Use of the $ZTIMEZONE variable is limited to a few special situations. $ZTIMEZONE affects the value returned by $HOROLOG but most other date/time features and functions (including $ZDATETIME and $ZDATETIMEH) ignore $ZTIMEZONE changes. Even though changing $ZTIMEZONE will change the value of returned by $HOROLOG, the time zone rules do not change. The time zone rules are always those used by the operating system on which the process is running. The $ZTIMEZONE special variable will probably become a legacy feature in future versions of the system. If possible, applications should avoid changing $ZTIMEZONE and should use $ZDATETIMEH(timestamp,-3) to convert UTC time to Local time.
LocalWithZTIMEZONEtoUTC
ClassMethod LocalWithZTIMEZONEtoUTC(h As %String) As %String
Converts Local time to UTC time.
Parameter
h : A string representing Local time in the same format as that returned by $HOROLOG.
Return Value
A string representing the corresponding UTC time in the same format as that returned by $ZTIMESTAMP.
Note: This method only supports dates between December 31, 1969 and January 18, 2038. Dates outside this range will give an
Note: $ZTIMEZONE Warning
This method is unusual in that it adjusts the Local time by any changes made to the $ZTIMEZONE special variable. Use of the $ZTIMEZONE variable is limited to a few special situations. $ZTIMEZONE affects the value returned by $HOROLOG but most other date/time features and functions (including $ZDATETIME and $ZDATETIMEH) ignore $ZTIMEZONE changes. Even though changing $ZTIMEZONE will change the value returned by $HOROLOG, the time zone rules do not change. The time zone rules are always those used by the operating system on which the process is running. The $ZTIMEZONE special variable will probably become a legacy feature in future versions of the system. If possible, applications should avoid changing $ZTIMEZONE and should use $ZDATETIME(h,-3) to convert Local time to UTC time.
Collation
ClassMethod Collation(String As %String, flag As %Integer, len As %Integer) As %String
Performs collation conversion.
Parameters
String : An expression specifying a string or number to be converted to a specified collation type.
flag : An integer code used to specify the desired collation type. Valid values are 0 through 9.
len : Optional -- The truncation length in characters, specified as an integer. Truncation is performed on the collation-converted string. This option can only be used with flag values of 7, 8, or 9. A decimal len value is truncated to its integer part. A negative or nonnumeric len value is treated as 0.
Description
Collation applies the collation type specified in flag to string. The following flag values are supported:
0 - EXACT : Returns string unchanged. Does not convert NULLs. Corresponds to the SQL %EXACT function.
1 - SPACE : Appends a blank to beginning of string.
2 - MVR : Returns its argument converted to the MultiValue collation sequence. It is used when a string contains both numeric and non-numeric characters. It divides the expression string into substrings, each substring containing either all numeric or all non-numeric characters. The numeric substrings are sorted in signed numeric order. The non-numeric substrings are sorted in case-sensitive ASCII collation sequence.
3 - PLUS : Converts numerics and numeric strings to canonical numbers. A nonnumeric string is returned as 0.
4 - MINUS : Converts numerics and numeric strings to canonical numbers and prepends a minus sign. A nonnumeric string is returned as 0.
5 - UPPER : Converts letters to uppercase. Corresponds to the SQL %UPPER function.
6 - ALPHAUP : Removes leading, trailing, and embedded blanks. Removes all punctuation characters, except commas (,) and question marks (?). Converts letters to uppercase. Corresponds to the SQL %ALPHAUP function.
7 - SQLUPPER : Removes trailing blanks. Converts letters to uppercase. Appends a blank to beginning of string. Corresponds to the SQL %SQLUPPER function.
8 - SQLSTRING : Removes trailing blanks. Appends a blank to beginning of string. Corresponds to the SQL %SQLSTRING function.
9 - STRING : Removes leading, trailing, and embedded blanks. Removes all punctuation characters, except commas (,). Converts letters to uppercase. Appends a blank to beginning of string. Corresponds to the SQL %STRING function.
Several of these collation conversions append a blank to the string. This forces numerics and the empty string to be collated as strings.
Numerics are converted to canonical form: leading and trailing zeros are removed, as is a trailing decimal point. Multiple plus and minus signs are resolved; if the resulting sign is a plus sign, it is removed.
The MINUS collation type appends a minus sign to the supplied sign before canonical resolution. Thus the MINUS collation of a negative number is a positive number. PLUS and MINUS resolve mixed numeric strings (such as "7dwarves") by truncating the string at the first nonnumeric character. PLUS and MINUS resolve nonnumeric strings by assigning them a value of 0.
RevCollation
ClassMethod RevCollation(String As %String, flag As %Integer) As %String
Performs reverse collation conversion.
Parameters
String : An expression specifying a collated string to be converted back to POSSIBLE original value.
flag : An integer code used to specify the desired collation type. Valid value is 2.
Description
RevCollation applies the collation type specified in flag to string. The following flag values are supported:
2 - MVR : Returns its argument converted from the MultiValue collation sequence. It is used when a string contains both numeric and non-numeric characters. It divides the expression string into substrings, each substring containing either all numeric or all non-numeric characters. The numeric substrings are sorted in signed numeric order. The non-numeric substrings are sorted in case-sensitive ASCII collation sequence. The result can differ from the original due to sign and leading zero suppression applied during the conversion to MVR collation.
PurgeSYSLOG
ClassMethod PurgeSYSLOG() As %Numeric
Purges existing error report records from SYSLOG.
GetOSErrorText
ClassMethod GetOSErrorText(ErrorCode As %Integer) As %String [ CodeMode = expression ]
Returns the text string corresponding to the given OS error code.
GetOSVersionInfo
ClassMethod GetOSVersionInfo() As %String
Returns MajorVersion.MinorVersion.BuildNumber on Windows.
Returns an unimplemented error on Unix or VMS.
GetPhysicalMemory
ClassMethod GetPhysicalMemory() As %Integer
Returns total physical memory on Windows.
Returns an unimplemented error on Unix.
GetPrivateVariables
ClassMethod GetPrivateVariables(ProcEntry As %String, ByRef OutArray) As %Integer
Get a list of all the private variables referenced in a procedure.
The procedure name is given by the entry reference label^routine.
The variable names are returned as subscripts of the OutArray argument.
The return value of the method is the number of variables in the output array.
Negative return values indicate an error with the ProcEntry:
-1 if the routine is not found
-2 if the label is not found
-3 if the label is not a procedure
-4 if a syntax error
GetSessionId
ClassMethod GetSessionId(arg As %Integer) As %Numeric
Returns the session Id on Windows.
If arg = 0 or no argument, returns the physical console Session Id or 0xffffffff if there is no session attached to the physical console. The physical console is the monitor, keyboard, and mouse.
If arg = 1, returns the session Id of the current process. On error, returns -GetLastError().
Returns an unimplemented error on Unix or VMS.
HexToDecimal
ClassMethod HexToDecimal(hex As %String) As %String
Converts a hexadecimal string to a decimal string.
DecimalToHex
ClassMethod DecimalToHex(decimal As %String) As %String
Converts a decimal string to a hexadecimal string.
mpadd
ClassMethod mpadd(x, y) [ Internal, Private ]
Add two multiple-precision integers, represented as a list of base 1,000,000,000 integers, least significant first
mpaddx
ClassMethod mpaddx(x, y) [ Internal, Private ]
Add two multiple-precision hex integers, represented as a list of base 0x1000000 integers, least significant first
mp2dec
ClassMethod mp2dec(x) [ Internal, Private ]
Convert multiple-precision integer to decimal string
mp2hex
ClassMethod mp2hex(x) [ Internal, Private ]
Convert multiple-precision hex integer to hex string
CoreCountForNoFreezeDBERR
ClassMethod CoreCountForNoFreezeDBERR(newvalue As %Integer) As %Integer
Configures the collection of core files from
Parameters
newvalue: An optional parameter which specifies the number of core files to capture from this type of problem. Negative values are treated as zero. If omitted the value is not changed.
Returns: The current value, before applying the optional new value.
GetFrameStackSize
ClassMethod GetFrameStackSize() As %Integer
Returns the configured frame stack size, in bytes.
This is the size that will be used for any new processes that are created.
SetFrameStackSize
ClassMethod SetFrameStackSize(size As %Integer) As %Integer
Sets the configured frame stack size, in bytes, for new processes.
If size is 0, the system default size is set.
Returns the previous configured value.
ValidateRoutineBuffers
ClassMethod ValidateRoutineBuffers(flag As %Integer, numbuf As %Integer)
Performs validation of the routine buffers in memory
Parameters
flag : 1 = stop if an error is found. Default is 0.
numbuf : For a big-endian system, specifies the number of buffers to allocate as a work area. Routines larger than this will not be checked. Default is 8. Little-endian systems do not allocate a work area.
Return value
The return value is a $LIST with at least one element.
The first element is the number of buffers (routines) that were checked.
If errors are found, there will be one list element for each error.
If numbuf is specified, there will be one element with the size of the largest routine found. If this value is larger than numbuf on a big-endian system then at least one routine was skipped.
Each error is itself a $LIST with these elements:
The buffer number.
The routine name.
The error code.
Additional information specific to the error code. Error code 1 is a crc error. The additional information is the expected crc value and the actual value.
CheckName
ClassMethod CheckName(Select As %String, Data As %String, Case As %Boolean = 0) As %Boolean [ Internal, SqlProc ]
Used by Config and Security classes.
'Case' determines if this is case sensitive (not case sensitive by default)
CheckNameContains
ClassMethod CheckNameContains(Select As %String, Data As %String) As %Boolean [ Internal, SqlProc ]
Used by Config and Security classes.
CheckAuditJSONString
ClassMethod CheckAuditJSONString(SearchString As %String, EventDataString As %String) As %Boolean [ Internal, SqlProc ]
This method checks if the JSON string generated for an audit entry contains a particular search string.
The string we are looking for is the SearchString input.
The EventDataString input should contain the Event Data for the audit entry,
which will subsequently contain the JSON String that we are to search through, if there is one present.
DatabaseLatency
ClassMethod DatabaseLatency(Directory As %String = "") As %Decimal
Returns a value that describes the health of the mounted database residing in the specified directory. If the Directory argument is missing or is the empty string then the returned value describes the health of the database that holds the data for the current default namespace.
If the specified directory does not exist or does not contain a mounted database then the
If the directory does exist and the directory contains a mounted database then the method will return a value representing the number of milliseconds required to access block 1 of the database file.
NOTE: On many lightly loaded platforms a call on this method will often return a very small value. On most systems there is high speed RAM memory built into the disk drive hardware in order to speed up disk operations. This is followed by some disk cache blocks in the system memory managed by the operating system. The existence of these levels of cache memory means that reading block 1 of a database file will often be done by copying data from one of these levels of cache memory rather than reading data from the spinning platters of the disk drive.
NOTE: Certain database files may not support this method. For example, specifying a database directory which is cluster mounted may signal the
ZBOOLEAN
ClassMethod ZBOOLEAN(a, b) As %Boolean [ Internal, SqlProc ]
Used by Config and Security classes.
"RoundToCFloat
ClassMethod "RoundToCFloat()"() [ Internal ]
Takes the input, coerces it to a $double, casts it to C float, and returns as a $double. Used to sanity check situations where IRIS converts $double data to float internally.