Chapter 13: Running EZASOKET Applications on Enterprise Server

Enterprise Server with Mainframe Transaction Option can run CICS and JCL applications that use the EZASOKET APIs. Applications use the features provided by these APIs to establish and manage connections, and to exchange data, over TCP/IP networks.

This chapter describes the support of EZASOKET in Enterprise Server. It does not provide a guide to EZASOKET programming. It contains the following sections:

• Introduction
• Prerequisites
• Supplied transactions and programs
• Items omitted from this release
• Notes on individual functions
• Configuring and managing EZASOKET support for CICS applications

For instructions on developing CICS and JCL applications to run on Enterprise Server, please see your Mainframe Transaction Option Developer's Guide.

Introduction

Micro Focus EZASOKET is designed to emulate, as closely as possible, the IBM implementation documented in SC31-8518-01, "OS/390 SecureWay Communications Server: IP CICS Sockets Guide Version 2 Release 8" (1999). It also supports some, though not all, of the features introduced in the z/OS implementation documented in SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5" (2004).

However, there are some differences. Micro Focus EZASOKET makes use of the local platform's native TCP/IP support. Due to differences between TCP/IP implementations, there are some circumstances in which Micro Focus EZASOKET does not behave identically to the IBM implementation. These differences are documented in the section Notes on individual functions.

Prerequisites

You must have Enterprise Server with Mainframe Transaction Option.

You must ensure that your enterprise server has Mainframe Transaction Option enabled.

How to

You must specify a suitable SIT for your enterprise server.

How to

To run CICS applications on your enterprise server:

• You must ensure that you have a TN3270 listener defined

  How to

• You may also need to define the CICS search paths

  How to

To use JCL with an enterprise server, you must:

• Enable JES for the server

  How to

• Define batch initiators and printers for the server

  How to

You may also need to define the JES program paths in Enterprise Server Administration.

Supplied Transactions and Programs

This section lists the programs and transactions supplied with Enterprise Server.

Standard Transactions and Programs

For more information on these items, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

• DFHEZA: group containing the EZASOKET definitions for CICS
• EZAC: transaction to define/alter/display/delete the CICS/Sockets listeners
• EZAO: transaction to start/stop CICS/Sockets listeners
• EZACIC20: program used in PLTPI/PLTSD or as a linked program to start/stop CICS/Sockets listeners
• EZACICSE: (default security exit, ASCII) can be replaced with your own exit
• EZACIC02: (default listener IPv4) can be replaced by your own listener
• EZACIC04: EBCDIC to ASCII translation program
• EZACIC05: ASCII to EBCDIC translation program
• EZACIC14: EBCDIC to ASCII translation program using a fixed table
• EZACIC15: ASCII to EBCDIC translation program using a fixed table
• EZACIC06: Translates bit-masks into character arrays and character arrays into bit-masks
• EZACIC08: Interprets the variable length address list in the HOSTENT structure returned by GETHOSTBYNAME or GETHOSTBYADDR.
• EZACIC25: Domain Name Server (DNS) cache module emulation

Test Transactions

• EZPI: transaction to test CICS/Sockets listener CSKL is defined properly
• EZPO: transaction used by EZPI to test CICS/Sockets is defined properly

Demonstration Programs

• EZAPING: Client demo program
• EZAPONG: Server demo program started by EZAPING

Items Omitted from this Release

The features not available this release are:

• IPv6 support
• raw sockets
• multicasting
• full support for Out-Of-Band (OOB) data

The following APIs are not available:

• FREEADDRINFO
• GETADDRINFO
• GETNAMEINFO
• INITAPIX
• READV
• RECVMSG
• SENDMSG
• WRITEV

The EZACIC09 utility program (which is used with GETADDRINFO) is not included in this release.

The CICS Domain Name System Cache is not included in this implementation. However, the API for it (utility program EZACIC25) is included, so you do not need to change application programs that use the DNS Cache.

WLM (Work Load Manager) registration for listeners is not supported.

Notes on Individual Functions

GETHOSTBYADDR

Where a hostname cannot be resolved, the function returns a RETCODE of -1 and null pointer for HOSTENT. This is in line with the behaviour of versions of IBM EZASOKET that were tested. However, the IBM documentation states that, if the hostname cannot be resolved, the function will return a HOSTENT structure containing the error code. The behaviour of this function may change in future releases. We recommend that application programs rely on the RETCODE value to determine whether the call succeeded, and only inspect the HOSTENT structure if RETCODE is 0.

The GETHOSTBYADDR function is not thread-safe.

Because the native name resolution functions used by Micro Focus are not thread-safe, there is a very small possibility of a race condition occurring and of the function returning incorrect data. However, this is significantly less likely than errors elsewhere in the name resolution system, such as a failing DNS server.

GETHOSTBYNAME

See GETHOSTBYADDR above.

GETSOCKNAME

The IBM documentation states that if GETSOCKNAME is passed a socket that does not have a local address, GETSOCKNAME will return successfully (RETCODE = 0), with the FAMILY field of the NAME parameter set to 2 and the other fields set to 0. The Micro Focus implementation may return an error in this case.

GETSOCKOPT

Only the following operations are supported:

• SO_ACCEPTCONN
• SO_BROADCAST
• SO_DEBUG
• SO_ERROR
• SO_KEEPALIVE
• SO_LINGER
• SO_RCVBUF
• SO_REUSEADDR
• SO_SNDBUF
• SO_TYPE
• TCP_NODELAY

GIVESOCKET

The CLIENT parameter is ignored. That is, this version does not support restricting which tasks can take a socket.

Cross-region GIVESOCKET is not supported.

INITAPI

The IDENT and SUBTASK parameters are ignored.

No task may have more than 4096 sockets.

IOCTL

Only the FIONBIO and FIONREAD operations are supported.

SELECT

The reporting of exception conditions, tested for by use of the ESNDMSK parameter, differs between platforms. This is due to differences between TCP/IP implementations on those platforms.

Where a socket specified with the ESNDMSK parameter has been the subject of a GIVESOCKET, but has not yet been the subject of a TAKESOCKET, SELECT will continue to poll the socket until the TAKESOCKET occurs. In addition, SELECT cannot test sockets which are in this "given" state for normal I/O events.

SETSOCKOPT

Only the following operations are supported:

• SO_BROADCAST
• SO_DEBUG
• SO_KEEPALIVE
• SO_LINGER
• SO_RCVBUF
• SO_REUSEADDR
• SO_SNDBUF
• TCP_NODELAY

SOCKET

The value of the PROTO parameter passed by the caller is ignored.

Only STREAM and DGRAM sockets are supported.

TAKESOCKET

Only the TASK field of the CLIENT parameter is used. Other fields are ignored.

See GIVESOCKET above for more information on the limitations of GIVESOCKET and TAKESOCKET in this release.

Security Exit

The CICS EZASOKET Security Exit should be compiled with directive charset(ASCII) as all the parameters are expected to be passed in ASCII and returned in ASCII.

Configuring and Managing EZASOKET Support for CICS Applications

This assumes that you have already configured your Enterprise Server to run CICS applications as detailed in the chapter CICS Walkthrough in your Mainframe Transaction Option Developer's Guide. You also need to ensure that you have updated your Resource Definition Files. See the section Updating Existing Resource Definitions in the chapter Configuring Enterprise Server/MTO of your Micro Focus Server Extending CICS and IMS Applications Guide.

Enabling EZASOKET Support in Enterprise Server

1. Connect to Enterprise Server Administration.

   How to

2. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you using as your CICS region, and click Edit in the left hand column.
3. Click Properties > MTO.
4. Check EZASOKET support.
5. Click OK.
6. If the enterprise server is started, please stop it.

   How to

7. Restart the server.

   How to

Adding DFHEZA Group to your CICS Startup List

1. On the Home page of Enterprise Server Administration, click Details in the Current Status column for your enterprise server.
2. Click ES Monitor & Control.
3. In the Resources panel, which is about half way down on the left, expand the drop-down list and select by Group.

   The buttons in the Resources panel change to indicate the options for viewing and managing resources by group.

4. Click StartUp in the Resources panel.
5. Click Details for your startup list.

   This displays the contents of your startup list.

6. Type DFHEZA in the first empty field.
7. Click Apply.

Restarting the Enterprise Server

To make the enterprise server pick up the configuration changes you just made, you have to stop it and restart it.

1. Stop the enterprise server.

   How to

2. Restart the enterprise server.

   How to

Understanding EZASOKET Configuration

The EZASOKET configuration file (EZACONFG) contains details of CICS regions (that is, enterprise servers capable of running CICS applications) and the CICS listeners within those regions. The file can be shared by multiple enterprise servers. The location of the file used by your enterprise server is governed by the File Path configuration setting for the server.

For each CICS region that supports EZASOKET and is controlled by the configuration file, there is an associated object (referred to as a CICS object) in the configuration file. The object is identified by the APPLID of the CICS region. There is also a listener object for each listener defined for a CICS region.

The first task you will perform is to use the EZAC transaction to define a CICS object in the configuration file for your CICS region/enterprise server. If the configuration file does not exist, EZAC will create it.

Using the Configuration Transaction (EZAC)

The EZAC transaction enables you to add, delete, or modify items in the configuration file while your CICS region is running. The following table lists and describes the functions supported by the EZAC transaction.

Figure 13-1: Initial EZAC screen

Enter the command you want to execute followed by the type of object. For creating a CICS object for your CICS region, you type:

EZAC DEF CICS or EZAC,DEF,CICS or EZAC,DEFINE,CICS or EZAC DEF and then select CICS on the screen.

Figure 13-2: EZAC, Define, CICS screen

Enter the name of the CICS APPLID for which you are defining configuration information. In this case, the APPLID is the name of your enterprise server. The field defaults to this value.

Figure 13-3: Application parameters screen

Specify the parameters you require for EZASOKET support in your CICS region. For more information, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

A CICS region will typically have one or more listeners. Each listener may be an instance of the supplied listener or a user-written listener. Define a CICS listener for your region using: EZAC DEF LIST or EZAC DEFINE LISTENER or EZAC,DEF,LIST or EZAC,DEFINE,LISTENER as shown in the following screenshots:

Figure 13-4: Listener screen

The following screen allows you to define the characteristics of your listener

Figure 13-5: Listener characteristics screen

For more information on this topic, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

Starting and Stopping the EZASOKET Interface Automatically

You can enable automatic startup/shutdown of the EZASOKET interface by placing the EZACIC20 module in the appropriate Program List Table (PLT). Listeners that have been defined as IMMEDIATE=YES will then start automatically when the CICS region is started.

1. On the Home page of Enterprise Server Administration, click Details in the Current Status column for your enterprise server.
2. Click ES Monitor & Control.
3. In the Resources panel, which is about half way down on the left, expand the drop-down list and select by Group.

   The buttons in the Resources panel change to indicate the options viewing and managing resources by group.

4. Click SIT in the Resources panel.
5. Click Details for your SIT table.
6. Locate the Program Lists section.
7. Enter the names you want to use for the Post Initialization and the Shut Down lists. For example:

   
   
   Figure 13-6: Post initialization

8. Click Apply.

   You now create the program lists as described in the steps below.

9. In the Resources panel, expand the drop-down list and select by Type.

   The buttons in the Resources panel change to indicate the options for viewing and managing resources by type.

10. Click PLT in the Resources panel.

    The screen shows a list of CICS defined PLTs. At the bottom of the list is a set of buttons for creating new entries.

11. Click PLT in the New section of the list.
12. In Name, enter the name of your Post Initialization list.
13. Click Grp to expand the drop-down list and select the group you want to use. This group must be defined in your Startup list.
14. Enter a description in Description.
15. In the row labelled 01:
    • In the first field, enter EZACIC20.
    • From the drop-down list, choose Run once.

    For example:
    
    Figure 13-7: Select group

16. Click Add to save the new list.
17. Click PLT in the Resources panel.
18. Click PLT in the New section of the list.
19. In Name, enter the name of your Shut Down list.
20. Click Grp to expand the drop-down list and select the group you want to use. This group must be defined in your Startup list.
21. Enter a description in Description.
22. In the row labelled 01:
    • In the first field, enter EZACIC20.
    • From the drop-down list, choose Run once.
23. Click Add to save the new list.

Starting/Stopping the EZASOKET Interface and Listeners Manually

You can start the EZASOKET interface manually by using the EZAO transaction. This transaction has four functions:

• Interface Startup

  Starts the interface in a CICS region and starts all listeners that are identified for immediate start.

  Note: The EZAO transaction must be running on the CICS region where you want to start the EZASOKET interface. You cannot start an EZASOKET interface from a different CICS.

• Interface Shutdown

  Stops the interface in a CICS region.

• Listener Startup

  Starts a listener in a CICS region.

• Listener Shutdown

  Stops a listener in a CICS region.

You can type EZAO and select the action you require as shown below:

Figure 13-8: EZAO screen

and then select the object that you want to act upon:

Figure 13-9: EZAO, Start

Alternatively, you can enter EZAO START|STOP CICS|LISTENER and then respond to the screen prompts as shown in the following examples:

Figure 13-10: EZAO, START, LISTENER

Figure 13-11: EZAO, STOP, LISTENER(CSKL)

Figure 13-12: EZAO, START, CICS

Figure 13-13: EZAO, STOP, CICS

Starting and Stopping the EZASOKET Interface with a Program Link

You can start or stop the EZASOKET interface by issuing an EXEC CICS LINK to program EZACIC20. Make sure you include the following steps in the LINKing program:

• Define the COMMAREA for EZACIC20. This can be done by including the EZACICA.CPY copybook in your program.
• Initialize the COMMAREA values as follows:

  P20TYPE	I Initialization T Immediate Termination D Deferred Termination
  P20OBJ	C CICS EZASOKET interface L Listener
  P20LIST	Name of listener if this is listener initialization/termination.

• Issue the EXEC CICS LINK to program EZACIC20.

  Note: EZACIC20 will not return until the function is complete.

• Check the P20RET field for the response from EZACIC20.

  Note: Note: If the EZASOKET interface is not in startup or termination and no COMMAREA was provided, the E20L user abend code is issued by EZACIC20.

Testing that EZASOKET Support is Correctly Installed and Configured

Using the transaction EZAC, alter an existing listener or define a new listener to test the supplied transaction EZPI as show below:

Figure 13-14: EZAC, ALTER, LISTENER

Figure 13-15: EZAC, ALTER, LISTENER parameters

You can use any available port, but you must ensure that the fields TRANTRN and TRANUSR are set to NO.

Start the listener using EZAO. Once the listener has been started and the message EZY1291I appears on the console.log, run the demo transaction EZPI as shown in the examples below:

Figure 13-16: EZPI

Figure 13-17: EZPI parameters

If everything is correctly installed and configured, you will get your message in reverse order in the Received field.

Figure 13-18: EZPI received

Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.