Allocate Object (ALCOBJ)

Where allowed to run: All environments (*ALL)
Threadsafe: Conditional 		Parameters
Examples
Error messages

The Allocate Object (ALCOBJ) command is used in a job or thread to reserve an object or list of objects for use later in the job or thread. If an object that is needed in the job is not specified in an ALCOBJ command, an allocation is attempted 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).

  8. Allocating an object by specifying *LIBL for the object's library, changing the thread's library list, and then attempting to deallocate the object by specifying *LIBL for the object's library can result in issuing the deallocate against the wrong object. This could release internal locks.

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 (*OBJOPR) authority to the object and execute (*EXECUTE) authority to the object's library.

  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 for distributed data management (DDM) files of type *SNA.

Top

 

Parameters

Keyword Description Choices Notes
OBJ Object specifications Values (up to 50 repetitions): Element list Required, Positional 1
Element 1: Object Qualified object name
Qualifier 1: Object Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Object type *AUTL, *BNDDIR, *CLD, *CRQD, *CSI, *CSPMAP, *CSPTBL, *DEVD, *DTAARA, *DTADCT, *DTAQ, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *IMGCLG, *IPXD, *LIB, *LOCALE, *MEDDFN, *MENU, *MGTCOL, *MODULE, *MSGQ, *NODL, *NTBD, *NWSCFG, *NWSD, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *SBSD, *SCHIDX, *SQLPKG, *SRVPGM, *SSND, *S36, *TIMZON, *USRIDX, *USRQ, *USRSPC, *VLDL, *WSCST
Element 3: Lock state *SHRRD, *SHRNUP, *SHRUPD, *EXCLRD, *EXCL
Element 4: Member, if data base file Name, *FIRST
WAIT Wait time Integer, *CLS Optional, Positional 2
SCOPE Lock scope *JOB, *THREAD, *LCKSPC Optional
CONFLICT Lock conflict action *NORQSRLS, *RQSRLS Optional

Top

 

Object specifications (OBJ)

Specifies the name and library of one or more objects that are 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 distributed data management (DDM) file).

This is a required parameter.

You can specify 50 values for this parameter.

Element 1: Object

Qualifier 1: Object

name

Specify the name of the object.

Qualifier 2: Library

*LIBL

All libraries in the thread's library list are searched until a match is found.

*CURLIB

The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.

name

Specify the name of the library where the object is located.

Element 2: Object type

object-type

Specify the type of object to be allocated. Refer to the figure Valid Lock States by Object Type for more information.

Element 3: Lock state

*SHRRD

The lock state is shared for read.

*SHRNUP

The lock state is shared, no update.

*SHRUPD

The lock state is shared for update.

*EXCLRD

The lock state is exclusive, allow read.

*EXCL

The lock state is exclusive, no read.

Element 4: Member, if data base file

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.

name

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

You can specify all five lock states (*EXCL, *EXCLRD, *SHRUPD, *SHRNUP, and *SHRRD) for most, but not all, object types.

Figure: Valid Lock States by Object Type 

 Object                                       Lock States Type     Object Type Definition  *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            x      x       x       x       x          description *CSI     Communications side       x      x       x       x       x          information *DEVD    Device Description               x       x *DTAARA  Data area                 x      x       x       x       x *DTADCT  Data dictionary           x      x       x       x       x *DTAQ    Data queue                x      x       x       x       x *FCT     Forms control table       x      x       x       x       x *FILE    File                      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 *IPXD    Internet packet           x      x       x       x       x          exchange description *LIB     Library                          x       x       x       x *LOCALE  Locale space object       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 *MODULE  Module                    x      x                       x *MSGQ    Message queue             x                              x *NODL    Node list                 x      x       x       x       x *NTBD    NetBIOS description       x      x       x       x       x *NWSCFG  Network server            x      x       x       x       x          configuration *NWSD    Network server            x      x       x       x       x          description *OVL     Overlay                   x      x       x       x       x *PAGDFN  Page definition           x      x       x       x       x *PAGSEG  Page segment              x      x       x       x       x *PDFMAP  PDF Map                   x      x       x       x       x *PDG     Print descriptor group    x      x       x       x       x *PGM     Program                   x      x                       x *PNLGRP  Panel group               x      x       x       x       x *PSFCFG  Print service facility    x      x       x       x       x          configuration *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              x      x       x       x       x          description *SBSD    Subsystem description     x *SCHIDX  Search index              x      x       x       x       x *SQLPKG  Structured Query          x      x       x       x       x          Language package *SRVPGM  Service program           x      x       x       x       x *SSND    Session description       x      x       x       x       x *TIMZON  Time zone description     x      x       x       x       x *USRIDX  User index                x      x       x       x       x *USRQ    User queue                x      x       x       x       x *USRSPC  User space                x      x       x       x       x *VLDL    Validation list object    x      x       x       x       x *WSCST   Workstation               x      x       x       x       x          customizing object 'x' indicates the lock state is allowed for the object type.

Additional details about lock states can be found in the CL information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

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 Deallocate Object (DLCOBJ) command) before another job can access the same object. If an object is already allocated with one lock state and user want to use a different lock state, first use the ALCOBJ command to request the new lock with the desired lock state and then use the DLCOBJ command to release the old lock (with the old lock state).

When an exclusive lock is requested on a logical file member, 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).

To determine whether a device description can be allocated, use information from the Work with Configuration Status (WRKCFGSTS) command.

Top

 

Wait time (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 distributed data management (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 default wait time specified in the class description used by the routing step is used as the wait time for the object to be allocated.

integer-number

Specify the number of seconds that the program waits for all of the specified objects to be allocated. Valid values include 0 and numbers ranging from 30 through 32767. A value of 0 indicates no wait time.

Top

 

Lock scope (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 objects 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.

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

Figure: Object Types that Support Thread Scope Locks 

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

Top

 

Lock conflict action (CONFLICT)

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

*NORQSRLS

No requests are sent to other jobs or threads which are holding conflicting locks.

*RQSRLS

A request is sent to the system code running in each job or 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.

Top

 

Examples

Example 1: Allocate File for Job 

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

This command exclusively allocates member MEMBERA of file FILEA in library LIBB to the job in which the ALCOBJ command is used. If MEMBERA is unavailable, the job will wait 60 seconds for it to become available.

Example 2: Allocate Data Area for a Thread 

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

This command exclusively allocates data area DATAAREAX in library LIBY to the requesting thread in which the ALCOBJ command is used.

Example 3: Allocate File for Lock Space 

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

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

Top

 

Error messages

*ESCAPE Messages

CPF1002

Cannot allocate object &1.

CPF1040

Maximum number of objects allocated on system.

CPF1085

Objects not allocated.

Top