Avoiding AEY9 abends

An AEY9 abend occurs if an application issues an EXEC SQL command when the CICS® Db2® attachment facility has not been enabled.

About this task

You can use the following CICS command to detect whether the CICS Db2 attachment facility is enabled: 

EXEC CICS EXTRACT EXIT PROGRAM('DFHD2EX1')
ENTRY('DSNCSQL')
GASET(name1)
GALENGTH(name2)
If you specify a program name of DSNCEXT1 or DSN2EXT1 CICS dynamically changes it to the required name DFHD2EX1. If you get the INVEXITREQ condition, the CICS Db2 attachment facility is not enabled.

When the CICS Db2 attachment facility is enabled, it is not necessarily connected to Db2. It can be waiting for Db2 to initialize. When this occurs, and an application issues an EXEC SQL command when CONNECTERROR=ABEND is specified in the DB2CONN, an AEY9 abend would result. CONNECTERROR=SQLCODE would result in a -923 SQL code being returned to the application.

You can use the INQUIRE EXITPROGRAM command with the CONNECTST keyword in place of the EXTRACT EXIT command to determine whether the CICS is connected to Db2.

The CONNECTST keyword of the INQUIRE EXITPROGRAM command returns values:
  • CONNECTED, when the CICS Db2 attachment facility is ready to accept SQL requests
  • NOTCONNECTED, when the CICS Db2 attachment facility is not ready to accept SQL requests

If the command fails with PGMIDERR, this is the same as NOTCONNECTED.

Figure 1 shows an example of assembler code using the INQUIRE EXITPROGRAM command.
Figure 1. Example of the INQUIRE EXITPROGRAM command
CSTAT DS F
						ENTNAME DS CL8
						EXITPROG DS CL8
						...
						MVC ENTNAME,=CL8'DSNCSQL'
						MVC EXITPROG,=CL8'DFHD2EX1'
						EXEC CICS INQUIRE EXITPROGRAM(EXITPROG) X
						ENTRYNAME(ENTNAME) CONNECTST(CSTAT) NOHANDLE
						CLC EIBRESP,DFHRESP(NORMAL)
						BNE NOTREADY
						CLC CSTAT,DFHVALUE(CONNECTED)
						BNE NOTREADY

If you specify a program name of DSN2EXT1, CICS dynamically changes it to the required name, DFHD2EX1.

Further consideration on the use of the EXTRACT EXIT or INQUIRE EXITPROGRAM commands by applications has to be made when running in an environment where dynamic workload balancing using the z/OS® Workload Manager (WLM) is taking place.

Testing for the availability of Db2 can lead to the "storm drain effect". If an application returns normally when a connection to a workload manager is unavailable, a workload manager can be deluded into routing more work to the CICS region, because it believes that good response times are being achieved. For an explanation of the storm drain effect, see Avoiding the storm drain effect. You are, therefore, advised to do the following:
  • Specify STANDBYMODE=RECONNECT in the DB2CONN. This ensures that the CICS Db2 attachment facility waits (in standby mode) for DB2® to initialize and connect automatically, should Db2 be down when connection is first attempted. Also, if Db2 subsequently fails, the CICS Db2 attachment facility reverts again to standby mode and wait for Db2. It then automatically connects when Db2 returns.
  • Use CONNECTERROR=SQLCODE provided applications handle the -923 code correctly.
  • Avoid using EXTRACT EXIT or INQUIRE EXITPROGRAM commands if CONNECTERROR=SQLCODE can be used.
  • Use CONNECTERROR=ABEND if an AEY9 abend is required. Use the INQUIRE EXITPROGRAM command instead of the EXTRACT EXIT command.
  • It is worth noting that AEY9 abends can still occur even when STANDBYMODE=RECONNECT and CONNECTERROR=SQLCODE are specified if:
    • The CICS Db2 attachment facility is never started. An AEY9 results if an application issues an EXEC SQL command. You should always specify DB2CONN=YES in the SIT, or program DFHD2CM0 in PLTPI. Therefore the CICS Db2 attachment is at minimum in standby mode.
    • The CICS Db2 attachment is shut down using a DSNC STOP or CEMT/EXEC CICS SET DB2CONN NOTCONNECTED command.
It is advisable to avoid shutting down the attachment. The CICS Db2 SPI commands allow dynamic modification of the environment without shutting down the attachment.