friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/alcobj.htm

510 lines
22 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Allocate Object (ALCOBJ)</title>
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body bgcolor="white">
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<a name="ALCOBJ.Top_Of_Page"></a>
<h2>Allocate Object (ALCOBJ)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
<b>Threadsafe: </b>Conditional
</td>
<td valign="top" align="right">
<a href="#ALCOBJ.PARAMETERS.TABLE">Parameters</a><br>
<a href="#ALCOBJ.COMMAND.EXAMPLES">Examples</a><br>
<a href="#ALCOBJ.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="ALCOBJ"></a>
<p>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.
</p>
<p>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.
</p>
<p>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.
</p>
<p><b>NOTES:</b>
</p>
<ol>
<li>When allocating database files, use the DLCOBJ command before deleting the file if the file being allocated is a logical file.
</li>
<li>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.
</li>
<li>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.
</li>
<li>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.
</li>
<li>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.
</li>
<li>The system does not lock programs when calling them.
</li>
<li>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).
</li>
<li>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.
</li>
</ol>
<p><b>Restrictions:</b>
</p>
<ol>
<li>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.
</li>
<li>This command can be used to allocate only the following database *FILE types:
<ul>
<li>Physical files
</li>
<li>Logical files
</li>
<li>Distributed files
<p>This allocates the piece of the file on each node in the node group.
</p>
</li>
<li>DDM files
<p>This allocates both the DDM file on the local system and the file on the remote system that is identified in the DDM file.
</p>
</li>
</ul>
</li>
<li>The object must exist on the system.
</li>
<li>The user issuing the command must have object operational (*OBJOPR) authority to the object and execute (*EXECUTE) authority to the object's library.
</li>
<li>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.
</li>
<li>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.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="ALCOBJ.PARAMETERS.TABLE">Parameters</a></h3>
<table border="1" cellpadding="4" cellspacing="0">
<!-- col1="10" col2="15" col3="30" col4="10" -->
<tr>
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
</tr>
<tr>
<td valign="top" rowspan="7"><a href="#ALCOBJ.OBJ"><b>OBJ</b></a></td>
<td valign="top">Object specifications</td>
<td valign="top">Values (up to 50 repetitions): <i>Element list</i></td>
<td valign="top" rowspan="7">Required, Positional 1</td>
</tr>
<tr>
<td valign="top">Element 1: Object</td>
<td valign="top">
<i>Qualified object name</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Qualifier 1: Object</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top" style="padding-left:10pt">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top">Element 2: Object type</td>
<td valign="top">
*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</td>
</tr>
<tr>
<td valign="top">Element 3: Lock state</td>
<td valign="top">
*SHRRD, *SHRNUP, *SHRUPD, *EXCLRD, *EXCL</td>
</tr>
<tr>
<td valign="top">Element 4: Member, if data base file</td>
<td valign="top">
<i>Name</i>, *FIRST</td>
</tr>
<tr>
<td valign="top"><a href="#ALCOBJ.WAIT"><b>WAIT</b></a></td>
<td valign="top">Wait time</td>
<td valign="top"><i>Integer</i>, <b><u>*CLS</u></b></td>
<td valign="top">Optional, Positional 2</td>
</tr>
<tr>
<td valign="top"><a href="#ALCOBJ.SCOPE"><b>SCOPE</b></a></td>
<td valign="top">Lock scope</td>
<td valign="top"><b><u>*JOB</u></b>, *THREAD, *LCKSPC</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#ALCOBJ.CONFLICT"><b>CONFLICT</b></a></td>
<td valign="top">Lock conflict action</td>
<td valign="top"><b><u>*NORQSRLS</u></b>, *RQSRLS</td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="ALCOBJ.OBJ"></a>
<h3>Object specifications (OBJ)</h3>
<p>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).
</p>
<p>This is a required parameter.
</p>
<p>You can specify 50 values for this parameter.
</p>
<p><b>Element 1: Object</b>
</p>
<dl>
<dt><b></b></dt>
<dd>
<p><b>Qualifier 1: Object</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the object.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the thread's library list are searched until a match is found.
</dd>
<dt><b>*CURLIB</b></dt>
<dd>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.
</dd>
</dl>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the library where the object is located.
</dd>
</dl>
</dd>
</dl>
<p><b>Element 2: Object type</b>
</p>
<dl>
<dt><b><i>object-type</i></b></dt>
<dd>Specify the type of object to be allocated. Refer to the figure Valid Lock States by Object Type for more information.
</dd>
</dl>
<p><b>Element 3: Lock state</b>
</p>
<dl>
<dt><b>*SHRRD</b></dt>
<dd>The lock state is shared for read.
</dd>
<dt><b>*SHRNUP</b></dt>
<dd>The lock state is shared, no update.
</dd>
<dt><b>*SHRUPD</b></dt>
<dd>The lock state is shared for update.
</dd>
<dt><b>*EXCLRD</b></dt>
<dd>The lock state is exclusive, allow read.
</dd>
<dt><b>*EXCL</b></dt>
<dd>The lock state is exclusive, no read.
</dd>
</dl>
<p><b>Element 4: Member, if data base file</b>
</p>
<p>
<b>Note: </b>The following values can only be specified if the object type is a database file.
</p>
<dl>
<dt><b>*FIRST</b></dt>
<dd>The first member of the database file is allocated.
</dd>
<dt><b><i>name</i></b></dt>
<dd>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.
</dd>
</dl>
<p>You can specify all five lock states (*EXCL, *EXCLRD, *SHRUPD, *SHRNUP, and *SHRRD) for most, but not all, object types.
</p>
<table border="1">
<caption align="bottom"><b>Figure: Valid Lock States by Object Type</b>
</caption>
<tr>
<td>
<p>
<pre>
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
<b>'x' indicates the lock state is allowed for the object type.</b>
</pre>
</p>
</td>
</tr>
</table>
<p>
<b>Note: </b>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.
</p>
<p>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).
</p>
<p>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).
</p>
<p>To determine whether a device description can be allocated, use information from the Work with Configuration Status (WRKCFGSTS) command.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ALCOBJ.WAIT"></a>
<h3>Wait time (WAIT)</h3>
<p>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.
</p>
<p>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.
</p>
<dl>
<dt><b><u>*CLS</u></b></dt>
<dd>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.
</dd>
<dt><b><i>integer-number</i></b></dt>
<dd>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.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ALCOBJ.SCOPE"></a>
<h3>Lock scope (SCOPE)</h3>
<p>Specify the scope for this lock request.
</p>
<dl>
<dt><b><u>*JOB</u></b></dt>
<dd>The lock is scoped to the job.
</dd>
<dt><b>*LCKSPC</b></dt>
<dd>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.
</dd>
<dt><b>*THREAD</b></dt>
<dd>The lock is scoped to the thread.
</dd>
</dl>
<p>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.
</p>
<p>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).
</p>
<table border="1">
<caption align="bottom"><b>Figure: Object Types that Support Thread Scope Locks</b>
</caption>
<tr>
<td>
<p>
<pre>
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
<b>'x' indicates a thread-scoped lock is allowed for the object type.</b>
</pre>
</p>
</td>
</tr>
</table>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ALCOBJ.CONFLICT"></a>
<h3>Lock conflict action (CONFLICT)</h3>
<p>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:
</p>
<ul>
<li>physical file
</li>
<li>logical file
</li>
<li>distributed file
</li>
</ul>
<dl>
<dt><b><u>*NORQSRLS</u></b></dt>
<dd>No requests are sent to other jobs or threads which are holding conflicting locks.
</dd>
<dt><b>*RQSRLS</b></dt>
<dd>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.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="ALCOBJ.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Allocate File for Job</b>
</p>
<p>
<pre>
ALCOBJ OBJ((LIBB/FILEA *FILE *EXCL MEMBERA)) SCOPE(*JOB)
WAIT(60)
</pre>
</p>
<p>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.
</p>
<p><b>Example 2: Allocate Data Area for a Thread</b>
</p>
<p>
<pre>
ALCOBJ OBJ((LIBY/DATAAREAX *DTAARA *EXCL ))
SCOPE(*THREAD)
</pre>
</p>
<p>This command exclusively allocates data area DATAAREAX in library LIBY to the requesting thread in which the ALCOBJ command is used.
</p>
<p><b>Example 3: Allocate File for Lock Space</b>
</p>
<p>
<pre>
ALCOBJ OBJ((LIBB/FILEA *FILE *EXCL MEMBERA))
SCOPE(*LCKSPC)
</pre>
</p>
<p>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.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="ALCOBJ.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF1002</b></dt>
<dd>Cannot allocate object &amp;1.
</dd>
<dt><b>CPF1040</b></dt>
<dd>Maximum number of objects allocated on system.
</dd>
<dt><b>CPF1085</b></dt>
<dd>Objects not allocated.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ALCOBJ.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>
Reference in New Issue Copy Permalink