ACCESS (Restricting Opens or Maintenance)

The ACCESS function provides the ability to allow or disallow an open of a User Requirements Table specified at the database level while the MUF is active. You can also use it to allow or disallow the ability of applications to execute maintenance to a database while MUF is active. In Simplify mode, all DBUTLTY functions use MUF when enabled for CXX access. Function options that, without Simplify, use the CXX in MUF and honor ACCESS OFF/READ continue with Simplify to honor ACCESS OFF/READ. However, in Simplify mode for functions that without Simplify use the CXX in the user address space, and now instead use the MUF address space, must completely ignore the ACCESS setting. Each DBUTLTY ensures that it executes only when appropriate and prevents users or other DBUTLTY functions from execution in conflict.
datacom
The ACCESS function provides the ability to allow or disallow an open of a User Requirements Table specified at the database level while the MUF is active. You can also use it to allow or disallow the ability of applications to execute maintenance to a database while MUF is active. In Simplify mode, all DBUTLTY functions use MUF when enabled for CXX access. Function options that, without Simplify, use the CXX in MUF and honor ACCESS OFF/READ continue with Simplify to honor ACCESS OFF/READ. However, in Simplify mode for functions that without Simplify use the CXX in the user address space, and now instead use the MUF address space, must completely ignore the ACCESS setting. Each DBUTLTY ensures that it executes only when appropriate and prevents users or other DBUTLTY functions from execution in conflict.
Using ACCESS against a system database is not recommended. The use of ACCESS OFF/UTLTY/READ/NOMAINT is honored for all bases except the Compound Boolean Selection (CBS) temporary index. It prevents system functions from being processed, based upon which ACCESS status, which database, and what is executing.
The Access function communicates with one MUF. Be aware of the following:
  • Ensure that DBUTLTY is communicating with the desired MUF by executing DBUTLTY with the same System Identifier module (DBSIDPR) used by the MUF
  • Ensure proper load library concatenation by keeping the System Identifier modules (DBSIDPR) in separate load libraries.
If the z/OS Cross-System Coupling Facility (XCF) is being used, help ensure that the TOGROUP DBSIDPR parameter is correctly defined. 
When using a console command, these steps are unnecessary.
This page discusses the following topics:
Length of Time to Process
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.
Buffer Writes
To provide a way to maintain better continuous operation backup, when a new access status has been processed for a database, a write of all pending buffers for the Index Area(s) and data area(s) is immediately done, unless the WAIT option is used. Such buffer writes are also done for the WRITE status so a write pending can occur with no loss of any current or planned activity.
If the MUF is restarted, all access statuses you have set with the ACCESS function are cleared. You must repeat any restrictions for access by submitting the function again.
ACCESS OFF/READ/WRITE/UTLTY controls the opening of a User Requirements Table (URT). It has no effect on an already open URT.
ACCESS MAINT/NOMAINT controls the maintenance commands to add, update, or delete rows. It has no effect on the open or close of a URT. NOMAINT instantly causes all new maintenance commands to receive an error. It does 
not
 affect transaction backout (ROLLBACK) or recovery.
Area Level DBUTLTY Control
The set of WRITE/READ/OFF/UTLTY status conditions allow, independently, the control of all non-DBUTLTY opens of specific data areas. Area level access stops all MUF applications to an area, so that the area can be processed in the MUF itself, for example to REORG an area without loss of access to other areas in the database.
Area level access is independent of database level control, the functions and meanings of database level control.
An AREA= keyword provides the choice of data area level control. When AREA= is specified, DBID= must also be specified. For example, if data area A01 contains tables POL, POH, PNC, and PNM, the ACCESS utility with keywords STATUS=UTLTY,DBID=1,AREA=A01 prevents future opens of tables POL, POH, PNC, and PNM by every application in MUF that is not done through DBUTLTY.
The ACCESS MUF startup option has not been changed for support of area level DBUTLTY control, nor has the ACCESS console command been changed. Area level access is provided
only
through DBUTLTY.
For more information about area level DBUTLTY control, see Area Level DBUTLTY Control.
How to Use the Console Command
The MUF must be active when you execute this command.
Use the following in your command to initiate this function from the system console. Consult your site operating system documentation for additional syntax information.
►►─ ACCESS ─┬─ MAINT ───┬─┬─ ,ALL ──┬─────────────────────────────────────────►◄             ├─ NOMAINT ─┤ └─ 
,dbid
 ─┘             ├─ OFF ─────┤             ├─ UTLTY ───┤             ├─ READ ────┤             └─ WRITE ───┘
Command
  • ACCESS
    Invokes the function to allow or disallow an open of a User Requirements Table specified at the database level or invokes the function to allow or disallow maintenance commands while the MUF is active.
Required Keywords
  • MAINT
    This access level allows maintenance commands to process against the database(s).
  • NOMAINT
    This access level blocks application maintenance commands from processing against the database(s).
  • OFF
    This access level blocks all User Requirements Tables from opening this database(s). Except, note that in Simplify mode some DBUTLTY functions ignore this restriction.
  • UTLTY
    This access level allows update access to this database by DBUTLTY and denies access to all applications that are not DBUTLTY.
    An exception is the DBTEST function of DBUTLTY which executes
    not
    with DBUTLTY authority.
  • READ
    This access level allows read-only User Requirements Tables to open the database(s). (The User Requirements Tables can specify UPDATE=NO only.) Except, note that in Simplify mode some DBUTLTY functions ignore this restriction.
  • WRITE
    This access level allows all User Requirements Tables to open the database(s). (The User Requirements Tables can specify UPDATE=YES or NO.)
    The preceding status conditions exist after processing this command. A previous status is ignored.
  • ,ALL
    Indicates that all databases are to participate in the ACCESS function.
  • ,dbid
    Specifies the database ID for a single database. You can specify only one per function.
Consult your site operating system manual for additional syntax information related to your operating system.
How to Use the DBUTLTY Command
The MUF must be active when you execute this command. To use the ACCESS function, execute DBUTLTY using the following:
ACCESS STATUS (MAINT/NOMAINT/WRITE, Database Level)
                                  ┌──────────────────┐ ►►─ ACCESS STATUS= ─┬─ MAINT ───┬─▼─┬──────────────┬─┴────────────────────────►                     ├─ NOMAINT ─┤   └─ ,DBID=
nnnn
 ─┘                     └─ WRITE ───┘  ►─┬──────────────────────┬───────────────────────────────────────────────────►◄    └─ ,IGN68= ─┬─ NO ◄ ─┬─┘                └─ YES ──┘
ACCESS STATUS (READ/OFF/UTLTY, Database Level)
                                ┌──────────────────┐ ►►─ ACCESS STATUS= ─┬─ READ ──┬─▼─┬──────────────┬─┴──────────────────────────►                     ├─ OFF ───┤   └─ ,DBID=
nnnn
 ─┘                     └─ UTLTY ─┘  ►─ ,USERS= ─┬─ FAIL ───┬─┬──────────────────────┬────────────────────────────►◄              ├─ IGNORE ─┤ └─ ,IGN68= ─┬─ NO ◄ ─┬─┘              └─ WAIT ───┘             └─ YES ──┘
ACCESS STATUS (WRITE, Area Level)
►►─ ACCESS STATUS=WRITE,DBID=
nnnn
,AREA=
name
 ─┬──────────────────────┬─────────►◄                                              └─ ,IGN68= ─┬─ NO ◄ ─┬─┘                                                          └─ YES ──┘
ACCESS STATUS (OFF/READ/UTLTY, Area Level)
►►─ ACCESS STATUS= ─┬─ OFF ───┬─ ,DBID=
nnnn
,AREA=
name
 ────────────────────────►                     ├─ READ ──┤                     └─ UTLTY ─┘  ►─ ,USERS= ─┬─ FAIL ───┬─────────────────────────────────────────────────────►◄              ├─ IGNORE ─┤              └─ WAIT ───┘
Command
  • ACCESS
    Invokes the function to specify the type of access.
Required Keywords
  • AREA=
    name
    Specifies data area level access. If AREA= is specified, DBID= must also be specified.
    For more information about area level DBUTLTY control, see Area Level DBUTLTY Control.
    • Valid Entries:
      Valid area name
    • Default Value:
      (No default)
  • ,DBID=
    nnnn
    At the area level, you must specify one database ID.
    • Valid Entries:
      One valid database ID.
    • Default Value:
      (No default)
  • STATUS=
    Specifies the currently desired access level for the area.
    • MAINT
      This access level allows maintenance commands to process against the database(s).
    • NOMAINT
      This access level blocks application maintenance commands from processing against the database(s).
    • OFF
      This access level blocks all User Requirements Tables from opening this area. That is, databases and areas are not allowed to be opened by any application, including DBUTLTY.
    • READ
      This access level allows read-only User Requirements Tables to open a database or area. That is, READ allows a database or area to be opened without update by all applications, including DBUTLTY. This allows support for the DBUTLTY BACKUP and EXTRACT functions. (The User Requirements Tables can specify UPDATE=NO only.)
    • WRITE
      This access level allows all User Requirements Tables to open the database or area. That is, WRITE allows the database or area to be opened with or without update by all applications, including DBUTLTY. (The User Requirements Tables can specify UPDATE=YES or NO.)
    • UTLTY
      This access level allows the database or area to be opened 
      only
       by DBUTLTY.
      DBUTLTY functions that do not open a database or area are never restricted by the ACCESS function.
      The DBUTLTY function DBTEST with keyword PGM=DBTSTPR is an exception. It executes as a user application without special DBUTLTY authority.
    • Valid Entries:
      MAINT, NOMAINT, OFF, READ, WRITE, or UTLTY
    • Default Value:
      (No default)
  • ,USERS=
    (Only required for OFF, UTLTY, or READ.)
     Specifies how the function is to execute. The parameter is required for STATUS=READ, UTLTY, or OFF, and it is optional, but ignored, for STATUS=WRITE. Regardless of which option is selected, the area or access level of the DBID is changed.
    • FAIL
      Specifies that if an open User Requirements Table exists for a table within the area currently open for read or update (when OFF), or update (when READ), or not a DBUTLTY (when UTLTY), the utility step is to terminate causing no additional utility functions to execute. The MUF can have the area open 
      without
       having any open User Requirements Tables when using the OPTIMIZE option of the ACCESS MUF startup option.
    • IGNORE
      Indicates that the ACCESS is to continue without regard to the open users.
    • WAIT
      Specifies that if an open User Requirements Table exists for a table within the area currently open for read or update (when being changed to OFF), or update (when being changed to READ), or not a DBUTLTY (when being changed to UTLTY), the utility step is to wait, stopping additional utility functions from executing. The MUF can have the area open 
      without
       having any open User Requirements Tables when using the OPTIMIZE option of the ACCESS MUF startup option. This wait has no time limit.
    • Valid Entries:
      FAIL, IGNORE, or WAIT
    • Default Value:
      (No default)
Optional Keywords
  • ,DBID=
    nnnn
    At the database level, DBID= is optional and may repeat. Each occurrence may specify one or more valid database IDs or a range of DBIDs 
    nnnn-mmmm
     (a range, for example, such as 100-250).
    If DBID= is not specified, all databases are processed.
    Every database specified by a DBID keyword is processed. Each database that is not defined generates an error and fails the function after all the databases are processed, except that a database in a range not defined is ignored.
    • Valid Entries:
      One or more valid database IDs or a range of DBIDs as already described.
    • Default Value:
      ALL
  • IGN68=
    Specify IGN68=YES to ignore a return code 68. IGN68= is allowed for every ACCESS and COMM function. By ignoring return code 68, you can set up and run JCL that incorporates a stack of DBUTLTY functions without requiring that the MUF be enabled. IGN68= would therefore be useful, for example, if you wanted to load a database without first enabling the MUF, perhaps to allow restart to properly occur. Following is an example showing a stack of DBUTLTY functions that use IGN68=.
     ACCESS STATUS=UTLTY,DBID=997,USERS=WAIT,IGN68=YES  COMM   OPTION=CLOSE,DBID=997,IGN68=YES  INIT   AREA=IXX,DBID=997  INIT   AREA=A01,DBID=997  LOAD   AREA=A01,DBID=997,FORMAT=NONE,KBYTES=9999,SORT=1  ACCESS STATUS=WRITE,DBID=997,IGN68=YES
    If the CXX is externally secured, the INIT and LOAD functions do not execute without the MUF being available, and IGN68=YES is therefore not recommended.
    A function or functions specified with IGN68=YES generates message DB13001E to note that the function did not occur. Because no error was recognized, however, other functions in the stack continue to execute, and the DBUTLTY step ends without a recognizable error. Message DB13001E signals that the MUF was not enabled.
    The DBSYSID macro parameter DELAY68= can be used to specify the number of minutes that the MUF connection can wait if the MUF is not currently available. But if IGN68=YES is specified, DELAY68= is ignored and the function continues. If the delay is desired, however, either do not specify IGN68=, in which case it defaults to NO, or specify IGN68=NO.
    • Valid Entries:
      NO or YES
    • Default Value:
      NO
Example JCL (ACCESS)
Use the following as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
 //jobname    
See the previous note and 
.
 //       EXEC PGM=DBUTLTY,REGION=0M  //STEPLIB    
See the previous note and 
.
 //SYSIN    DD *                                   Command input            ACCESS   STATUS=READ,USERS=IGNORE  /*
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
                    CONTROL CARD(S)                     .........1.........2.........3.........4.........5.........6.........7.........8                     ACCESS STATUS=READ,USERS=IGNORE                     FUNCTION=ACCESS                     STATUS=READ                        USERS=IGNORE
This page of the report shows the following:
  • The command exactly as entered.
  • An analysis of keywords encountered and expected. Any errors found are flagged with a note in the left margin.
  • Any messages related to syntax processing.
                     DB00607I - BASE ALL   ACCESS READ
This page of the report shows the following:
  • A message indicating that DBUTLTY successfully placed the request on the MUF communication queue.
This is one example of the text that can be associated with the DB00607I message.