CHKOBJ (Check Object)

CHKOBJ Command syntax diagram

 

Purpose

The Check Object (CHKOBJ) command verifies that an object exists and that a user has authority to the object before access to it is permitted. For verification, as many as ten specific authorities can be specified in the command.

These checks are particularly useful before the user tries to access several objects at the same time. The CHKOBJ command is also used to check the validity of object names contained in CL variables and to verify object authorizations under program control.

When the command runs, the system searches for the specified object. If the object is found, the system verifies that the user is authorized to that object as specified on the CHKOBJ command. If the object is not found or the user does not have the authorities specified on the CHKOBJ command, an escape message is sent to the user.

When the CHKOBJ command is used in a CL program, at least one Monitor Message (MONMSG) command should follow the CHKOBJ command to monitor for any messages that result from running this command.

 

Required Parameters

OBJ

Specifies the qualified name of the object being checked. If no library name is given, *LIBL is used to find the object.

The name of the object can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

object-name: Specify the name of the object that is checked.

OBJTYPE

Specifies the object type of the OS/400 system object being checked. Enter the predefined value that specifies the object type. More information on this parameter is in Commonly used parameters.

 

Optional Parameters

MBR

Specifies which logical file member is checked, when checking data authorities.

Note:

The logical file member, and the physical file members on which it is based are checked.

*NONE: Database file members are not checked, but the existence and (optionally) the authority of the file are checked. For all other object types (including device files), *NONE is the only valid value for the MBR parameter.

*FIRST: The first member in the database file is used.

database-file-member-name: Specify the name of a physical or logical file member to be checked by the CHKOBJ command. Values specified for the OBJ and OBJTYPE parameters must identify a database file and the member specified must be a member of the database file specified in the OBJ parameter.

AUT

Specifies the authority being checked.

*NONE: The user's authority is not checked.

*USE: The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. *USE authority provides object operational authority, read authority, and execute authority.

*CHANGE: The user's object operational authority and all data authorities to the object are checked regardless of the object type.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.

*EXCLUDE: The user cannot access the object.

*AUTLMGT: The user's authority to add, delete, or change users and their authorities on the authorization list or delete the authorization list is checked.

Note:

The OBJTYPE(*AUTL) parameter must be specified before specifying AUT(*AUTLMGT).

*OBJALTER: Object alter authority provides the authority needed to alter the attributes of an object. If the user has this authority on a database file, the user can add and remove triggers, add and remove referential and unique constraints, and change the attributes of the database file. If the user has this authority on an SQL package, the user can change the attributes of the SQL package. This authority is currently only used for database files and SQL packages.

*OBJEXIST: The user's authority to control object ownership and existence is checked. These authorities are required for a user to delete an object; to free storage; or to save, restore, or transfer ownership of the object. A user with special save system (*SAVSYS) authority does not need object existence authority to save or restore the object.

*OBJMGT: The user's authority to manage the access to, and availability of, the object is checked. A user with object management authority can check personal authority status, move and rename objects, and add members to database files.

*OBJOPR: The user's authority to manage access to, and availability of, the object is checked. Object operational authority has no data authority associated with it. Data authorities (listed below) are individually checked.

*OBJREF: Object reference authority provides the authority needed to reference an object from another object such that operations on that object may be restricted by the other object. If the user has this authority on a physical file, the user can add a referential constraint in which the physical file is the parent. This authority is currently only used for database files.

*ADD: The user's add authority, which is needed to add entries to the object (for example, adding job entries to a queue or adding records to a file) is checked.

*DLT: Delete authority allows the user to remove entries from an object, for example, remove messages from a message queue or records from a file.

*EXECUTE: The user's execute authority, which is needed to run a program or locate an object in a library.

*READ: The user's read authority, which is needed to retrieve the contents of the object entry is checked.

*UPD: The user's update authority, which is needed to update entries in the object is checked.

Examples for CHKOBJ

Example 1: Checking for Existence of a Program

CHKOBJ  OBJ(LIB1/PROG1)  OBJTYPE(*PGM)

This command checks for the existence of a program named PROG1 in library LIB1. The user's authorities to PROG1 are not checked.

Example 2: Checking for User's Authority to File

CHKOBJ  OBJ(SOURCE1)  OBJTYPE(*FILE)
  MBR(MBR3)  AUT(*CHANGE)

This command checks for the existence of file SOURCE1 and for the existence of member MBR3 in file SOURCE1. It also checks to see if the user has *CHANGE authority to file SOURCE1.

Example 3: Checking for User's Authority to Program

CHKOBJ   OBJ(LIB1/PROG1)  OBJTYPE(*PGM)  AUT(*CHANGE)

This command checks the existence of program PROG1 in library LIB1. It also checks to see if the user has *CHANGE authority to PROG1.

Messages that can be monitored by the Monitor Message (MONMSG) command if sent by the CHKOBJ command are:

CPF9801

OBJECT NOT FOUND-PROG1 does not exist.

CPF9802

OBJECT NOT AUTHORIZED-The user that issued this command does not have *CHANGE authority to PROG1.

CPF9810

LIBRARY NOT FOUND-LIB1 cannot be located.

CPF9820

NOT AUTHORIZED TO LIBRARY-The user that issued this command is not authorized to the library named LIB1.

CPF9830

UNABLE TO ALLOCATE LIBRARY-The library named LIB1 is locked and cannot be accessed.

Example 4: Checking User's Authority to a Logical File Member

CHKOBJ  OBJ(FILEA)  OBJTYPE(*FILE)
  MBR(MBR1)  AUT(*USE)

This command checks the user's authority to use logical file member MBR1, and each physical file member on which MBR1 is based.

In addition to the messages listed in the previous example, messages that can be monitored by the MONMSG command if sent by the CHKOBJ command, are:

CPF9815

MEMBER IN FILE NOT FOUND-MBR1 cannot be found in FILEA or FILEA does not contain members. If FILEA is a device file, a CPF9899 message is sent.

CPF9899

FUNCTION NOT PERFORMED-This message is a summary escape message that is always preceded by a diagnostic message. If FILEA is a device file, message CPD2168 precedes message CPF9899. If FILEA is locked, message CPF3202 precedes this message.

Example 5: Checking User's Add and Delete Authority

CHKOBJ   OBJ(FILEA)  OBJTYPE(*FILE)  MBR(MBR1)
  AUT(*ADD  *DLT)
 
MONMSG   MSGID(CPF9802)  EXEC(GOTO  ERROR1)

These two commands (CHKOBJ and MONMSG) are used to verify that the user has both add and delete authority for logical file FILEA and each of the physical file members on which the logical file member MBR1 in the logical file FILEA is based. If the user does not have data authority for FILEA and each of the physical file members on which FILEA is based, escape message CPF9802 is sent to the program, and control in the program is passed to the command that has the label ERROR1.

Error messages for CHKOBJ

*ESCAPE Messages

CPF9801

Object &2 in library &3 not found.

CPF9802

Not authorized to object &2 in &3.

CPF9810

Library &1 not found.

CPF9815

Member &5 file &2 in library &3 not found.

CPF9820

Not authorized to use library &1.

CPF9830

Cannot assign library &1.

CPF9899

Error occurred during processing of command.