ENQCTL command

From m204wiki
Revision as of 21:46, 4 April 2016 by JAL (talk | contribs) (misc cleanup)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.