DLCOBJ (Deallocate Object)

DLCOBJ Command syntax diagram

 

Purpose

The Deallocate Object (DLCOBJ) command releases the allocations of the specified objects. The objects, allocated earlier by one or more Allocate Object (ALCOBJ) commands, are freed for use by other jobs or threads. If the DLCOBJ command is used when a lock does not exist, no error occurs.

If the DLCOBJ command is not used, the objects may be automatically deallocated. Allocated job-scoped locks are automatically released when the job ends. Allocated thread-scoped locks are automatically released when the thread ends. If a thread received a job-scoped lock, the job will continue to hold that lock after the requesting thread ends.

Lock-space-scoped locks are not automatically released.

The DLCOBJ command should not be issued for an object that was not explicitly allocated by the ALCOBJ command. If the DLCOBJ command is used this way, internal locks on the object are released, making the object capable of being deleted.

 

Notes

  1. When deallocating distributed data management (DDM) files or distributed files, additional time is required for the command to complete because of the time required for establishing communication and for deallocating files on remote systems.

  2. The system does not lock programs when calling them.

Restrictions:

  1. This command cannot be used to deallocate a device description, *DEVD, for an Advanced Program-to-Program Communications (APPC) device or for an intrasystem (INTRA) device.

  2. This command can be used to deallocate only the following database *FILE types:

    • Physical files

    • Logical files

    • Distributed files
      This deallocates the piece of the file on each node in the node group.

    • DDM files
      This deallocates both the DDM file on the local system and the file on the remote system that is identified in the DDM file.

  3. In multithreaded jobs, this command is not threadsafe for distributed files. This command is also not threadsafe and fails for Distributed Data Files (DDM) files of type *SNA.

 

Required Parameters

OBJ
Specifies the qualified name of one or more system objects that are to be deallocated from the job, thread,

or lock space,

the type of each object specified, the lock state of each object, and the member name (if the object is a database file or DDM file).

Element 1: Name of the Object to be Deallocated

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

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

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

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

object-name: Specify the name of the object to be deallocated.

Element 2: Type of Object to be Deallocated

object-type: Specify the type of the object to be deallocated. Refer to Table 1, for the list of object types that are valid for this command.

Element 3: Lock State for the Object to be Deallocated

lock-state: Specify the lock state for the object. Valid lock states include the following:

Value Lock State Meaning
*SHRRD Shared for read
*SHRUPD Shared for update
*SHRNUP Shared, no update
*EXCLRD Exclusive, allow read
*EXCL Exclusive, no read

You can specify all five lock states (*EXCL, *EXCLRD, *SHRUPD, *SHRNUP, and *SHRRD) for most, but not all, object types. Refer to Table 1, for the list of object types and the valid lock states allowed for each object type.

Note: Additional details about lock states can be found in the CL Programming

book.

Multiple locks can be specified for the same object in the same job with duplicate or different lock states. Each lock is held separately. For example, if an *EXCL lock is already held for an object, and a second *EXCL lock request occurs, the second lock is also acquired. Both locks must be separately released in the job (deallocated with the DLCOBJ command) before another job can get access to the same object.

Element 4: Member of the Database File to be Deallocated

Note: The following values can only be specified if the object type is a database file.

*FIRST: The first member of the database file is deallocated.

member-name: Specify the name of member to be deallocated. If the specified file is a logical file, the physical file members associated with the members of the logical file are also deallocated.

 

Optional Parameters

SCOPE
Specify the scope of the lock request.

*JOB: The lock is scoped to the job.

*LCKSPC:The lock is scoped to the lock space attached to the current thread. If no lock space is attached, the lock is scoped to the job.

*THREAD: The lock is scoped to the thread.

All object types supported on the OBJ parameter support job-scoped locks.

All object types supported by the OBJ parameter support lock-space-scoped locks. When deallocating DDM objects with a lock-space-scope, the lock on the remote system scoped to the job is released.

To determine if an object type supports thread-scoped locks refer to Table 1.

The lock scope must match the scope of the locks currently allocated for the job or thread.

Table 1. Object Information

Object Type Object Type Definition Lock States1 Thread Scope2
*EXCL *EXCLRD *SHRUPD *SHRNUP *SHRRD
*AUTL Authorization List x x x x x  
*BNDDIR Binding directory x x     x  
*CLD C Locale description x x x x x  
*CRQD Change request description x x x x x  
*CSI Communications side information x x x x x  
*DEVD Device Description   x x     x
*DTAARA Data area x x x x x x
*DTADCT Data dictionary x x x x x x
*DTAQ Data queue x x x x x x
*FCT Forms control table x x x x x  
*FILE File x x x x x x
*FNTRSC Font resource x x x x x  
*FNTTBL Font mapping table x x x x x  
*FORMDF Form definition x x x x x  
*IMGCLG Image catalog x x x x x x
*IPXD Internet packet exchange description x x x x x x
*LIB Library   x x x x x
*LOCALE Locale space object x x x x x x
*MEDDFN Media definition x x x x x  
*MENU Menu x x x x x  
*MGTCOL Management collection x x x x x x
*MODULE Module x x     x  
*MSGQ Message queue x       x x
*NODL Node list x x x x x  
*NTBD NetBIOS description x x x x x x
*NWSD Network server description x x x x x x
*OVL Overlay x x x x x  
*PAGDFN Page definition x x x x x  
*PAGSEG Page segment x x x x x  
*PDG Print descriptor group x x x x x  
*PGM Program x x     x x
*PNLGRP Panel group x x x x x  
*PSFCFG Print service facility configuration object x x x x x  
*QMFORM Query management form x x x x x  
*QMQRY Query management query x x x x x  
*QRYDFN Query definition x x x x x  
*S36 S/36 machine description x x x x x  
*SBSD Subsystem description x         x
*SCHIDX Search index x x x x x  
*SQLPKG Structured Query Language package x x x x x  
*SRVPGM Service program x x x x x x
*SSND Session description x x x x x  
*USRIDX User index x x x x x x
*USRQ User queue x x x x x x
*USRSPC User space x x x x x x
*VLDL Validation list object x x x x x x
*WSCST Workstation customizing object x x x x x  
1
x indicates this lock state is allowed for this object type.
2
x indicates a thread-scoped lock is allowed for this object type.

Examples for DLCOBJ

Example 1: Deallocate a File for the Job 

DLCOBJ  OBJ((LIBB/FILEA *FILE *SHRRD))

This command releases the shared-for-read allocation of the first member of file FILEA in library LIBB that was held by the job.

Example 2: Deallocate a Data Area for the Thread 

DLCOBJ  OBJ((LIBY/DATAAREAX *DTAARA *SHRRD ))
  SCOPE(*THREAD)

This command releases the shared-for-read allocation of the data area DATAAREAX in library LIBY that was held by the thread.

Example 3: Deallocate File for Lock Space 

DLCOBJ   OBJ((LIBB/FILEA  *FILE *EXCL MEMBERA)) SCOPE(*LCKSPC)

This command deallocates MEMBERA of FILEA in LIBB from the lock space attached to the current thread.

Error messages for DLCOBJ

*ESCAPE Messages

CPF1005
Objects not deallocated.