How
to
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.
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.
You must have Enterprise Server with Mainframe Transaction Option.
You must ensure that your enterprise server has Mainframe Transaction Option enabled.
You must specify a suitable SIT for your enterprise server.
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.
This section lists the programs and transactions supplied with Enterprise Server.
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".
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.
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.
See GETHOSTBYADDR above.
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.
Only the following operations are supported:
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.
The IDENT and SUBTASK parameters are ignored.
No task may have more than 4096 sockets.
Only the FIONBIO and FIONREAD operations are supported.
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.
Only the following operations are supported:
The value of the PROTO parameter passed by the caller is ignored.
Only STREAM and DGRAM sockets are supported.
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.
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.
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.
The buttons in the Resources panel change to indicate the options for viewing and managing resources by group.
This displays the contents of your startup list.
To make the enterprise server pick up the configuration changes you just made, you have to stop it and restart it.
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.
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 |
|
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:
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.
When you press Enter, the following screen is displayed.
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".
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 |
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.
The buttons in the Resources panel change to indicate the options viewing and managing resources by group.
Figure 13-6: Post initialization
You now create the program lists as described in the steps below.
The buttons in the Resources panel change to indicate the options for viewing and managing resources by type.
The screen shows a list of CICS defined PLTs. At the bottom of the list is a set of buttons for creating new entries.
For example: 
Figure 13-7: Select group
You can start the EZASOKET interface manually by using the EZAO transaction. This transaction has four functions:
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.
Stops the interface in a CICS region.
Starts a listener in a CICS region.
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
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:
| 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. |
Note: EZACIC20 will not return until the function is complete.
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.
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.
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:
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 © 2006 Micro Focus (IP) Ltd. All rights reserved.