gtpm2m2gMigration Guide: Program Update Tapes

Domain Name System (DNS) Support (APAR PJ27268)

The following section discusses the migration considerations for DNS support.

Prerequisite APARs

See the APEDIT for APAR PJ27268 for information about prerequisite APARs.

Functional Overview

Following is the DNS server support and the enhancements to DNS client support. You can use either or both options to:

Architecture

While TCP/IP applications refer to host systems by their Internet Protocol (IP) addresses, you will find it easier to use host names because host names are easier to remember than IP addresses and host names change much less frequently than IP addresses. To enable the use of host names in a network, the DNS translates host names to IP addresses. The DNS provides host name to IP address mapping through network server hosts called domain name servers.

Before DNS support, the TPF 4.1 system only supported the DNS client function, meaning the TPF 4.1 system could send DNS requests but could not process incoming DNS requests. In addition, every DNS client request made by the TPF 4.1 system was sent to an external DNS server for processing. DNS support adds DNS server support to the TPF 4.1 system and enhances the TPF DNS client performance by adding caching capability for information received from external DNS servers.

The DNS server function enables the TPF 4.1 system to process incoming DNS requests for host names of the TPF 4.1 system. The TPF DNS server works with the UDNS user exit to select the appropriate TPF local IP address for each DNS request that is received. This allows you to load balance TCP/IP connections in your loosely coupled complex. Having DNS requests for TPF host names processed by the TPF 4.1 system rather than external DNS servers ensures that an inactive IP address is never passed back in the DNS response, and it centralizes the load balancing logic in one place. Because the TPF DNS server only processes requests for host names of the TPF 4.1 system itself, DNS requests for host names external to the TPF 4.1 system will continue to be processed by external DNS servers.

When a gethostbyname() or gethostbyaddr() API function call is issued, the TPF 4.1 system takes on the role of a DNS client. The TPF 4.1 system now includes a pair of DNS client caches: one that maps external host names to their IP addresses, and the other that maps external IP addresses to their host name. When the TPF 4.1 system sends a DNS request to an external DNS server and the response comes back, the information is then placed in the cache if the response indicates that the information is allowed to be cached. Subsequent gethostbyname() or gethostbyaddr() calls with the same input will be able to retrieve the information locally from the TPF DNS client cache. By reducing the number of requests sent to the external DNS server, the performance of TPF socket client applications improves.

Operating Environment Requirements and Planning Information

To ensure that your TPF 4.1 system performs correctly with DNS support, you must establish the required operating environment. The following section describes hardware and software requirements specific to DNS support.

Operating Environment Requirements and Planning Information provides information about the minimum system configuration requirements that are necessary to operate the TPF 4.1 system. You may find it helpful to review that chapter along with the following information.

Hardware

There are no hardware requirements.

Software (Programming Requirements)

The following section contains information about software requirements.

Communication

The following section summarizes the communication changes.

Operating Environment for TCP/IP-Based Communication

To use the DNS server portion, TCP/IP native stack support must be installed in the TPF 4.1 system. To use the DNS client portion, TCP/IP native stack support or TCP/IP offload support must be installed. See TCP/IP Native Stack Support (APAR PJ26683) for more information about TCP/IP native stack support and Transmission Control Protocol/Internet Protocol (TCP/IP) Offload Support (APAR PJ21791) for more information about TCP/IP offload support.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

Table 804 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 804. Changes to Build Scripts for DNS Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CDNCBS DLL New Build script for DNS server sipcc() send processing.
CDNEBS DLM New Build script for /etc/hosts file processing.
CDNFBS DLM New Build script for /etc/host.txt file processing.
CDNIBS DLM New Build script for IPAST management processing.
CDNPBS DLM New Build script for DNS server sipcc() receive processing.
CDNQBS DLM New Build script for DNS client restart processing.
CDNRBS DLM New Build script for DNS restart processing.
CDNSBS DLM New Build script for DNS server processing.
COMXBS LLM Changed Updated to remove OCO comments from CGTHBA and CGTHBN library object files.
UDNSBS DLM New Build script for DNS server user exit UDNS.

Dynamic Load Module (DLM) Stubs

Table 805 summarizes changes to the dynamic load module (DLM) stubs. This information is presented in alphabetic order by the name of the DLM stub. See TPF Application Programming for more information about the DLM stubs.

Table 805. Changes to Dynamic Load Module (DLM) Stubs for DNS Support

DLM Stub New, Changed, or No Longer Supported?
UDNS CDNS

General Use C/C++ Language Header Files

Table 806 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 806. Changes to General Use C/C++ Language Header Files for DNS Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$ck2sn Changed No
nameser.h Changed No
netdb.h Changed No
socket Changed No

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

Table 807 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 807. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for DNS Support

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
i$pwbl.h Changed No
i$tcpc.h Changed No

Library Interface Scripts

There are no changes.

Library Members (Object Files)

Table 808 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 808. Changes to Library Members (Object Files) for DNS Support

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CGTHBA COMX Changed C Language Updated to save host IP address information in IDNSHOSTADDR DNS client cache.
CGTHBN COMX Changed C Language Updated to save host name information in IDNSHOSTNAME DNS client cache.
C536 COMX Changed C Language Updated to make sure the DNS server uses TCP/IP native stack support.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 809 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).

Notes:

  1. You must recompile or reassemble a member (object file) if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 809. Changes to Members (Object Files) for DNS Support

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CDNF CDNF New C++ Language Created to periodically refresh the core copy of the /etc/host.txt file used for DNS server processing.
CDNS CDNS New C++ Language Created to receive DNS address queries and send DNS responses.
CDNSCF CDNE New C++ Language Created to periodically refresh the core copy of the /etc/hosts file used for DNS client processing.
CDNSCR CDNQ New C++ Language Created to create IDNSHOSTADDR and IDNSHOSTNAME caches during system restart.
CDNSSC CDNC New C++ Language Created to Issue sipcc() functions to send IP address processor shared table (IPAST) information to other processors.
CDNSSI CDNI New C++ Language Created to add or delete IP address entries from the IPAST.
CDNSSP CDNP New C++ Language Created to receive a sipcc() message (from another processor in restart) to send IPAST information to the processor in restart.
CDNSSR CDNR New C++ Language Created to initialize the IPAST during system restart.
CINET4 CLTX Changed C Language Updated to save the server program name in the entry control block (ECB) work area.
CLTQ CLTN Changed Object - Only Updated to change the length of the recvfrom() source address buffer from 4 to 16.
CLTR CLTR Changed C Language Updated to issue the serrc_op_ext() function with the SERRC_EXIT argument and to abort system restart if the TCP/IP configuration table is not built.
UDNS UDNS New C++ Language The DNS server user exit.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

Table 810 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 810. Changes to Copy Members for DNS Support

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CT15 Control Program CCCTIN Not Applicable Changed Updated to create the IP address processor shared table (IPAST).
CTT1 Control Program CCTCP1 Not Applicable Changed Updated to set up the IPAST interface for CTX3.
CTT5 Control Program CCTCP1 Not Applicable Changed Updated to set up the IPAST interface for CTX3.
CTTA Control Program CCTCP1 Not Applicable Changed Updated to set up the IPAST interface for CTX3.
CTX0 Control Program CCTCP1 Not Applicable Changed Updated to set up the IPAST interface for CTX3.
CTX2 Control Program CCTCP1 Not Applicable Changed Updated to set up the IPAST interface for CTX3.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 811 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 811. Changes to Data Macros for DNS Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
CK2SN Changed No
DLTEC Changed No
IPWBL Changed No
ISTAK Changed No

General Macros

There are no changes.

Selected Equate Macros

Table 812 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 812. Changes to Selected Equate Macros for DNS Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZ1SE Changed No

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 813 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 813. Changes to SIP Skeleton and Internal Macros for DNS Support

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 814 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 814. Changes to SIP Stage II Macros for DNS Support

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

There are no changes.

System Macros (IBM Use Only)

Table 815 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 815. Changes to System Macros (IBM Use Only) for DNS Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFMDC Changed Yes, dump formatter programs ICDF and STPP.

Segments

Table 816 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 816. Changes to Segments for DNS Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CNAB Assembler Not Applicable Changed Updated to delete IP address entries from the IP address processor shared table (IPAST) when a processor is deactivated.
CTKT Assembler Not Applicable Changed Updated to issue the CREMC macro during system startup on the CDNF program to create the host name tables used by the DNS server and DNS client code.
CTS7 Assembler Not Applicable Changed Updated to process the new MSG_RTN_LOCAL_IP_ADDR flag for the recvfrom() socket API function.
CTSQ Assembler Not Applicable Changed Updated to start DNS client restart processing of the CDNQ DLM.
CTSR Assembler Not Applicable Changed Updated to start DNS server restart processing of the CDNR DLM.
CTSU Assembler Not Applicable Changed Updated to process the new MSG_RTN_LOCAL_IP_ADDR flag for the recvfrom() socket API function.
CTX3 Assembler Not Applicable Changed Updated to call CDNI when CDLC IP links are activated or deactivated.

System Equates

The following section summarizes system equate changes.

SYSEQ Tags

There are no changes.

User Exits

Control Program (CP) User Exits and ECB User Exits summarize the control program (CP) and ECB user exit changes. See TPF System Installation Support Reference for a complete description of all user exits.

Control Program (CP) User Exits

There are no changes.

ECB User Exits

This information is presented in alphabetic order by the name of the function.

Table 817. Changes to ECB User Exits for DNS Support

Function User Exit Activated In User Exit Program New, Changed, or No Longer Supported? Description of Change
Determine Internet protocol (IP) address CDNS UDNS New Created to determine which host and IP address to use for the DNS response.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

There are no changes.

Messages and System Errors

Table 818 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. See Messages (System Error and Offline) and Messages (Online) for a complete description of all messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 818. Changes to Messages and System Errors for DNS Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
009117 System Error New
009118 System Error New
009119 System Error New
009120 System Error New
DNSC0001E Online New
DNSC0002I Online New
DNSC0003E Online New
DNSC0004I Online New
DNSC0005E Online New
DNSC0006E Online New
DNSC0007E Online New
DNSC0008E Online New
DNSC0009E Online New
DNSC0010E Online New
DNSC0011I Online New
DNSS0001E Online New
DNSS0002E Online New
DNSS0003E Online New
DNSS0004I Online New
DNSS0005E Online New
DNSS0006E Online New
DNSS0007E Online New
DNSS0008E Online New
DNSS0009E Online New
DNSS0010E Online New
DNSS0011E Online New
DNSS0012E Online New
DNSS0013I Online New
DNSS0015E Online New
DNSS0016E Online New

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 819 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 819. Changes to TPF Publications for DNS Support

Publication Title Softcopy File Name Description of Change
TPF Library Guide GTPDOC0D Updated with definitions for new terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for DNS support.
TPF Migration Guide: Program Update Tapes GTPMG203 Updated with migration considerations for DNS support.
TPF Program Development Support Reference GTPPDR0C Updated with new dump labels.
TPF System Installation Support Reference GTPINR0D Updated with the UDNS user exit.
TPF Transmission Control Protocol/Internet Protocol GTPCLW09 Updated with information about server and client processing, and changes to application programming interface (API) functions.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

The recvfrom() API now supports a new TPF-unique flag called MSG_RTN_LOCAL_IP, which passes back the local (TPF) IP address and port associated with a User Datagram Protocol (UDP) message to the application. The rempte IP and port are still returned, along with the local IP and port, when the new flag is used. This new flag is only supported for sockets using TCP/IP native stack support, not for sockets using TCP/IP offload support.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Use the following procedure to add DNS support to your existing TPF 4.1 system.

  1. Install program update tape (PUT) 13.
  2. If you plan to use the DNS client cache portion of DNS support, install logical record cache and coupling facility (CF) cache support (APAR PJ27083) . You do not need coupling facility (CF) support to use the client cache. See Logical Record Cache and Coupling Facility (CF) Cache Support (APAR PJ27083) for more information.
  3. If you want to create the external host name file used by the DNS client portion of DNS support, create the host name file, /etc/hosts, which contains external host names and IP addresses. See TPF Transmission Control Protocol/Internet Protocol for more information about host names.
  4. If you are using the DNS server portion of DNS support, do the following:
    1. Be sure TCP/IP native stack support (APAR PJ26683) is installed on your TPF 4.1 system. See TCP/IP Native Stack Support (APAR PJ26683) for more information.
    2. Create the host name file, /etc/host.txt.
    3. Code the UDNS user exit if you do not want to use the default round-robin logic. See TPF System Installation Support Reference for more information about the UDNS user exit. See TPF Transmission Control Protocol/Internet Protocol for more information about coding the user exit.
  5. IPL the TPF 4.1 system and cycle to NORM state.
  6. If you are using the DNS client cache portion of DNS support, do the following:
    1. Determine the number of entries that will be in the IDNSHOSTADDR and IDNSHOSTNAME caches according to how many remote hosts you want to communicate with.
    2. Enter the ZCACH command to change the number of entries in either or both caches. See TPF Operations for more information about the ZCACH command.
    3. IPL the TPF 4.1 system.
  7. If you want to create the external host name file used by the DNS client portion, load the /etc/host.txt file to your TPF 4.1 system.
  8. If you are using the DNS server portion of DNS support, do the following:
    1. Load the /etc/host.txt file to your TPF 4.1 system.
    2. Enter from the basic subsystem (BSS): ZINET ADD S-DNS MODEL-NOWAIT PGM-CDNS PROT-UDP IP-ANY PORT-53 STATE-NORM to define the DNS server application to the Internet daemon (INETD). A specific IP address may be supplied for the IP parameter. See TPF Operations for more information about the ZINET ADD command.
    3. Enter the ZINET START command from the BSS to activate the server application from the INETD. See TPF Operations for more information about this command.

Fallback Scenarios

If the migration to DNS support is not successful, you will need to fall back to your previous network environment, correct the problem, and try the conversion again.

To Fallback from the DNS Server Portion of DNS Support

Enter the ZINET STOP command to stop the DNS server. See TPF Operations for more information about the ZINET STOP command.

To Fallback From the DNS Client Cache Portion of DNS Support

Enter the ZCACH command to set the size of the IDNSHOSTNAME and IDNSHOSTADDR caches to zero, and IPL the TPF 4.1 system. See TPF Operations for more information about the ZCACH command.