Using IBM environmental support for user-written listeners

A user-written listener can use the environmental support supplied and used by the IBM-supplied listener. To employ this support, the user-written listener must do the following in addition to the requirements described in Prerequisites for writing your own listener:

The user-written listener must be written in Assembler.
The RDO definitions for the listener transaction and program should be identical to those for the IBM-supplied listener with the exception of the transaction/program names. Reference the program definition for the IBM-supplied listener, EZACIC02, in SEZAINST(EZACICCT).
Figure 1. Program Definition for listener EZACIC02
```
DEFINE PROGRAM(EZACIC02) 
DESCRIPTION(IBM LISTENER) 
GROUP(SOCKETS) CEDF(YES) DATALOCATION(ANY) EXECKEY(CICS) 
RELOAD(NO) RESIDENT(YES) USELPACOPY(NO)
LANGUAGE(ASSEMBLER) STATUS(ENABLED) USAGE(NORMAL) 
CONCURRENCY(THREADSAFE) 
```
In the program, define an input area for the configuration file records. If you are going to read the configuration file using MOVE mode, you can define the area by making the following entry in your DFHEISTG area:
```
         EZACICA AREA=CFG,TYPE=CSECT
```
If you are going to read the configuration file using LOCATE mode you can define a DSECT for the area as follows:
```
         EZACICA AREA=CFG,TYPE=DSECT
```
In either case, the length of the area is represented by the EQUATE label CFGLEN. The name of the area/DSECT is CFG0000.
In the program, define a DSECT for mapping the Global Work Area (GWA). This is done by issuing the following macro:
```
         EZACICA AREA=GWA,TYPE=DSECT
```
The name of the DSECT is GWA0000.
In the program, define a DSECT for mapping the Task Interface Element (TIE). This is done by issuing the following macro:
```
         EZACICA AREA=TIE,TYPE=DSECT
```
The name of the DSECT is TIE0000.
In the program define a DSECT for mapping the listener Control Area (LCA). This is done by issuing the following macro:
```
         EZACICA AREA=LCA,TYPE=DSECT
```
The name of the DSECT is LCA0000.
Obtain address of the GWA. This can be done using the following CICS® command:
```
         EXEC  CICS EXTRACT EXIT PROGRAM(EZACIC01) GASET(ptr) GALEN(len)
```
where ptr is a register and len is a halfword binary variable. The address of the GWA is returned in ptr and the length of the GWA is returned in len. Use of the Extract Exit command requires UPDATE access to the EXITPROGRAM resource. Failure to have at least the UPDATE access to the EXITPROGRAM resource causes the IP CICS socket interface and listener to either not start when starting or not stop when stopping.

Guideline: As of CICS/TS 2.3, the EXEC CICS EXTRACT command is not threadsafe. If the interface is using the CICS Open Transaction Environment, you should issue this command with other non-threadsafe commands to prevent excessive TCB switching.
Read the configuration file during initialization of the listener. The configuration file is identified as EZACONFG in the CICS Configuration file. The record key for the user-written listener is as follows:
- APPLID
  An 8-byte character field set to the APPLID value for this CICS. This value can be obtained from the field GWACAPPL in the GWA or by using the following CICS command:
```
         EXEC  CICS ASSIGN APPLID(applid)
```
  where applid is an 8-byte character field.
- Record Type
  A 1-byte character field set to the record type. It must have the value L.
- Reserved Field
  A 3-byte hex field set to binary zeros.
- Transaction
  A 4-byte character field containing the transaction name for this listener. It can be obtained from the EIBTRNID field in the Execute Interface Block.
The configuration record provides the information entered by either the EZACICD configuration macro or the EZAC Configuration transaction. The user-written listener can use this information selectively, but it is preferred because it contains the values specified for PORT, BACKLOG, and NUMSOCK. See Setting up and configuring CICS TCP/IP for more information about the configuration data set with EZACICD TYPE parameter subsection.
For shared files: If the user-written listener reads the configuration file, it must first issue an EXEC CICS SET command to enable and open the file. When the file operation is complete, the user-written listener must issue an EXEC CICS SET command to disable and close the file. Failure to do so results in file errors in certain shared-file situations.

Requirement: Use of the EXEC CICS ENABLE command requires UPDATE access to EXITPROGRAM resources. Failure to have at least the UPDATE access to the EXITPROGRAM resource causes the IP CICS socket interface and listener to either not start when starting or not stop when stopping.
The user-written listener should locate its listener Control Area (LCA). The LCAs are located contiguously in storage with the first one pointed to by the GWALCAAD field in the GWA. The correct LCA has the transaction name of the listener in the field LCATRAN.
The user-written listener should set the LCASTAT field to a value specified by LCASTATP so that the IP CICS socket interface is aware that the listener is active. Otherwise, the IP CICS sockets listener termination logic bypasses the posting of the listeners termination ECB.
The user-written listener should monitor either the LCASTAT field in the LCA or the GWATSTAT field in the GWA for shutdown status. If either field shows an immediate shutdown in progress, the user-written listener should terminate by issuing the EXEC CICS RETURN command and allow the interface to clean up any socket connections. If either field shows a deferred termination in progress, the user-written listener should do the following:
1. Accept any pending connections, and close the passive (listen) socket.
2. Complete the processing of any sockets involved in transaction initiation (that is, processing the GIVESOCKET command). When processing is complete, close these sockets.
3. When all sockets are closed, issue the EXEC CICS RETURN command.
The user-written listener should avoid socket calls which imply blocks dependent on external events such as ACCEPT or READ. These calls should be preceded by a single SELECTEX call that waits on the ECB LCATECB in the LCA. This ECB is posted when an immediate termination is detected, and its posting causes the SELECTEX to complete with a RETCODE of 0 and an ERRNO of 0. The program should check the ECB when the SELECTEX completes in this way as this is identical to the way SELECTEX completes when a timeout happens. The ECB can be checked by looking for a X'40' in the first byte (post bit).
This SELECTEX should also specify a timeout value. This provides the listener with a way to periodically check for a deferred termination request. Without this, CICS sockets Deferred Termination or CICS Deferred Termination cannot complete.
The user-written listener should use a non-reusable subtask. Issue the INITAPI command or an INITAPIX command with the letter L in the last byte of the subtask name. The user-written listener implements the termination and detach logic in the same way that the IBM-supplied listener does.
The user-written listener should update LCASTAT with one of the following:
```
LCASTAT DS X Status of this listener
LCASTAT0 EQU B'00000000' Listener not in operation
LCASTATI EQU B'00000001' Listener in initialization
LCASTATS EQU B'00000010' Listener in SELECT
LCASTATP EQU B'00000100' Listener processing
LCASTATE EQU B'00001000' Listener had initialization error
LCASTATC EQU B'00010000' Immediate termination in progress
LCASTATD EQU B'00100000' Deferred termination in progress
LCASTATA EQU B'01000000' Listener is active 
LCASTATR EQU B'10000000' Listener is CICS delayed retry 
```
Rule: If IP CICS sockets is configured to use CICS's Open Transaction Environment, then ensure that you serially update the LCASTAT vaue. The Listener Control Area (LCA) is part of the global work area (GWA), and is considered to be a shared resource. An appropriate value to move into LCASTAT would be LCASTATP (B'00000100') when the user-written listener starts. This value enables the CICS socket logic to correctly post the LCATECB during both deferred and immediate termination.

User-written listener programs can use the LCASTAT2A status flag to determine whether this listener should register application data. The user-written listener should update LCASTAT2 with one of the following:

LCASTAT2 DS X Listener status byte 2
LCASTAT2C EQU B'00000001' Listener can now connect to TCP
LCASTAT2A EQU B'00000010' Register Application Data
LCASTAT2H EQU B'00000100' LAPPLD inherits APPLDAT
LCASTAT2S EQU B'00100000' This is a STANDARD listener
LCASTAT2E EQU B'01000000' This is an ENHANCED listener
LCASTAT26 EQU B'10000000' Listeners AF is AF_INET6