/LOCK command

Queuing of output messages for a particular communication line, terminal, or transaction code is not affected.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Equivalent IMS type-2 commands
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the command and keywords.

Syntax

                    .------------------------.               
                    V                        |               
>>-+-/LOCK-+--+-DB----dbname--+------------+-+-----------+-----><
   '-/LOC--'  |               '-(password)-'             |   
              |          .---------------------------.   |   
              |          V                           |   |   
              +-LTERM--+---ltermname--+------------+-+-+-+   
              |        |              '-(password)-'   | |   
              |        '-ALL---------------------------' |   
              +-NODE-------------------------------------+   
              |      .-------------------------.         |   
              |      V                         |         |   
              +-PGM----pgmname--+------------+-+---------+   
              |                 '-(password)-'           |   
              +-PTERM------------------------------------+   
              |       .--------------------------.       |   
              |       V                          |       |   
              '-TRAN----tranname--+------------+-+-------'   
                                  '-(password)-'             

Keywords

The following keywords are valid for the /LOCK command:

DB

LOCK prevents subsequently scheduled programs from accessing the database. The /LOCK DB command does not close the database or affect currently scheduled programs.

If the database is a DEDB or MSDB, programs using the database will not be scheduled. For other databases, the programs will still be scheduled. If the INIT call was issued, however, a call against the database will result in either a 3303 pseudoabend or a BA status code.

For DBCTL, CCTL can specify LONG or SHORT when it schedules a PSB. If the database is currently scheduled to a LONG thread, the command is rejected. If not, the thread completes before the database is acted upon. If the thread completes, a commit point or transaction termination is the result.

While the database is being quiesced, this command cannot be processed successfully.

LTERM

Specifies the logical terminal for which sending and receiving of messages is to be stopped. /LOCK LTERM applies only to logical terminals associated with the entering physical terminal.

The /LOCK LTERM ALL command can only be used when none of the logical terminals associated with the entering physical terminal have passwords.

NODE

Specifies that the sending and receiving of messages for the VTAM® node associated with the entering physical terminal is to be stopped.

PGM

Specifies the program for which scheduling is to be stopped.

PTERM

Specifies that the sending and receiving of messages for the entering physical terminal is to be stopped.

TRAN

Specifies that scheduling of messages containing this transaction code is to be stopped. The /LOCK TRAN command cannot be used with Fast Path exclusive transactions but can be used with Fast Path potential transactions.

The /LOCK TRAN command cannot be used for CPI Communications driven programs.

Usage notes

The /LOCK command can be used on HALDB databases.

The output of the /LOCK DB command is changed when the command is entered through the OM API. In this case, the DFS058I message is not returned to OM. The command response returned to OM contains one or more of the following messages: DFS0488I, DFS3466I, or DFS132. The OM API does not support the /LOCK command without any keywords.

The /LOCK command can be issued by APPC and OTMA clients.

This command can be issued to an IMSplex by using the Batch SPOC utility.

A resource name can be defined with password protection in SAF for the DB, LTERM, PGM, and TRAN keywords. If the parameter, LOCKSEC=Y (N is the default) is specified on the DFSPBxxx IMS.PROCLIB member, IMS™ calls the SAF and user exit calls. If the resource is not defined to SAF, or is defined and is authorized to the user, the command is processed. If the resource is defined to SAF but not authorized for use, the command is rejected with a DFS3689W message.

The password associated with a signed on user, and specified after a command resource parameter, will be used to perform a reverification check, if the resource is defined to RACF® with 'REVERIFY' specified in the APPLDATA field. Passwords can be mixed case or uppercase depending on what is specified on the PSWDC keyword in the DFSPBxxx IMS.PROCLIB member. If the resource passes the RACF authorization check, and RVFY=Y is specified as an IMS startup parameter, IMS will verify that the password following the parameter is the same as the password entered during signon for the user that entered the command. If 'REVERIFY' is specified for a resource, but a password is not provided, or the wrong password is provided, the command processing for that resource will be rejected.

A period that is specified in the password brackets is not treated as a delimiter.

The /LOCK LTERM, NODE, and PTERM commands apply only to the entering physical terminal. The /LOCK DB | PGM | TRAN command is only valid if entered from the master terminal, the system console, a TCO script, or an AOI application program.

Issuing the /LOCK command for a physical terminal, logical terminals, or nodes prevents application program output from being sent (assuming nonresponse mode transactions) and message switches from any other terminals. Output message queuing continues for the locked physical terminal. The /STOP LTERM command can be used instead of the /LOCK LTERM command, because both stop the sending and receiving of messages to the physical terminal.

If the terminals are on a switched communication network and a physical or logical terminal disconnection occurs, an implied /UNLOCK command is processed against the physical terminal and inquiry logical terminal.

The /LOCK command cannot be used with logical terminals assigned to deallocated users.

When you enter this command, the database name can be an existing non-HALDB, a HALDB master, or a HALDB partition. A command against a HALDB partition operates exactly like a command against a non-HALDB with the exception of the /START DB and the UPDATE DB START(ACCESS) commands. A HALDB partition is not allocated during the command unless it was previously authorized but not allocated, the OPEN keyword was specified, or the partition has EEQEs. The partition is allocated at first reference.

The HALDB partition reflects conditions such as STOPPED, LOCKED, or NOTOPEN. When a HALDB partition is stopped, it must be explicitly started again. Commands with the keyword ALL and commands against a HALDB master do not change the STOPPED and LOCKED indicators in each HALDB partition.

When the command target is a HALDB master, processing acts on all HALDB partitions. For example, if the IMS command is /DBR on the HALDB master, all of the HALDB partitions are closed, deallocated, and deauthorized. Only the HALDB master displays STOPPED (each HALDB partition does not display STOPPED unless it was itself stopped). If a /DBR command was issued against a HALDB master, the display output of a /DISPLAY DB command shows the HALDB master (as STOPPED), but does not display the status of the partitions.

Each partition inherits the access limitations of its HALDB master. If the /DBD command is issued against a HALDB master, all of its partitions close. A subsequent reference to any of the partitions results in the partition opening for input, although the partition's access might be UPDATE or EXCLUSIVE. The DBRC authorization state reflects the limited access.

Equivalent IMS type-2 commands

The following table shows variations of the /LOCK command and the IMS type-2 commands that perform similar functions.