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:

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:

To use JCL with an enterprise server, you must:

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

Note: Beyond the requirements stated above, the support of EZASOKET for JCL does not need any special configuration. EZASOKET CICS support needs additional configuration as described in the section Configuring and managing EZASOKET support for CICS applications.

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".

Test Transactions

Demonstration Programs

Items Omitted from this Release

The features not available this release are:

The following APIs are not available:

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:

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:

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.

Note: If you create your own EZASOKET listener, you must compile it with the directive CALL-RECOVERY.

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.

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.

Command Object Function
ALTER CICS/Listener Modifies the attributes of an existing resource definition
DEFINE CICS/Listener Creates a new resource definition
DISPLAY CICS/Listener Shows the parameters specified for the CICS/Listener object.
DELETE CICS/Listener
  • CICS - Deletes the CICS object and all of its associated listeners.
  • Listener - Deletes the listener object.

Start a TN3270 session, connect to the port for the TN3270 listener on your enterprise server and start the EZAC transaction. When you enter EZAC, the following screen is displayed:

Initial EZAC screen

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.

You are now presented with a screen in which you specify the CICS region for which you are configuring EZASOKET.

EZAC, Define, CICS 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.

When you press Enter, the following screen is displayed.

Application parameters screen

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:

Listener screen

Figure 13-4: Listener screen

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

Listener characteristics screen

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".

Note: The supplied transaction used in this example, CSKL, uses the default listener program, EZACIC02. This listener is written in ASCII. The rules described in the table below determine whether or not it converts the transaction id and the user data in the Transaction Initial Message from EBCDIC to ASCII.

TRANTRN TRANUSR Tranid format Translate tranid? Translate user data?
YES YES ASCII NO NO
YES NO ASCII NO NO
NO YES ASCII NO YES
NO NO ASCII NO NO
YES YES EBCDIC YES YES
YES NO EBCDIC YES NO
NO YES EBCDIC YES YES
NO NO EBCDIC YES NO

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:

    Post initialization

    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:

    For example: Select group

    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:
  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:

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

EZAO screen

Figure 13-8: EZAO screen

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

EZAO, Start

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:

EZAO, START, LISTENER

Figure 13-10: EZAO, START, LISTENER

EZAO, STOP, LISTENER(CSKL)

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

EZAO, START, CICS

Figure 13-12: EZAO, START, CICS

EZAO, STOP, 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:

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:

EZAC, ALTER, LISTENER

Figure 13-14: EZAC, ALTER, LISTENER

EZAC, ALTER, LISTENER parameters

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.

Note: You cannot use the same TRANID for more than one listener within a CICS region. Therefore, if you want to create a second instance of a listener, you must define a new transaction in a group specified in your startup list. For example, to create a new instance of the default listener, you create a new transaction and associate it with the default listener program, EZACIC02. You then use EZAC to create a new listener definition with the new transaction name as the TRANID.

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:

EZPI

Figure 13-16: EZPI

EZPI parameters

Figure 13-17: EZPI parameters

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

EZPI received

Figure 13-18: EZPI received


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