ENQCTL command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc cleanup)
 
Line 6: Line 6:
<dd>Examines or modifies the status of a <var class="product">Model&nbsp;204</var> file enqueuing list
<dd>Examines or modifies the status of a <var class="product">Model&nbsp;204</var> file enqueuing list
</dl>
</dl>
==Syntax==
==Syntax==
<p class="syntax">ENQCTL <span class="term">filename</span>  
<p class="syntax">ENQCTL <span class="term">filename</span> [<span class="term">sysid</span> [<span class="term">jobname</span> [<span class="term">stepname</span> [<span class="term">date</span> [<span class="term">time</span>]]]]]
  [<span class="term">sysid</span> [<span class="term">jobname</span> [<span class="term">stepname</span> [<span class="term">date</span> [<span class="term">time</span>]]]]]
</p>
</p>
   
   
<b>Where:</b>
Where:
<table>  
<table>  
<tr>
<tr>
Line 27: Line 27:
<tr>
<tr>
<th>jobname</th>
<th>jobname</th>
<td>The job name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system or the USERID on a CMS system.</td>
<td>The job name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system, or the USERID on a CMS system.</td>
</tr>
</tr>
   
   
<tr>
<tr>
<th>stepname</th>
<th>stepname</th>
<td>The step name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system or the CPU ID on a CMS system.</td>
<td>The step name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system, or the CPU ID on a CMS system.</td>
</tr>
</tr>
   
   
Line 42: Line 42:
<tr>
<tr>
<th>time</th>
<th>time</th>
<td>The time for entries to be deleted from the enqueuing list in the format hh:mm:ss.</td>
<td>The time for entries to be deleted from the enqueuing list; the format of the time is hh:mm:ss.</td>
</tr>
</tr>
</table>
</table>


==Example==
==Example==
The following example removes all enqueuing list entries from CENSUS that were added by jobs running on system S133; this might be done in case of a system crash on system S133:  
The following example removes all enqueuing list entries from <code>CENSUS</code> that were added by jobs running on system <code>S133</code>; this might be done in case of a system crash on system <code>S133</code>:  
<p class="code">ENQCTL CENSUS S133  
<p class="code">ENQCTL CENSUS S133  
</p>
</p>
==Usage notes==
==Usage notes==
The ENQCTL command examines or modifies the status of a file's enqueuing list. The enqueuing list, contained in each file, is a list of jobs that have control of the file.  
The <var>ENQCTL</var> command examines or modifies the status of a file's enqueuing list. The enqueuing list, contained in each file, is a list of jobs that have control of the file.  
<ul>  
<ul>  
<li>
<li>If you issue an <var>ENQCTL</var> command with only a filename, <var class="product">Model&nbsp;204</var> displays all the enqueue list entries with their options data for the file.</li>
<p>When you issue an ENQCTL command with only a filename, <var class="product">Model&nbsp;204</var> displays all the enqueue list entries with their options data for the file.</p>
</li>
   
   
<li>
<li>If any arguments are given, all of the entries that satisfy the arguments are deleted. For example, if a system crash occurs for system <code>S133</code>, the operator at another system can issue the command:
<p>If any arguments are given, all of the entries that satisfy the arguments are deleted. For example, if a system crash occurs for system S133, the operator at another system can issue the command:</p>
<p class="code">ENQCTL filename S133
<p class="code">ENQCTL filename S133
</p>
</p>
<p>Indiscriminate use of ENQCTL might affect the integrity of a shared DASD by removing list entries for active systems or jobs. When a file is closed, the <var class="product">Model&nbsp;204</var> job must remove its enqueuing list entry. If the correct entry cannot be found, the operator receives an error message in the following form: </p>
<p>
Indiscriminate use of <var>ENQCTL</var> might affect the integrity of a shared DASD by removing list entries for active systems or jobs. When a file is closed, the <var class="product">Model&nbsp;204</var> job must remove its enqueuing list entry. If the correct entry cannot be found, the operator receives an error message in the following form: </p>
<p class="code">*** M204.0585: SHARED DASD ENQ LIST OVERLAID FOR filename AT hh:mm:ss ON yy:ddd  
<p class="code">*** M204.0585: SHARED DASD ENQ LIST OVERLAID FOR filename AT hh:mm:ss ON yy:ddd  
</p>
</p>
<p>where the date and time identify the most recent update of the file. </p>
<p>where the date and time identify the most recent update of the file. </p>
</li>
</li>
</ul>
</ul>
 
====Handling z/VM stepnames====
====Handling z/VM stepnames====
<p>Under z/VM, the part of an enqueue entry referred to as the stepname is actually the CPUID. Prior to <var class="product">Model&nbsp;204</var> V6R1.0, if the CPUID contained unprintable characters-as is commonly the case-you could not specify the CPUID as the stepname on the ENQCTL command. In V6R1.0, you can.</p>
<p>
<p>The ENQCTL command, with no options, displays the first eight entries in the SHARED DASD enqueue list. Previously, the stepname was displayed as 1-8 characters. Now, if the stepname is printable, it is displayed as before. Otherwise, if the stepname contains unprintable characters, it is displayed in hexadecimal.</p>
Under z/VM, the part of an enqueue entry referred to as the step name is actually the CPUID. Prior to <var class="product">Model&nbsp;204</var> V6R1.0, if the CPUID contained unprintable characters &mdash; as is commonly the case &mdash; you could not specify the CPUID as the <var class="term">stepname</var> value on the <var>ENQCTL</var> command. In V6R1.0, you can.</p>
<p>
The <var>ENQCTL</var> command, with no options, displays the first eight entries in the SHARED DASD enqueue list. Previously, the step name was displayed as 1-8 characters. Now, if the step name value is printable, it is displayed as before. Otherwise, if the step name contains unprintable characters, it is displayed in hexadecimal.</p>
 
====Deleting entries in the ENQCTL list====
====Deleting entries in the ENQCTL list====
<p>The ENQCTL command, with options, deletes all matching entries in the SHARED DASD enqueue list. With this enhancement, you can specify the stepname as before, if the stepname is printable: otherwise, in hexadecimal. To specify a stepname in hexadecimal, use the format output by the ENQCTL command in display mode: the 2 characters X plus a single quotation mark (X'), followed by exactly 16 hexadecimal digits (0-F) followed by a single quotation mark (').</p>
<p>
<p>Since the stepname can be up to 8 characters, when it is expressed as a sequence of hexadecimal codes, it is displayed as 19 characters. Hence the format of entries displayed by the ENQCTL command has changed slightly-the date and time are now 11 columns further to the right.</p>
The <var>ENQCTL</var> command, with options, deletes all matching entries in the SHARED DASD enqueue list. With this enhancement, you can specify the step name as before, if the step name is printable: otherwise, in hexadecimal. To specify a step name in hexadecimal, use the format output by the <var>ENQCTL</var> command in display mode: the two characters "X" plus a single quotation mark (<code>X'</code>), followed by exactly 16 hexadecimal digits (0-F), followed by a single-quotation mark (<code>'</code>).</p>
<p><var class="product">Model&nbsp;204</var> message M204.0588 was changed to the following formats: </p>
<p>
Since the step name can be as many as eight characters, when it is expressed as a sequence of hexadecimal codes, its display uses 19 characters. Hence the format of entries displayed by the <var>ENQCTL</var> command has changed slightly &mdash; the date and time are now 11 columns further to the right.</p>
<p>
The <var class="product">Model&nbsp;204</var> message M204.0588 has the following formats: </p>
<p class="code">M204.0588: ZOS  EXCL jjjjjjjj ssssssss            yy.ddd hh:mm:ss
<p class="code">M204.0588: ZOS  EXCL jjjjjjjj ssssssss            yy.ddd hh:mm:ss
M204.0588: CMS  EXCL jjjjjjjj X'ssssssssssssssss' yy.ddd hh:mm:ss
M204.0588: CMS  EXCL jjjjjjjj X'ssssssssssssssss' yy.ddd hh:mm:ss
</p>
</p>
====Mishandling ENQCTL entries====
====Mishandling ENQCTL entries====
<p>You can effectively crash your Online if you do not bring <var class="product">Model&nbsp;204</var> down cleanly with an EOJ command, but are terminating the service machine by either issuing:</p>
<p>
You can effectively crash your Online if instead of bringing <var class="product">Model&nbsp;204</var> down cleanly with an <var>EOJ</var> command, you terminate the service machine by issuing either of these:</p>
<ul>  
<ul>  
<li>
<li>An IPL of CMS</li>
<p>An IPL of CMS</p>
</li>
   
   
<li>
<li>#CP LOGOUT</li>
<p>#CP LOGOUT</p>
</ul>
</li>
<p>
</ul>
These non-<var>EOJ</var> options leave enqueues in all files that were still open when you terminated the service machine. If you then bring <var class="product">Model&nbsp;204</var> up on a different CPU, you cannot automatically remove those enqueue entries, which will cause you problems. </p>
<p>This leave enqueues in all files that were still open when you terminated the service machine. If you then bring <var class="product">Model&nbsp;204</var> up on a different CPU, you cannot automatically remove those enqueue entries, which will cause you problems. </p>
<p>
<p>Review the procedures that bring down the service machine. It must be done by issuing: </p>
Review the procedures that bring down the service machine. It must be done by issuing: </p>
<ul>  
<ul>  
<li>
<li><var>EOJ</var> from a user machine logged into the <var class="product">Model&nbsp;204</var> Online</li>
<p>EOJ from a user machine logged into the <var class="product">Model&nbsp;204</var> Online</p>
</li>
   
   
<li>
<li><var>EOJ</var> from the service machine
<p>EOJ from the service machine</p>
<p class="note"><b>Note:</b> You cannot use the service machine unless you have a <var>HALT</var> command coded in the <var class="product">Model&nbsp;204</var> CCAIN for that Online.</p></li>
<p class="note"><b>Note:</b> You cannot use the service machine unless you have a HALT command coded in the <var class="product">Model&nbsp;204</var> CCAIN for that Online.</p>
</ul>
</li>
 
</ul>
[[Category: System administrator commands]]
[[Category: System administrator commands]]
[[Category: Operator commands]]
[[Category: Operator commands]]
[[Category:Commands]]
[[Category:Commands]]

Latest revision as of 21:46, 4 April 2016

Summary

Privileges
System administrator or operator
Function
Examines or modifies the status of a Model 204 file enqueuing list

Syntax

ENQCTL filename [sysid [jobname [stepname [date [time]]]]]

Where:

filename The name of the file to be examined or modified. The file need not be open. If only a file name is specified, all list entries for the file are displayed.

Note: filename cannot be CCATEMP.

sysid The System Management Facility (SMF) system ID for entries to be deleted from the enqueuing list.
jobname The job name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system, or the USERID on a CMS system.
stepname The step name for entries to be deleted from the enqueuing list on a z/OS or z/VSE operating system, or the CPU ID on a CMS system.
date The date for entries to be deleted from the enqueuing list; the format of the date is yy.ddd.
time The time for entries to be deleted from the enqueuing list; the format of the time is hh:mm:ss.

Example

The following example removes all enqueuing list entries from CENSUS that were added by jobs running on system S133; this might be done in case of a system crash on system S133:

ENQCTL CENSUS S133

Usage notes

The ENQCTL command examines or modifies the status of a file's enqueuing list. The enqueuing list, contained in each file, is a list of jobs that have control of the file.

  • If you issue an ENQCTL command with only a filename, Model 204 displays all the enqueue list entries with their options data for the file.
  • If any arguments are given, all of the entries that satisfy the arguments are deleted. For example, if a system crash occurs for system S133, the operator at another system can issue the command:

    ENQCTL filename S133

    Indiscriminate use of ENQCTL might affect the integrity of a shared DASD by removing list entries for active systems or jobs. When a file is closed, the Model 204 job must remove its enqueuing list entry. If the correct entry cannot be found, the operator receives an error message in the following form:

    *** M204.0585: SHARED DASD ENQ LIST OVERLAID FOR filename AT hh:mm:ss ON yy:ddd

    where the date and time identify the most recent update of the file.

Handling z/VM stepnames

Under z/VM, the part of an enqueue entry referred to as the step name is actually the CPUID. Prior to Model 204 V6R1.0, if the CPUID contained unprintable characters — as is commonly the case — you could not specify the CPUID as the stepname value on the ENQCTL command. In V6R1.0, you can.

The ENQCTL command, with no options, displays the first eight entries in the SHARED DASD enqueue list. Previously, the step name was displayed as 1-8 characters. Now, if the step name value is printable, it is displayed as before. Otherwise, if the step name contains unprintable characters, it is displayed in hexadecimal.

Deleting entries in the ENQCTL list

The ENQCTL command, with options, deletes all matching entries in the SHARED DASD enqueue list. With this enhancement, you can specify the step name as before, if the step name is printable: otherwise, in hexadecimal. To specify a step name in hexadecimal, use the format output by the ENQCTL command in display mode: the two characters "X" plus a single quotation mark (X'), followed by exactly 16 hexadecimal digits (0-F), followed by a single-quotation mark (').

Since the step name can be as many as eight characters, when it is expressed as a sequence of hexadecimal codes, its display uses 19 characters. Hence the format of entries displayed by the ENQCTL command has changed slightly — the date and time are now 11 columns further to the right.

The Model 204 message M204.0588 has the following formats:

M204.0588: ZOS EXCL jjjjjjjj ssssssss yy.ddd hh:mm:ss M204.0588: CMS EXCL jjjjjjjj X'ssssssssssssssss' yy.ddd hh:mm:ss

Mishandling ENQCTL entries

You can effectively crash your Online if instead of bringing Model 204 down cleanly with an EOJ command, you terminate the service machine by issuing either of these:

  • An IPL of CMS
  • #CP LOGOUT

These non-EOJ options leave enqueues in all files that were still open when you terminated the service machine. If you then bring Model 204 up on a different CPU, you cannot automatically remove those enqueue entries, which will cause you problems.

Review the procedures that bring down the service machine. It must be done by issuing:

  • EOJ from a user machine logged into the Model 204 Online
  • EOJ from the service machine

    Note: You cannot use the service machine unless you have a HALT command coded in the Model 204 CCAIN for that Online.