Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%SYSTEM.INetInfo

class %SYSTEM.INetInfo extends %SYSTEM.Help

The %SYSTEM.INetInfo class provides an interface for Internet address manipulation.
These interfaces support both IPV6 and IPV4 internet addresses.

Method Inventory

Methods

classmethod AddrToHostName(Addr As %String) as %String
Find a host name for an Internet address.

Parameters:
Addr - An Internet address in binary form. The length is 4 for IPV4, 16 for IPV6.
The address should be in Network order.

Return:
This method returns a host name string, it returns a null string if no host name is associated with the Internet address.
classmethod AddrType(Addr As %String) as %Integer
Find the type of an address text.

Parameters:
Addr - A text string could be a hostname, an IPV4 dotted address or an IPV6 colon-hex text address.

Return:
This method returns 0 for hostname, 1 for IPV4 address type or 2 for IPV6 address type.
classmethod BinaryAddrToText(Addr As %String) as %String
Convert a binary Internet address to a readable text string.

Parameters:
Addr - An Internet address in binary form. The length is 4 for IPV4, 16 for IPV6.
The address should be in Network order.

Return:
This method returns a 'dotted' decimal string if the input address is IPV4 address (worked as inet_ntoa()).
It returns colon-hex address string if the input address is IPV6 address.
If the address could not be translated, a null string is returned.
classmethod CheckAddressExist(IPAddr As %String) as %Integer
CheckAddressExist:

Description

Check if the specific IP address exists in the network or not.
Returns 1 if the IP address exists in the network, otherwise return 0.

classmethod CheckInterfaceExist(Interface As %String, MatchExact As %Integer = 0) as %Integer
CheckInterfaceExist:

Description

Check if the specific network interface exists in the system or not.
Returns 1 if the network interface exists in the system, otherwise return 0.

classmethod CheckSubnetMatch(Interface As %String, IPAddr As %String) as %Integer
CheckSubnetMatch:

Description

Check to see if the subnets for the IP for a given physical interface match a requested virtual IP.
Returns 1 if the subnets match, otherwise return 0.

classmethod Connected() as %Boolean
The Connected() class method checks if the current device is a TCP device has been disconnected from the remote site. It returns 0 if the TCP device is disconnected. It returns 1 if the TCP device is still connected. An error <FUNCT> is generated if the current device is not a TCP device.

You can also have the system poll asynchronously for a TCP disconnect by using the D mode option for the OPEN or USE command.

classmethod DisableIPV6(System As %Integer = 0) as %Integer
Disable IPV6 process or system wide.

Parameters:
System - Disable IPV6 for process or system wide, 1 for system wide, 0 for process wide (default).

Return:
Return whether the IPV6 was enabled or not, 1 - was enabled, 0 - was disabled.
classmethod EnableIPV6(System As %Integer = 0) as %Integer
Enable IPV6 process or system wide.

Parameters:
System - Enable IPV6 for process or system wide, 1 for system wide, 0 for process wide (default).

Return:
Return whether the IPV6 was enabled or not, 1 - was enabled, 0 - was disabled.
classmethod EthernetAddress(flag As %Integer, Name As %String) as %String
EthernetAddress(flag[,name]) is a class method that determines Ethernet address.

Description

You can return a string containing ethernet address information by issuing a call to the following class method.

EthernetAddress(0) returns the address of the primary ethernet device. This primary ethernet device is the first ethernet device found on the device names list with a valid ethernet address. Any ethernet device can be designated the primary ethernet device.

EthernetAddress(0,name) returns the address of any attached ethernet device specified by name. On OpenVMS systems, this is the physical port address of the ethernet device, not the hardware address. The ethernet address is returned as a string of 12 characters that represent the 48-bit ethernet address. The name is not case sensitive. The maximum length of a device names list is platform-dependent, but the name of an individual device cannot be more than 15 characters in length. An invalid name value results in a error.

EthernetAddress(0) returns a null string, rather than an ethernet address if:

The primary ethernet device is not present in the device names list. EthernetAddress(0,name) returns a null string if the named device is not present in the device names list, or has no corresponding ethernet address.

On Windows systems, the InterSystems Packet Driver is not installed.

On IBM AIX(r) systems, the DLPI (Data Link Provider Interface) packages are not installed.

The ethernet adapters are protected against access by non-root users, and the process invoking EthernetAddress(0) is not the root user.

EthernetAddress(1) returns the current list of attached ethernet device names, delimited by $CHAR(1). The first name in this list is the primary ethernet device.

EthernetAddress(2) returns the current list of ethernet device names, delimited by commas. This feature is not available on Windows systems.

EthernetAddress(2,name) replaces the current ethernet device names list with the list specified in name; it then returns the ethernet device names list prior to the replacement. This feature is not available on Windows systems.

Parameters

flag -- The switch that specifies the information that EthernetAddress is to return. Valid values are:

0 Returns the address of an attached ethernet device. When name is specified, it returns the address of the named device. When name is not specified, it returns the primary ethernet device.

1 Returns a list of the ethernet device names actually present on the system. This is a subset of the list returned by flag= 2. Listed names are separated by the $CHAR(1) character.

2 Returns the current list of ethernet device names, as set by system startup or by a subsequent invocation of EthernetAddress(2,name). Listed names are separated by commas. This flag value is not available on Windows systems.

name Optional -- Ethernet device name(s). Valid values are:

When flag = 0 name is the name of a specific ethernet device. EthernetAddress(0,name) returns the address of the named device.

When flag= 2 name is an ethernet device names list, enclosed in quotes with individual device names separated by commas. A name list specified in EthernetAddress(2,name) cannot contain control characters. The ethernet device names cannot be changed on Windows systems.

classmethod GetInterfacesInfo(Interface As %String = "") as %String
Get interfaces information configured in the system.
Parameters:
Interface - Null string will return information of all interfaces otherwise it returns the information of the specified interface.

Return:
Each interface is separated by $c(0) character. Within each interface it contains interface name and IP addresses separated by $c(1) character.
The first field separated by $c(1) is interface name and rest fields of them are the IP addresses configured on this interface.
classmethod GetListOfConfiguredInterfaces(InterfaceNamesOnly As %Boolean = 0, VIP As %String = "") as %List
Get interfaces information configured in the system excluding loopback interface.
Parameters:
InterfaceNamesOnly - If set it will return only interface name otherwise return interface name and IP address.
VIP - If this is non-null string it will return only interfaces with matching subnet of the VIP.

Return:
For InterfaceNamesOnly is set, it returns all the interface names in $LIST() format, e.g. $LB(InterfaceName1,InterfaceName2,...)
If it is not set it returns all interfaces in a nested $LIST() format, e.g. $LB(Interface1,Interface2,...)
Each interface is also a $LIST() containing interface name and IP addresses, e.g. $LB(InterfaceName,IPv4,IPv6). Please note that the sequence of IPv4 and IPv6 might be reversed, you need to check whether it is IPv4 or not by $Length(IP,":"), if it is > 2 then it is IPv6 otherwise it is IPv4. And there can be more than one IPV4 or IPV6 addresses in the interfaces.
classmethod GetServiceByName(Name As %String, Proto As %String = "", Family As %Integer = 0) as %List
Get port number, protocol name and IP Family from a service name.

Parameters:
Name - The service name string to be translated.
Proto - The protocol of service to be returned. If this parameter is omitted the default value is "". The value could be:
  • "": return services for both TCP and UDP protocols.
  • "tcp": return service for TCP protocol.
  • "udp": return service for UDP protocol.
Family - The family of the service to be returned. If this parameter is omitted the default value is 0. The value could be:
  • 0: depends on value of $SYSTEM.INetInfo.IsIPV6Enabled(), if IPV6 is NOT enabled IPV4 service is returned, otherwise it returns services for both IPV4 and IPV6.
  • 1: Only return IPV4 service, if no IPV4 service then return null string as failure.
  • 2: Only return IPV6 service, if no IPV6 service then return null string as failure.
Return:
Returns a List, its element is port number, protocol name and family type separated by "," (e.g. 23,tcp,IPV4).
The port number returned is in Host order.
Returns null string if the service name could not be resolved.
classmethod GetServiceByPort(Port As %Integer, Family As %Integer = 0) as %String
Get a service name from a port number.

Parameters:
Port - The port number to be translated. This port number is in Host order.

Family - The family of the service to be returned. If this parameter is omitted the default value is 0. The value could be:
  • 0: depends on value of $SYSTEM.INetInfo.IsIPV6Enabled(), if IPV6 is NOT enabled IPV4 service is returned, otherwise it returns services for IPV6.
  • 1: Only return IPV4 service, if no IPV4 service then return null string as failure.
  • 2: Only return IPV6 service, if no IPV6 service then return null string as failure.
Return:
Returns a service name string.
Returns null string if the service name could not be found.
classmethod HostNameToAddr(HostName As %String, Family As %Integer = 0, Format As %Integer = 0) as %String
Get one IP address from a host name.

Parameters:
HostName - The host name string to be translated.
Family - The family of the IP address to be returned. If this argument is omitted the default value is 0. The value could be:
  • 0: depends on value of $SYSTEM.INetInfo.IsIPV6Enabled(), if IPV6 is NOT enabled IPV4 address is returned, otherwise it returns whatever the system supports.
  • 1: Always return IPV4 address, if no IPV4 address then return null string as failure.
  • 2: Always return IPV6 address, if no IPV6 address then return null string as failure.
Format - The format of address to be returned. If this argument is omitted the default value is 0. The value could be:
  • 0: in text format, 'dotted' decimal string for IPV4, colon-hex address string for IPV6.
  • 1: in binary format, 4 character length for IPV4, 16 characters for IPV6.
Return:
Returns the primary IP address of the specified host name. It could be in binary or text format depends on the Format parameter. For binary format the IP address is in Network order.
If the host name could not be resolved a null string is returned.
classmethod HostNameToAddrMulti(HostName As %String, Family As %Integer = 0, Format As %Integer = 0) as %List
Get all IP addresses from a host name.

Parameters:
HostName - The host name string to be translated.
Family - The family of the IP address to be returned. If this argument is omitted the default value is 0. The value could be:
  • 0: depends on value of $SYSTEM.INetInfo.IsIPV6Enabled(), if IPV6 is NOT enabled IPV4 address is returned, otherwise it returns whatever the system supports.
  • 1: Always return IPV4 address, if no IPV4 address then return null string as failure.
  • 2: Always return IPV6 address, if no IPV6 address then return null string as failure.
Format - The format of address to be returned. If this argument is omitted the default value is 0. The value could be:
  • 0: in text format, 'dotted' decimal string for IPV4, colon-hex address string for IPV6.
  • 1: in binary format, 4 character length for IPV4, 16 characters for IPV6.
Return:
Returns all the IP addresses of the specified host name in a List. Each IP address in the List could be in binary or text format depends on the Format parameter. For binary format the IP address is in Network order.
If the host name could not be resolved a null string is returned.
classmethod HostToNetLong(Addr As %Integer) as %Integer
Convert a 4-byte unsigned integer from Host order to Network order (htonl()). This is used to convert the binary IPV4 address.

Parameters:
Port - A 4-byte unsigned integer as a binary IPV4 address in Host order.

Return:
Return a A 4-byte unsigned integer as a binary IPV4 address in Network order.
classmethod HostToNetShort(Port As %Integer) as %Integer
Convert a 2-byte unsigned integer from Host order to Network order (htons()). This is used to convert the Port number.

Parameters:
Port - A 2-byte unsigned integer as a port number in Host order.

Return:
Return a 2-byte unsigned integer as a port number in Network order.
classmethod IsIPV6Enabled(System As %Integer = 0) as %String
Check if IPV6 is enabled.

Parameters:
System - Check for process or system wide, 1 for system wide, 0 for process wide (default).
Return:
Return whether the IPV6 is enabled or not, 1 - is enabled, 0 - is disabled.
classmethod LocalHostName() as %String
Return the local host name. (gethostname()).
classmethod NetToHostLong(Addr As %Integer) as %Integer
Convert a 4-byte unsigned integer from Network order to Host order (htonl()). This is used to convert the binary IPV4 address.

Parameters:
Port - A 4-byte unsigned integer as a binary IPV4 address in Network order.

Return:
Return a 4-byte unsigned integer as a binary IPV4 address in Host order.
classmethod NetToHostShort(Port As %Integer) as %Integer
Convert a 2-byte unsigned integer from Network order to Host order (ntohs()). This is used to convert the Port number.

Parameters:
Port - A 2-byte unsigned integer as a port number in Network order.

Return:
Return a 2-byte unsigned integer as a port number in Host order.
classmethod OSsupportsIPV6() as %Integer
$SYSTEM.InetInfo.OSsupportsIPV6() provides a way to determine if IPV6 is supported by the operating system.

Return:
Returns 1 if the operating system supports IPV6.
Returns 0 if the operating system does not support IPV6.
classmethod TCPName() as %String
TCPName is a class method called by a child process to retrieve the TCP device name assigned by the parent process.
classmethod TCPStats(Code As %Integer) as %Integer
TCPStats(Code) returns statistics from the current TCP device.

Description

TCPStats(2) returns the number of bytes that have been read from the current TCP device.

TCPStats(3) returns the number of bytes that have been read from the current TCP device and clears the counter.

TCPStats(4) returns the number of bytes that have been written to the current TCP device.

TCPStats(5) returns the number of bytes that have been written to the current TCP device and clears the counter.

classmethod TextAddrToBinary(Addr As %String) as %String
Convert a readable Internet address text string to a binary Internet address string.

Parameters:
Addr - Internet address, a string with address in text form. It is a 'dotted' decimal string for IPV4, colon-hex address string for IPV6.

Return:
This method (worked as inet_addr()) returns a binary IP address in Network order, the length is 4 for IPV4, 16 for IPV6.
If the address could not be translated, a null string is returned.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab