UNLOCK

Description

UNLOCK releases the exclusive control established in response to a read command with the UPDATE option. You use it if you retrieve a record for update, and then decide that you do not want to update the record after all. However, for a recoverable file (other than one that refers to a coupling facility data table), the resource remains locked until either a SYNCPOINT command is executed or the task is terminated. The record can be in a data set, or in a CICS or user-maintained data table, on a local or a remote system.

If the UNLOCK command refers to a record in a recoverable coupling facility data table the record lock is released immediately provided that the task has not made any previous change to the same record (or added it as a new record) within the current unit of work. If changes have been made to the record, or it is a new record added to the table, it remains locked until either a SYNCPOINT command is executed or the task is terminated.

If an UNLOCK command does not have a token, an attempt is made to match it to either a read with the UPDATE option that also does not have a token, or to a WRITE MASSINSERT operation. If neither of these is found, no action is taken and a NORMAL response is returned.

Use this command to terminate a VSAM WRITE MASSINSERT operation against a VSAM file.

Releasing locks when updating in browse

The UNLOCK command does not release locks held against records locked in response to READNEXT or READPREV commands that specify the update option. It only invalidates the TOKEN value so that it cannot be used to complete an update.

Options

FILE(filename)

specifies the name of the file to be released.

If SYSID is specified, the data set to which this file refers is assumed to be on a remote system irrespective of whether the name is defined to CICS. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.

SYSID(systemname)

specifies the name of the system to which the request is directed.

TOKEN(data-area)

specifies as a fullword binary value a unique request identifier for an UNLOCK, used to associate it with a previous READ, READNEXT, or READPREV command that specified the UPDATE option.

If you specify UNLOCK with the TOKEN returned on a READNEXT UPDATE or READPREV UPDATE command for a file accessed in RLS mode, the UNLOCK command invalidates the TOKEN value so that it cannot be used to complete an update. It does not release the record lock.

TOKEN can be function shipped. However, if a request specifying TOKEN is function shipped to a CICS region that does not support this keyword, the request fails.

Conditions

84 DISABLED

RESP2 values:

50

A file is disabled because it was initially defined as disabled and has not since been enabled.

A file is disabled by an EXEC CICS SET FILE or a CEMT SET FILE command.

This condition cannot occur when the UNLOCK follows a successful read for update or a VSAM WRITE MASSINSERT.

Default action: terminate the task abnormally.

12 FILENOTFOUND

RESP2 values:

1

A file name referred to in the FILE option is not defined to CICS and SYSID has not been specified.

Default action: terminate the task abnormally.

21 ILLOGIC

RESP2 values: (VSAM and CICS-maintained data tables)

110

A VSAM error occurs that is not in one of the other CICS response categories.

See EIBRCODE in the EXEC interface block; for details, see EIB fields.

Default action: terminate the task abnormally.

16 INVREQ

RESP2 values:

47

An unlock includes a token whose value cannot be matched against any token in use for an existing READ with the UPDATE option.

48

An attempt is made to function-ship a request that includes a TOKEN keyword.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

There is an I/O error during the file control operation. An I/O error is any unusual event that is not covered by a CICS condition.

For VSAM files, IOERR usually indicates a hardware error. Further information is available in the EXEC interface block; for details, see EIB fields.

For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.

Default action: terminate the task abnormally.

54 ISCINVREQ

RESP2 values:

70

The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

70 NOTAUTH

RESP2 values:

101

A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

19 NOTOPEN

RESP2 values:

60

NOTOPEN (RESP2 60) is returned for one of the following reasons:

• The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file and the file is no longer in use. You can also make CLOSED, UNENABLED the initial state, by specifying STATUS(UNENABLED) and OPENTIME(FIRSTREF) on the FILE resource definition. (For BDAM files, you use the FILSTAT parameter of the DFHFCT TYPE=FILE macro.)
• The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
• An UNLOCK command is issued against a data set that is quiesced, or is being quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED command.
• The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request. This file open has failed for some reason. You should examine the console for messages that explain why the file open has been unsuccessful.

This condition does not occur if the request is made to a CLOSED, DISABLED file. In this case, the DISABLED condition occurs.

It also cannot occur when the UNLOCK follows a successful READ for update or a WRITE MASSINSERT operation.

Default action: terminate the task abnormally.

53 SYSIDERR

RESP2 values:

130

The SYSID option specifies a name that is neither the local CICS region nor a remote system defined to CICS by a CONNECTION definition. SYSIDERR also occurs when the link to the remote system is closed.

131

For a coupling facility data table, the connection to the coupling facility data table server has failed. This could be because the server itself has failed, or the server is available, but CICS has failed to connect to it.

132

The UNLOCK is issued against a coupling facility data table that no longer exists, probably because of a coupling facility failure, in which case the coupling facility data table server also fails. See the Defining and starting a coupling facility data table server region for information about restarting a coupling facility data table server and reloading a table.

Default action: terminate the task abnormally.