| 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:
Restrictions:
This allocates the piece of the file on each node in the node group.
This allocates both the DDM file on the local system and the file on the remote system that is identified in the DDM file.
| Top |
| 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 |
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
Qualifier 2: Library
Element 2: Object type
Element 3: Lock state
Element 4: Member, if data base file
Note: The following values can only be specified if the object type is a database file.
You can specify all five lock states (*EXCL, *EXCLRD, *SHRUPD, *SHRNUP, and *SHRRD) for most, but not all, object types.
|
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.
|
Note: 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 |
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.
| Top |
Specify the scope for this lock request.
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).
|
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 |
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:
| Top |
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 |
*ESCAPE Messages
| Top |