SQLCODE -923: Connection not established
SQLCODE -923 (SQLSTATE 57015) means the program's connection to Db2 couldn't be set up. The message names the condition, such as Db2 not up, an allocation error or the CICS attachment not up, with a Db2 reason code and the resource involved.
Other names for this code
Also written as SQL -923, SQLCODE=-923, SQLCODE = -923, db2 -923, sqlstate 57015, connection not established db2 not up, -923 allocation error, -923 CICS attachment not up.
What it means
Before a program can run SQL, its attachment (TSO, batch, CAF, RRSAF, CICS or IMS) creates a thread in Db2 and allocates the plan. If that fails, the program gets -923 and no connection exists. The message gives a condition, a reason code and, when available, a resource type and name.
The conditions Db2 for z/OS can report are these.
- Db2 not up, not operational, shutdown in progress, or in restricted access mode.
- Db2 restarted in light mode.
- Allocation error.
- Db2 - CICS attachment not up, where NAME is the Db2 subsystem.
- Db2 - CICS entry disabled, where NAME is the DB2ENTRY.
- Fall back, meaning the object depends on a newer Db2 release than the one running.
An allocation error has its own list of causes. The plan may not exist. A database, table space, table or index the plan needs may be unavailable. A data set allocation may have failed, or virtual storage may be short. The plan may also be restricted from running in this environment, which SYSIBM.
IBM warns that any SQL a program issues after -923 gives unpredictable results.
Common causes
- The Db2 subsystem is down, stopping, or started in restricted access mode for maintenance.
- The plan named in the job or the CICS definition doesn't exist, for example after it was freed or never bound in this subsystem.
- A table space or index the plan needs is stopped or in a restricted state.
- The CICS-Db2 attachment isn't started, or the DB2ENTRY for the transaction is disabled.
- The plan was bound so that it can only run from certain environments, and this job runs from another one.
- Db2 was started in light mode after a failure, which doesn't accept normal new work.
How to find the problem
- Read the condition, reason code, TYPE and NAME in the message. Look the reason code up in the Db2 for z/OS Codes manual.
- Check the Db2 address spaces (ssnmMSTR, ssnmDBM1) in SDSF and the console for startup or shutdown messages.
- For an allocation error, check the plan exists with
SELECT NAME FROM SYSIBM.SYSPLAN WHERE NAME = 'PAYPLAN', and check SYSIBM.SYSPLSYSTEM for environment restrictions. - Run
-DISPLAY DATABASE(PAYDB) SPACENAM(*) RESTRICTto find objects in a restricted state. - In CICS, use
CEMT INQUIRE DB2CONNto see whether the attachment is connected, andCEMT INQUIRE DB2ENTRYto see whether the entry is enabled.
How to fix it
- If Db2 or an object was unavailable, wait until it's back or have it started, then rerun.
- If the plan can't be allocated, REBIND it. The bind messages explain what's missing.
- Bind the plan if it doesn't exist in this subsystem, or correct the plan name in the job or CICS definition.
- Start the CICS attachment, or enable the DB2ENTRY, after fixing whatever the reason code points to.
- Don't let the program run more SQL after -923. End it or retry the connection from scratch.
IBM documentation
IBM documentation: -923. Use the documentation for your installed release.
Related codes
Questions
What's the difference between -923 and -922?
-922 means Db2 refused the connection or plan for this user for security reasons. -923 means the connection failed for a non-security reason, such as Db2 being down or the plan not allocating.
Can the program retry after -923?
It should not run more SQL on that failed connection. End the program or start a fresh connection once the cause is fixed.
Why does -923 say allocation error when the plan exists?
The plan may exist but need an object that is unavailable, a data set that won't allocate, or an environment it wasn't bound for. The reason code and resource name say which.