How does ACCESS OFF work with USERS=WAIT and USERS=FAIL?

Document ID : KB000014064
Last Modified Date : 14/02/2018
Show Technical Document Details
Introduction:

It is a common function to turn off access to a CA Datacom/DB or CA Datacom/AD database to take a backup, perform maintenance, etc. Being able to control access is important to ensure success of the processes you need to perform, and so it is important to understand how this function works.

Question:

How does the CA Datacom DBUTLTY function "ACCESS OFF" work with USERS=WAIT and USERS=FAIL?

Answer:

First, there are two different parts to this ACCESS...OFF function to discuss: 

  • The actual turning off of access (disabling) for a database, and
  • What effect does USERS= have?

The first point is fairly simple. As soon as the ACCESS...OFF function is received in the MUF, it is processed. What it does is noted in the DBUTLTY documentation for the ACCESS function description:

ACCESS OFF/READ/WRITE/UTLTY controls the opening of a User Requirements Table (URT). It has no effect on an already open URT.

This means that once the MUF processes the command, it will turn off access to (disable) the DBID so that new URTs/tasks will not be able to access the database. Therefore, new work cannot run against this DBID. Any currently open URTs and tasks will continue until their open URTs have been closed. As the DBUTLTY page indicates, "When the function is processed with the keywords READ, OFF, UTLTY, or NOMAINT, the database is disabled instantly. After the database or databases are disabled, a console message is written."

The console message mentioned above is
DB00607I - BASE nnn ACCESS OFF ACTIVE JOB(S)  

Once the database is disabled, any new tasks that try to access the database will receive a RC 88(002) or 88(085) error.

Now to the second point about the USERS value. Whereas the first point dealt with other tasks that want to access the database, this second point answers the question, "Now that I have turned off access to (disabled) the database, what do you want me to do in my job, and with any other functions in this DBUTLTY step?"

USERS=WAIT specifies that this ACCESS...OFF job is to wait until all the open URTs are closed before finalizing the ACCESS...OFF command and proceeding to process any other DBUTLTY functions. This is the reason that you will not see the DB00607I message - this command is not complete until the WAIT is satisfied by all other URTs being closed. Note that this wait does not expire; there is no time limit.

USERS=FAIL indicates that once the access has been turned off, if there are still open URTs, this DBUTLTY step will terminate immediately and you will get message 
DB10045E - ABNORMAL TERMINATION DUE TO ERROR(S) 

and a U0004 completion. If there are no open URTs, processing continues as usual.

So to summarize this, the ACCESS...OFF function will process immediately, just like any other DBUTLTY function, and will turn off access to (disable) the database. Then, if you use USERS=WAIT, the ACCESS...OFF function will sit and wait until all open URTs are closed before marking this ACCESS function complete, issuing the "Request Complete" message and continuing on with any other functions. If you use USERS=FAIL, processing will continue if there are no open URTs, and it will terminate immediately with a U0004 abend if there are any other open URTs.

You can query the status of a database at any time from the Datacom System Tables. To do this, you would run a DBSQLPR job with this input:

//SYSIN    DD  *                  
SELECT * FROM MUF_ACCESS WHERE DBID = nnn   ;
/*

which produces a report like this (for DB 240, in my case):

MUF_NAME  DBID TYPE_ACCESS MAINTENANCE OPEN_STATUS OPTIMIZE_OPEN
________ _____ ___________ ___________ ___________ _____________
MUFNAME    240 OFF         Y           WRITE       Y            
___ 1 row returned ___                                

Additional Information:

For more information about the DBUTLTY ACCESS function, please refer to the following documentation:

CA Datacom/DB version 14.02 DBUTLTY Guide, in the section, ACCESS (Restricting Opens or Maintenance)

CA Datacom/DB version 15.0 DocOps Webpage, in the section, Reference > DBUTLTY Reference > Utility Function Summary > ACCESS (Restricting Opens or Maintenance)

CA Datacom/DB version 15.1 DocOps Webpage, in the section, Reference > DBUTLTY Reference > Utility Function Summary > ACCESS (Restricting Opens or Maintenance)

As always, please contact CA Technologies support for CA Datacom if you have further questions.