Add TCP/IP Host Table Entry (ADDTCPHTE)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Add TCP/IP Host Table Entry (ADDTCPHTE) command adds an internet address and its associated host names along with an optional text description field to the local host table. A host table entry consists of one internet address, up to 65 host names, and a text description field.

See also the following host table commands:

Change TCP/IP Host Table Entry (CHGTCPHTE) command changes one or more host names or the text description field.
Copy TCP/IP Host Table (CPYTCPHT) command copies the contents of the local host table to a physical file member.
Merge TCP/IP Host Table (MRGTCPHT) command merges host names, internet addresses, and text comment entries from a physical file member into the local host table. A replace option is also provided that allows the entire local host table to be replaced by the host table entries in a user specified physical file member.
Rename TCP/IP Host Table Entry (RNMTCPHTE) command renames the internet address of a host table entry to another internet address.
Remove TCP/IP Host Table Entry (RMVTCPHTE) command removes an entire entry from the local host table.

If an internet address already exists in the host table that matches the internet address specified in the command, an escape message is sent to the user and the duplicate internet address is not added.

If a remote name server is being used by your system for resolving a host name or an internet address, the choice to first search the remote name server or the local host table depends on the setting of the host name search priority (HOSTSCHPTY) parameter on the Change TCP/IP Domain (CHGTCPDMN) command. To change the host name search priority use the CHGTCPDMN command or use the Configure TCP/IP (CFGTCP) command and select option 12.

The TCP/IP host table is shipped with two loopback entries -- one for IPv4 and one for IPv6. The IPv4 entry has an internet address of 127.0.0.1 and two host names: LOOPBACK and LOCALHOST. The LOOPBACK host name can only be associated with an internet address that has a first-byte value equal to 127. The IPv6 entry has an internet address of ::1 and two host names: IPV6-LOOPBACK and IPV6-LOCALHOST. The IPV6-LOOPBACK host name can only be associated with the IPv6 internet address ::1. The IPV6-LOCALHOST host name can only be associated with an IPv6 internet address.

Related APPC over TCP/IP Information

APPC over TCP/IP (AnyNet) uses the host name to map location names to internet addresses. The host name must be in the form:

location.netid.SNA.IBM.COM

Where location is the remote location the program is opening to, and netid is the network identifier for this connection. SNA.IBM.COM is the qualifier that designates this as the APPC over TCP/IP domain.

Location names support characters that cannot be present in host names (for example: $ (dollar), @ (at sign), and # (number sign)). Therefore, the APPC application can open only to locations that fulfill the TCP/IP host name syntax. This limits location names used for APPC over TCP/IP to the characters A-Z (uppercase and lowercase) and 0-9.

Restrictions:

You must have input/output system configuration (*IOSYSCFG) special authority to run this command.

Top

Parameters

Keyword	Description	Choices	Notes
INTNETADR	Internet address	Character value	Required, Positional 1
HOSTNAME	Host names	Values (up to 65 repetitions): Element list	Required, Positional 2
HOSTNAME	Element 1: Name	Character value	Required, Positional 2
TEXT	Text 'description'	Character value, *BLANK	Optional

Top

Internet address (INTNETADR)

Specifies the internet address that the host names and text descriptions are associated with.

An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address.

An IPv6 internet address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

An IPv4-mapped IPv6 address may be specified. An IPv4-mapped IPv6 address is specified in the form ::FFFF:nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255.

If the internet address is entered from a command line, the address must be enclosed in apostrophes.

This is a required parameter.

character-value: Specify the internet address.

Top

Host names (HOSTNAME)

Specifies the host names corresponding to the internet address. The host name can be either the short form or the full domain version of the name. A common practice is to define one short name that is unique within your local network and to also define the full domain version of the host name that is unique within the Internet.

A host name is a text string that has 1 to 255 characters. Host names consist of one or more labels separated by periods. Each label can contain up to 63 characters. The first character of each label must be an alphabetical character or a digit. The last character of each label must be an alphabetical character, a digit, or a period. The following characters are allowed in host names:

Alphabetical characters A through Z
Digits 0 through 9
Underscore (_)
Minus sign (-)
Period (.). Periods are allowed only when they separate host name labels or as the last character in the host name (refer to RFC 1034). A host name cannot have two consecutive periods.

Note: These characters are part of the Syntactic/Invariant Character Set (character set number 640).

Other domain name and host name conventions include the following:

Uppercase and lowercase characters are allowed, but no significance is attached to the case. The host name (HOSTNAME) may be converted to uppercase depending on the combination of characters and digits. If the HOSTNAME is enclosed in apostrophes ('), the case is maintained as entered.
The host name returned when searching the host table for an internet address is the first host name associated with the internet address. For example, if the address 9.130.38.187 is defined in the host table with names ROCHESTER, JOHN, and RCHAS100, the name ROCHESTER would be returned. The other two host names would not be used in this type of search. However, these host names would be used when searching the host table to find the internet address associated with the names JOHN and RCHAS100.
Try to limit your domain name labels to 12 characters. Shorter labels are easier to remember.
It is a common practice to use hierarchical names that allow predictable extensions for change and growth. Domain names normally reflect the delegation of authority or hierarchy used to assign them. For example, the name SYS1.MFG.ABC.COM can be broken down into the following:

COM

All commercial networks.

ABC.COM

All systems in the ABC company's commercial network.

MFG.ABC.COM

All manufacturing systems in the ABC company's commercial network.

SYS1.MFG.ABC.COM

A host named SYS1 in the manufacturing area of the company's commercial network.

The COM designation is one of several domain names used by convention when connecting to the Internet. Some of the other domain names that follow this convention are:

AERO

Air-transport industry

BIZ

Businesses

CAT

Catalan linguistic and cultural community

COM

Commercial organizations

COOP

Cooperative associations

EDU

Educational institutions

GOV

United States of America government institutions

INFO

Global information

INT

Organizations established by international treaties between governments

JOBS

Human resource managers

MIL

United States of America military groups

MOBI

Consumers and providers of mobile products and services

MUSEUM

Museums

NAME

Individuals

NET

Major networks support centers

PRO

Credentialed professionals and related entities

TRAVEL

Travel industry

ORG

Organizations other than those above

ARPA

Temporary ARPANET domain

Country or Region Code

Countries or regions other than the USA

This is a required parameter.

You can specify 65 values for this parameter.

character-value

Specify a host name to be associated with the specified internet address. When running APPC over TCP/IP, the host name is in the form:

location.netid.SNA.IBM.COM

The default if a host name is not specified is blanks. An IP address cannot be a host name.

Top

Text 'description' (TEXT)

Specifies text that briefly describes the host table entry.

*BLANK: No text is specified.
character-value: Specify no more than 64 characters of text, enclosed in apostrophes.

Top

Examples

Example 1: Adding a Short Host Name

ADDTCPHTE   INTNETADR('132.28.71.5')  HOSTNAME(ETHERNETHOST)
            TEXT('ETHERNETHOST on Ethernet subnet')

This command associates the host name ETHERNETHOST with the internet address of 132.28.71.5. The text 'ETHTERNETHOST on Ethernet subnet' is saved as the text description for this host table entry.

Example 2: Adding Five Host Names

ADDTCPHTE   INTNETADR('1234::5678')
            HOSTNAME((SYSTEM1.SALES.ABC.COM)
                     ('system1.sales.abc')
                     ('System1.Distribution.Abc.Com')
                     ('System1.Marketing.Abc.Com')
                     ('System1.Marketing.Abc'))
            TEXT('Entry verified by J. Jones')

This command associates the host names SYSTEM1.SALES.ABC.COM, SYSTEM1.SALES.ABC, SYSTEM1.DISTRIBUTION.ABC.COM, SYSTEM1.MARKETING.ABC.COM, and SYSTEM1.MARKETING.ABC with the internet address of 1234::5678. Because host names are case insensitive, a match is found on host name SYSTEM1.SALES.ABC.COM, system1.sales.abc, System1.Distribution.Abc.Com, System1.Marketing.Abc.Com, or System1.Marketing.Abc. The text 'Entry verified by J. Jones' is saved as the text description for this host table entry.

Top

Error messages

*ESCAPE Messages

TCP1901: Internet address &2 not valid.
TCP1902: Internet address &1 not valid.
TCP1903: Specified host name not valid.
TCP1904: Duplicate internet address &2 found in host table.
TCP1908: Internet address &1 not valid.
TCP1910: LOOPBACK internet address &2 not valid.
TCP1929: Host table not available.
TCP8050: *IOSYSCFG authority required to use &1.
TCP9999: Internal system error in program &1.

Top