Inter-User Communications Vehicle (IUCV) Sockets

Table Of Contents

Inter-User Communications Vehicle (IUCV) Sockets

Overview

IUCV Socket Compatibility

Initializing the IUCV Sockets

Configuration Information

Configuring the TCPIP.DATA Data Set

Configuring the IJTCFGxx Member

Converting From IBM TCP/IP

Converting From API/Link

Starting and Stopping IUCV Address Space

Limitations and Restrictions

Additional References

Inter-User Communications Vehicle (IUCV) Sockets

---

This chapter provides descriptions of the Inter-User Communications Vehicle (IUCF) sockets for Cisco IOS for S/390. It includes these sections:

•Overview

Describes the IUCV sockets for Cisco IOS for S/390.

•IUCV Socket Compatibility

Describes IUCV socket compatibility with applications written for IBM's TCP/IP API that will run over the Cisco IOS for S/390 stack.

•Configuration Information

Provides configuration information for Cisco IOS for S/390 for IUCV.

•Converting From IBM TCP/IP

Describes how to convert code from IBM TCP/IP programs.

•Converting From API/Link

Describes converting code from API/Link programs.

•Starting and Stopping IUCV Address Space

Describes control of the IUCV address space.

•Limitations and Restrictions

Describes the limitations of the Cisco IOS for S/390 IUCV implementation.

•Additional References

Lists references for more information about IUCV.

Overview

With Cisco IOS for S/390 runtime support for the Inter-User Communication Vehicle (IUCV) sockets, applications written for the IBM TCP/IP IUCV API can run over the Cisco IOS for S/390 product. Supported applications include those linked with the IBM IUCV-based C socket library.

Cisco IOS for S/390 IUCV sockets replace the corresponding IBM TCP/IP IUCV transport address space and TCP/IP facilities, and let existing applications—those linked with the IBM C socket library as well as those written using the IBM macro sockets (EZASMI) or IUCV APIs—execute transparently.

The IUCV sockets are implemented via both a started task (RUNIUCV) that provides the IUCV transport facilities to user programs, and via a new Cisco IOS for S/390 transport provider.

The Cisco IOS for S/390 IUCV product provides the same interface points as the IBM TCP/IP product, so you need not make any application changes in order to use it. However, you must use a Domain Name Server (DNS) to resolve the name to the IP address, or explicitly use an IP address (in dotted decimal format), as table lookup is not currently supported.

The IUCV started task must be initialized before any Cisco IOS for S/390 task is initiated and it must remain active while any user or Cisco IOS for S/390 tasks are running on the MVS system. The IUCV task should be started as part of the system initialization command list (COMMNDxx) and not be shut down during normal operations.

Upon startup, the IUCV task defines and activates the VMCF subsystem linkage and Program Call (PC) services that client programs use.

After the IUCV task has been initialized, Cisco IOS for S/390 can be started. As part of its initialization, Cisco IOS for S/390 performs the IUCV transport handshake and initializes the transport provider interface. No additional operator commands to Cisco IOS for S/390 are necessary to start the IUCV sockets.

---

Note   All users of IUCV must be inactive before the subsystem is stopped or started; otherwise, unpredictable results can occur.Applications using IUCV have the VMCF subsystem name hard-coded (as VMCF) in most cases. If you choose to change the name of the VMCF subsystem and not use this default, you must also change all occurrences of VMCF to the chosen subsystem name.

---

---

Caution   

When the IUCV task is started, it supersedes any existing environment that had been established for the named subsystem. The previous environment is restored when the IUCV task is stopped.

---

IUCV Socket Compatibility

Support for IUCV sockets in Cisco IOS for S/390 allows applications written for IBM's TCP/IP API to run over the Cisco IOS for S/390 stack.

In addition, support is provided for the following service routines:

•SNMPGPCN

•IUCVMULT

•IUCVMAST

•IUCVSTRT

•EZASOK03

These routines are documented in the IBM TCP/IP V3R1 for MVS: Application Programming Interface Reference, and in IBM APAR PNSG110.

---

Note   Cisco IOS for S/390 IUCV sockets require that you use the IUCVMULT routine that is included with the product. If you replace this file with another version, unpredictable results can occur.

---

Initializing the IUCV Sockets

Once the IUCV the startup procedures have been customized, the IUCV sockets can be initialized to provide IUCV support over Cisco IOS for S/390.

Any applications that use IUCV must be stopped prior to starting the IUCV task, since it will dynamically reassign the VMCF subsystem ID. The pre-existing VMCF environment is saved and restored at RUNIUCV termination, but no application notification is performed.

---

Note   Applications that are left running at startup may encounter a variety of unpredictable failures, ranging from S0D6 ABENDs to indefinite waits.

---

If possible, bring down the existing IBM TCP/IP address space and IUCV address space. IBM maintenance APAR PN87700 (available as PTF UN97100 for TCP/IP V3R1 on the MVS 9511 cumulative tape) will permit the VMCF subsystem to be stopped and restarted via operator commands; this fix is recommended if your site will be testing or using both products alternately.

Make sure that the same IJTCFGxx member of the Cisco IOS for S/390 PARM library is in use for both the RUNIUCV task and the Cisco IOS for S/390 task (typically RUNTCP). The same software key will enable both facilities. The VMCFNAME parameter on the IFSPARM statement must match between IUCV and Cisco IOS for S/390.

---

Note   By default, applications use a VMCF name of VMCF. Do not alter this default subsystem name unless instructed to do so.

---

•Start the IUCV task (s runiucv).

Monitor the JES output log for the messages T00IF002I (Address Space Initialization Complete) and T02IU001I (IUCV Initialization Successfully Completed). These are interspersed with other messages issued by the task.

•Start the Cisco IOS for S/390 task (s runtcp.tcpip).

Monitor the JES output log for the T00IF002I (Address Space Initialization Complete), T01SO001I (Sockets API Initialization Successfully Completed) and T01IU001I (Connection to IUCV Established). These are interspersed with other messages issued by the task.

Applications that utilize IUCV sockets can now be started.

Configuration Information

For IUCV, you must configure the TCPIP.DATA data set, the IJTCFGxx member of the PARM data set, and the TCPCFGxx member of the PARM data set.

Configuring the TCPIP.DATA Data Set

Applications using the IUCV-based C sockets runtime library must either configure the hlq.TCPIP.DATA (hlq refers to the TSO user ID) data set or insert the SYSTCPD DD statement into the application. The format of this data set and definitions of the various parameters contained within are defined in the IBM manual IBM TCP/IP V3R1 FOR MVS: Customization and Administration Guide, SC31-7134-01.

---

Note   The Domain Name Server (DNS) must either be configured with a name server or you must use an IP address (in dotted decimal format). Name resolution via table lookup is not currently supported.

---

The required configuration parameters are:

•TCPIPJOBNAME jobname

Where jobname specifies the stepname/jobname of the Cisco IOS for S/390 task.

---

Note   The stepname (tcpip) given to the Cisco IOS for S/390 started task (for example, runtcp.tcpip) becomes the TCPIPJOBNAME that applications use to connect to the Cisco IOS for S/390 started task via IUCV. If no stepname is given, the jobname (or task name) is used.

---

•DOMAINORIGIN origin

Where origin specifies the site domain origin that is appended to a host name to form the fully-qualified domain name for a host.

Example

DOMAINORIGIN MYCOMPANY.COM

•NSINTERADDR internet_IP_addr

Where internet_IP_addr specifies the IP address of the Domain Name Server (DNS) host for the site. Multiple name servers can be specified, but the default 14.0.0.0 is not supported for the IUCV sockets.

Optional configuration parameters are:

•SOCKBULKMODE

•SOCKDEBUG

•SOCKDEBUGBULKPERF0

•SOCKNOTESTSTOR

Any other configuration parameters will be ignored.

Configuring the IJTCFGxx Member

You must edit the IJTCFGxx member of the PARM data set. Read the Cisco IOS for S/390 Customization Guide for information about the VMCFNAME and PROMPT parameters.

The pool IPTH, defined in the IJTCFGxx member, is used by IUCV sockets. Read the Cisco IOS for S/390 Customization Guide for information about this pool.

POOLDEF NAME(IPTH) INITIAL(64) MINIMUM(64) EXPAND(64)

The parameters shown will allocate memory for IUCV connection control blocks.

Converting From IBM TCP/IP

If you are currently running IBM TCP/IP, you must do the following:

•Shut down IBM TCP/IP.

•Start up Cisco IOS for S/390 IUCV with the default VMCF subsystem entry (Cisco IOS for S/390 IUCV will de-activate IBM VMCF and save the information used by it).

•Start up Cisco IOS for S/390.

The startup procedures are described in the following sections.

Converting From API/Link

If you are currently running API/Link, you must do the following:

•Shut down API/Link.

•Run the IBMRESET job from the API/Link source library (this job resets the VMCF subsystem entry).

•Start up Cisco IOS for S/390 IUCV with the default VMCF subsystem entry (Cisco IOS for S/390 IUCV will de-activate IBM VMCF and save the information used by it).

•Start up Cisco IOS for S/390.

The startup procedures are described in the following sections.

Starting and Stopping IUCV Address Space

The IUCV address space executes a single task group, the IJT task group. IUCV can be started and stopped only by starting or stopping the IUCV address space. Use the procedure RUNIUCV supplied in the Cisco IOS for S/390 CNTL library.

s runiucv

f runiucv,p clear

Syntax Description

runiucv

Name of the IUCV address space.

Usage Guidelines

Monitor the JES output log for the messages IFS001I (Address Space Initialization Complete) and T02100I (IUCV Initialization Successfully Completed). These are interspersed with other messages issued by the task.

---

Note   The IUCV address space should not be shut down during normal operations.

---

---

Caution   

If the IUCV address space is terminated via the FORCE operator command, the pre-existing VMCF environment (if any) is not restored.

---

Limitations and Restrictions

The following limitations and restrictions have been identified for the Cisco IOS for S/390 IUCV sockets.

•For IUCV-based C sockets applications, Domain Name Resolution (DNR) must be provided by a network Domain Name Server (DNS) configured in the hlq.TCPIP.DATA statement NSINTGRADDR. Resolution via table lookup (due to the DNS being unreachable or because RESOLVE_VIA_LOOKUP was specified at compile time) is not supported.

•Due to Domain Name Resolution conflicts, the following C socket calls are not supported:

sethostent()	gethostent()	endhostent()
setnetent()	getnetent()	endnetent()
setprotoent()	getprotoent()	endprotoent()
setservent()	getservent()	endservent()

---

Note   These calls return 0 (R15=0) when they fail.

---

•Output for the sock_debug() call is different than that returned for IBM TCP/IP for MVS calls.

•RPC and XDR calls are not supported with this feature.

•Bulk mode is not currently supported.

Additional References

For more information about socket programming in the IBM TCP/IP environment, refer to the following documents.

IBM TCP/IP for MVS: Application Programming Interface Reference, Version 3 Release 1; IBM order number SC31-7187

IBM TCP/IP for MVS: Programmers Reference, Version 3 Release 1; IBM order number SC31-7135

IBM TCP/IP for MVS: Customization and Administration Guide, Version 3 Release 1; IBM order number SC31-7134

VM/ESA CP Programming Services for 370, IBM order number SC24-5435

VM/XA CP Programming Services, IBM order number SC23-0370

VM/SP System Facilities for Programming, IBM order number SC24-5288