PN79652: UNPREDICTABLE RESULTS USING APITYPE=3 WITH EZASMI MACRO INTERFACE.

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• Customer assembler application written using apitype=3 is
  experiencing unpredictable results using EZASMI macro
  interface. The problems that they have seen are the recv call
  getting invalid rc=0 when data was actually received. Sends
  intermitently fails with errno=45, with subsequent close
  failing with errno=1008. Send faild ends with rc=0 even
  though data has been sent.
  Additional Symptoms:
   Abend0C4 Because storage freed.  R14 points to MVPYINT X'228'
   which contains BALR 14,15.
   Abend0C4 because storage is freed due to IRB running the
   GetHostByName (or GetHostByAddr) code attempting to run code
   that has been deleted. A POST occurs for the TCB running the
   mainline code and it deletes the IRB's code. The IRB, running
   under another TCB, was interrupted and causes an 0C4 when it
   is resumed.  Also described in APAR PN86216.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of TCP/IP for MVS; Macro           *
  *                 Application Programming Interface (MAPI)     *
  *                 APITYPE=3 or CICS Sockets                    *
  ****************************************************************
  * PROBLEM DESCRIPTION: Unpredictable results using APITYPE=3   *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  A variety of unpredictable results can occur in the use of
  APITYPE=3 where there are multiple sockets active on the same
  IUCV path or TIE. The symptoms are diverse, including erroneous
  return codes, ERRNO's, and data. In some cases, wait states were
  encountered.
  
  Under certain conditions, socket transactions are waiting in
  EZACIC01 for a response from the EZACIC03 subtask. This response
  is normally driven by a response from TCP/IP to an outstanding
  socket call. There are two conditions where the socket
  transaction will not see this response and will hang:
  1) An Abend of the subtask. If the subtask abends, EZACIC01 is
  not posted for event completion.
  2) TCP/IP failure. If TCP/IP fails, IUCV cannot deliver the
  connection severed' interrupt to any subtask except the
  listener. The listener terminates properly but all other
  subtasks are hung resulting in their corresponding CICS tasks
  being hung.
  
  In this APAR, an ESTAE routine has been added to the subtask to
  cope with situation 1. When the ESTAE exit is activated, it
  checks for the presence of the TIE and, if the TIE is still
  there, posts the CICS task indicating subtask termination.
  Scenario 2 will be addressed by a future APAR.
  
  APARs closed DUPlicate of this one:
  
  PN79145 error description:
  CICS SOCKET TRANSACTIONS ARE "HANGING" IN EZACIC03 CAUSING A
  RECYCLE OF THE CICS REGION TO RECOVER
  
  Under certain conditions socket transactions are waiting in
  EZACIC03 for IUCV or TCPIP interrupts. From the CICS point of
  view the transactions are in an MVS wait in EZACIC01. This
  situation occurs when an application issues a blocking read/recv
  call to a remote host that does not respond. TCPIP has no way of
  knowing that the remote host is not responding because no error
  condition was returned. This causes the customer to attempt to
  recover by trying to force purge the transactions but they are
  unable to do so. They then try to recover by issuing CSKD to
  terminate the TRUE and the subtask but this is also
  unsuccessful. The only recovery is to recycle the CICS region.
  
  PN81703 error description:
  ABEND0C4 IN EZACICRE+112E BECAUSE EZASOK03 HAS DELETED EZACICRE
  
  LPR fails with an abend0C4-11 in EZACICRE while performing the
  GetHostByName function.  The GetHostByName function causes
  EZASOK03 to issue a load for EZACICRE and branch to it.  When
  CICRE returns to SOK03, a delete is issued for CICRE.  The error
  is that an IRB is running code in CICRE and gets interrupted,
  CICRE is deleted, and the IRB gets control and tries to execute
  instructions out of CICRE.
  
  The IRB is scheduled under the job step TCB to run the exit
  code.  The exit code issues the post SVC and the post SVC
  returns control to the exit code.  The only thing left in the
  exit code is restoring the regs and returning to the caller.
  Before the exit code can be dispatched to do the return, an SRB
  is scheduled under the job step TCB which gets control.  The TCB
  that is running EZACICRE was posted by the exit code so it is
  dispatched and continues processing.  The code in EZACICRE is
  completed and returns to EZASOK03 which then performs a delete
  SVC for EZACICRE.
  
  The SRB running under the job step TCB completes and the IRB
  gets control again.  When the IRB is dispatched, the exit code
  that does the return logic has been freemained as a result of
  the delete SVC for EZACICRE.  This causes an abend0C4 pic11.
  
  SYMPTOMS: The PSW address will not be in storage but the system
  trace table should have SVC 2 entries with the same PSW address.
  The TCB that receives the abend should be the JSTCB and the
  request block should be an IRB. The NPF VTAM capture point is
  most likely to get this error due to the SRBs being scheduled
  under the JSTCB to handle the VTAM interrupts. The exit code
  running under the IRB is INTIUCVB in IUCVFORC.
  CICS Sockets Listener (CSKL) IRB owning TCB abends 0C4.
  
  PN82948 error description:
  EZASOK03 DOES NOT RETURN TO THE CALLER CORRECTLY IF VMCF OR
  TCP/IP ARE NOT ACTIVE.
  
  EZASOK03 does not preserve the caller's save area on INITAPI
  call if VMCF or TCP/IP are not active.  The error can occur if
  the check for the JESCT in TRU00100 fails, VMCF is not found in
  TRU00200, or if TCP/IP is not active in TRU00300.
  The code issues a getmain for the subtask common storage which
  will contain the savearea.  The problem is that R13 is not
  loaded with the address of the subtask common storage area until
  TRU00350.  If the JESCT, VMCF, or TCP/IP check fails, the code
  branches around TRU00350 and ends up at TRU70100.  The code
  then loads R13 with the previous savearea address, but really is
  picking up the savearea prior to the SOK03 caller.  The regs are
  restored from the savearea and we BSM to R14.
  
  Running an SVC trace will show the SVC 120 for the getmain of
  the subtask common storage, followed by an SVC 8 for EZACICMT
  for normal execution.  If the SVC 8 is not in the trace, then
  the savearea has been corrupted.
  
  PN86216 error description:
  ABEND0C4 BECAUSE STORAGE FREED.  R14 POINTS TO MVPYINT X'228'
  WHICH CONTAINS BALR 14,15
  
  Abend0C4 because storage is freed due to IRB running the
  GetHostByName (or GetHostByAddr) code attempting to run code
  that has been deleted. A POST occurs for the TCB running the
  mainline code and it deletes the IRB's code. The IRB, running
  under another TCB, was interrupted and causes an 0C4 when it is
  resumed.
  
  Note: Any user who applied one of the pre-PTF usermods should
        RESTORE them prior to application of these PTFs. i.e:
  
        LSSO310 $HTCP310 LSSO31A $HTCP310 LSSO3A2 $HTCP310
        LSSO311 $JTCP311 LSSO31B $JTCP311 LSSO3B2 $JTCP311
        LSSO3C0 $HTCP310 LSSO3E0 $HTCP310 LSSO3D1 $JTCP311
        LSSO3F1 $JTCP311
  
  Additional Keywords and Symptoms: ABEND0C4 ABENDS0C4 S0C4
  0C4 caused by a TIE. The address for the TIE is correct at 8DA4
  but the E$USECB is put into the program at offset x'1982', then
  when EZASMI loads that into the tie + x'2E0' it picks up the
  second halfword first because the field is not on a word
  boundary. The problem is caused by the parameter list for
  EZASOK03. This parameter list consists of the following fields:
  
            E$A03P1  DS      F     ADDRESS OF GWA
            E$A03P2  DS      F     ADDRESS OF TIE
            E$ASMTOK DS      CL16  TOKEN FIELD
            E$ASMCMD DS      H     COMMAND FIELD FOR IPARML
            E$ASMDUM DS      8F    DUMMY FIELD FOR USE WITH RECV
            E$ASMLOM DS      F     LENGTH OF FIELD FOR SELECT
            E$USECB  DS      F     ADDRESS OF USER'S ECB
  
  The problem happens after the halfword field E$ASMCMD. The next
  fullword field (E$ASMDUM) starts at the next sequential address,
  which would now be on a halfword boundary.
  

Problem conclusion

• Sockets Extended:
  
  1) Two external changes have been made to the interface. The ECB
  area (104 bytes) MUST be doubleword aligned. The second is the
  addition of new ERRNO values (see documentation changes below).
  
  2) Implementation of the EZASMI TYPE=CANCEL macro. This macro is
  used to cancel an outstanding blocked call such as an EZASMI
  TYPE=READ. The original call MUST have been issued with the ECB
  parameter and the EZASMI TYPE=CANCEL is issued as follows:
  
      EZASMI TYPE=CANCEL,
             CALLAREA=OTHERECB, ECB area from call to be cancelled
             ECB=CANCECB,       ECB area for cancel call
             ERRNO=CANERR,      ERRNO returned from cancel call
             RETCODE=CANRET     RETCODE returned from cancel call
  
  Note that both calls must be asynchronous and the order of their
  completion is unpredictable. Since the timing of the cancel in
  relationship to the other call affects its outcome, there are
  multiple possibilities:
  
  a) Call being cancelled
     RETCODE=-1, ERRNO=1009  Call was cancelled
     Any other combination   Call completed before cancel was
                             processed.
  b) CANCEL call
     RETCODE=0, ERRNO=0      Call was cancelled
     RETCODE=-1, ERRNO=3     Call cannot be found. TCP/IP might
                             have already processed it.
     RETCODE=-1, ERRNO=22    Call cannot be cancelled.
  
  Note that the EZASMI TYPE=SYNC must be issued for both calls.
  Both ECB's will be posted unless one call has a request error.
  
  Note 1: Assembler users of sockets extended must reassemble
  their programs to get the changes to the asynchronous facilities
  including the CANCEL macro.
  
  Note 2: The storage area used to map the GWA (via the EZASMI
  TYPE=GLOBAL, STORAGE=DSECT) must be initialized to binary
  zeroes.
  
  Note 3: The MAXSOC parameter of the EZASMI TYPE=INITAPI macro is
  defined as a halfword. If a fullword is used, unpredictable
  results may occur, including a 10112 error.
  
  
  Note 4: The ECB area must be cleared to binary zeroes.
  
  Sockets Extended and CICS:
  
  1) The 32K large buffer has been eliminated. This will
  substantially reduce OSCOR requirements in CICS and general
  memory requirements in Sockets Extended.
  2) One data move has been eliminated. This will improve
  performance in both environments.
  
  CICS Only:
  
  1) ESTAE support have been added to the subtask. The ESTAE
  routine determines if the TIE is still addressable and, if it
  is, it informs the CICS transaction of the abend with a return
  code of -1 and an errno of 10999 and continues abend processing.
  2) The Transient Data Queue for the TRUE (EZACIC01) has been
  changed to 'TCPM'.
  3) The ENQ has been changed to eliminate the possibility of S138
  abends
  
  Documentation Changes:
  
  The TCP/IP for MVS Version 3 Release 1 Application Programming
  Interface Reference Guide (SC31-7187-01) should be changed as
  follows:
  
  "Storage Definition" on page 141, Chapter 4. Macro Application
  Programming Interface (API). Change the third paragraph as
  follows:
  
     The defining task must make the address of this storage
     available to all other tasks within the address space using
     the interface.  Programs running in these tasks must define
     the storage mapping with the instruction EZASMI TYPE=GLOBAL
     with STORAGE=DSECT. The storage area used to map the GWA
     must be initialized to binary zeroes.
  
  "Task Management" on page 142, Chapter 4. Macro Application
  Programming Interface (API). Replace the example of how to code
  WAIT instructions with:
  
    For asynchronous functions, the RETCODE value should be set to
    zero before the macro is issued. The user should either code
    the ERROR parameter on the macro or check register 15 for a
    negative value immediately after macro completion. If any
    errors have been detected during either macro execution or
    invocation of the sockets function, the following will take
    place:
  
    1) If the ERROR parameter is specified, the program will
    branch to the location specified in the ERROR parameter.
    2) If the ERROR parameter is not specified, register 15 will
    have a value of -1. If no error has occurred, register 15 will
    be zero.
    3) In either case, if an error has occurred, the ERRNO field
    specified by the user will contain a value indicating the type
    of error. Also, if an error has occurred, the ECB will not be
    posted.
  
    If no error has occurred, the invocation was successful and
    the ECB will be posted. You can test the ECB for posting prior
    to issuing a WAIT as many times the posting takes place before
    control is returned from the macro. If you do not test the ECB
    or the ECB was not posted, you should issue a WAIT for the
    ECB. When the WAIT is satisfied (ECB posted) the RETCODE and
    ERRNO fields reflect the results of the function. See the
    following example of a READ macro:
  
              XC    READRET,READRET    Clear RETCODE field
     *
              EZASMI TYPE=READ,        Read data from socket
                    BUF=DATAAREA,      Data area for read
                    NBYTE=DATASIZE,    Size of data area
                    ECB=READECB,       ECB area
                    ERRNO=READERR,     ERRNO field for read
                    RETCODE=READRET    RETCODE field for read
     *
     *    If you don't code ERROR=, you would need the following:
     *
              LTR   R15,R15        Get RC code from READ request
              BM    READERR        If negative, go to error rtn
     *
              WAIT  ECB=READECB        Wait on READ to complete
     *
              EZASMI TYPE=SYNC,        Process READ response
                    ECB=READECB,       ECB area
                    ERRNO=READERR,     ERRNO field for read
                    RETCODE=READRET    RETCODE field for read
     *
              L     R0,READRET       Get RC from READ response
              LTR   R0,R0            Check for errors
              BM    READERR          If negative, go to error rtn
     *
     *  READ was good so continue processing
     *
  
  "The Macros for Assembler Programs", on page 180, Chapter 4.
  Change the MAXSOC description for the SELECT macro as follows:
  
     Parameter  Description
  
     MAXSOC     Input parameter. A halfword binary field
                specifying the largest socket descriptor number to
                be checked plus 1. Socket numbering ranges from 0
                to 1999.
  
  "Sockets Extended Return Codes", on page 524, Appendix B. Add
  the following new return codes:
  
    Error   Problem                            System
    Code    Description                        Action
    --------------------------------------------------------------
    30000   Synchronization Error.             End the call.
  
    Programmer's Response:
    This errno is returned when a SYNC response does not
    correspond to the call for which it was issued. The typical
    cause of this problem is an error in WAIT logic, e.g. the
    user's program proceeded directly to the SYNC macro without
    issuing a WAIT. Another cause is issuing the SYNC with the
    wrong ECB area which could happen in a multi-threaded
    environment if there are programming errors.
  
    30001   Send errors on the CANCEL call.    End the call.
  
    Programmer's Response:
    This errno is returned if errors are detected in the CANCEL
    call. One such error is having CALLAREA and ECB pointing to
    the same area. 30002 - ECB area not doubleword aligned.
  
    30003   Path quiesced - SENDs not allowed. End the call.
  
    Programmer's Response:
    TCP/IP has issued a QUIESCE on your path indicating it will
    not accept any more requests at this time.
  
    30004   MSGLIM exceeded.                   End the call.
  
    Programmer's Response:
    The number of outstanding socket calls permitted on your path
    has been exceeded.
  

Temporary fix

Comments

• ×**** PE96/08/28 PTF IN ERROR. SEE APAR PN88330  FOR DESCRIPTION
  ×**** PE96/11/13 FIX IN ERROR. SEE APAR PN91177  FOR DESCRIPTION
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UN93760 UN93761 UN93763 UN93764 UN93765 PN90450

Modules/Macros

• EZACICCM EZACICSC EZACIC00 EZACIC01 EZACIC03
  EZAIMSAS EZAIMSES EZAIMSLN EZAPASSK EZAPPFCI EZASMGWA EZASMI
  EZASMIC  EZASOKET EZASOKFN EZASOK03
  

Fix information

• Fixed component name

  TCP/IP V3 MVS

• Fixed component ID

  5655HAL00

Applicable component levels

• R310 PSY UN93760

     UP96/08/14 P F608

• R311 PSY UN93761

     UP96/08/14 P F608

• R315 PSY UN93763

     UP96/08/14 P F608

• R316 PSY UN93764

     UP96/08/14 P F608

• R318 PSY UN93765

     UP96/08/14 P F608

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.