ALCOBJ (Allocate Object)

ALCOBJ Command syntax diagram

 

Purpose

The Allocate Object (ALCOBJ) command is used to reserve an object or list of objects for use later in the job or thread. If an object that is needed is not specified in an ALCOBJ command, an allocation is made automatically when the object is used.

Objects can be deallocated with the Deallocate Object (DLCOBJ) command. 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 allocating database files, use the DLCOBJ command before deleting the file if the file being allocated is a logical file.

  2. If a file is being allocated that is affected by a file override, the ALCOBJ command ignores the override and attempts to allocate the file named in the OBJ parameter.

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

  4. Work station message queues cannot be allocated. A work station message queue is associated with a work station device description of the same name. Therefore, to do an operation on a work station message queue that must be allocated, the user must allocate the associated device description. When the device description is allocated, the work station message queue is implicitly allocated.

  5. When ALCOBJ is executed to get an EXCL lock on a program (*PGM), only the program object description is locked. The program code is not locked exclusively. Therefore, the program may still be run by another user. Changes are not allowed for the program object description while the actual program can still be used.

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

  7. When ALCOBJ is executed to get an EXCL lock on a logical file member (*FILE), the lock occurs on both the logical file member and the associated physical file members. No other user can use the physical file members (not even through some other logical file member).

 

Restrictions

  1. This command cannot be used to allocate 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 allocate only the following database *FILE types:

    • Physical files

    • Logical files

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

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


  3. The object must exist on the system.

  4. The user issuing the command must have object operational authority for the object.

  5. If the allocation cannot be completed, none of the locks are granted, and a message is sent to the thread that issued the command. If the command is issued from a program, the Monitor Message (MONMSG) command can be used to determine whether the allocation was successful.

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

 

Required Parameters

OBJ
Specifies the qualified names of one or more system objects that are to be allocated to 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 Allocated

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 allocated.

Element 2: Type of Object to be Allocated

object-type: Specify the type of the object to be allocated. 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 Allocated

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 acquired. Both locks must be released in the job (deallocated with the DLCOBJ command) before another job can access the same object.

Element 4: Member of the Database File to be Allocated

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 allocated to the job.

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

 

Optional Parameters

WAIT
Specifies the number of seconds that the program waits for the object to be allocated. If the object cannot be allocated in the specified wait time, a message, which can be detected by a Monitor Message (MONMSG) command, is sent to the program. If one or more device descriptions are in the list of objects to be allocated, the system may wait more than the specified amount of time to attempt the allocation.

When allocating DDM files and distributed files, additional time is required for communications and for allocating files on remote systems. A separate WAIT time is used for each remote system.

When allocating objects with a lock-space-scope, the lock space may override the wait time specified.

*CLS: The job default wait time is used as the wait time for the resources being allocated.

SCOPE
Specify the scope for this 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 by the OBJ parameter support job-scoped locks.

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

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

Locks scoped to a thread can never conflict with a lock scoped to its containing job, but may conflict with a lock scoped to a different job or any other thread (depending on the lock states involved).

Locks scoped to a lock space can conflict with a lock scoped to the thread or job associated with the lock space.

CONFLICT
Specify the action to be taken if a lock conflict exists. This parameter is only supported for certain database *FILE objects. This parameter is ignored for all other objects. The supported database *FILE objects are:

  • Physical file

  • Logical file

  • Distributed file

*NORQSRLS: No requests are sent to the jobs or threads which are holding conflicting locks.

*RQSRLS: A request is sent to the system code running in each job and thread that is holding a conflicting lock for the specified object. Notification of lock contention is not visible to user applications which hold conflicting locks. Only locks which are acquired implicitly by system code are eligible to be released. Locks acquired explicitly by user application code are not eligible to be released. If *RQSRLS specified for a distributed file, the request to release the lock is sent to each node in the node group that holds a conflicting lock.

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 ALCOBJ

Example 1: Allocate File for Job 

ALCOBJ   OBJ((LIBB/FILEA  *FILE *EXCL MEMBERA)) SCOPE(*JOB)

This command exclusively allocates MEMBERA of FILEA in LIBB to the job in which the ALCOBJ command is used. If MEMBERA is unavailable, the number of seconds to wait for it to become available is the job default wait time.

Example 2: Allocate Data Area for a Thread 

ALCOBJ   OBJ((LIBY/DATAAREAX  *DTAARA  *EXCL ))
  SCOPE(*THREAD)

This command exclusively allocates DATAAREAX in LIBY to the requesting thread in which the ALCOBJ command is used. If DATAAREAX is unavailable, the number of seconds to wait for it to become available is the job default wait time.

Example 3: Allocate File for Lock Space 

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

This command exclusively allocates MEMBERA of FILEA in LIBB to the lock space attached to the current thread. If no lock space is attached, the lock is scoped to the job.

Error messages for ALCOBJ

*ESCAPE Messages

CPF1002
Cannot allocate object &1.
CPF1040
Maximum number of objects allocated on system.
CPF1085
Objects not allocated.