LOCK—Lock a Member or Assign an Access Key

The LOCK service locks a member in a development library, assigns the member an access key, or both. In most cases, LOCK allows one member to be modified by only one user at a time. Locking a member also ensures that updates to the member can occur only in the specified development library until you unlock or promote the member. The member to be locked does not have to exist in a development library or anywhere in the SCLM project hierarchy.

Suppose you are creating a new member on your programmable workstation. You can use LOCK to reserve the member name for future use.

You can assign an access key to the member to make the member even more secure than just locking it does. If you assign an access key to a member, you must, thereafter, provide that access key to further modify the member. When using access keys, remember:

Access keys have no effect on the BUILD, DBACCT, DBUTIL, PARSE, and RPTARCH services.
You must supply the correct member access key when you call the DELETE, SAVE, STORE, and UNLOCK services.
Before you can promote a member, you must call the UNLOCK service to remove a member's access key. The PROMOTE service promotes any member that has a blank access key.
If you have successfully completed the SAVE or STORE service for a member, the member remains locked. You can still use the LOCK service to assign an access key to the member.

In most cases, LOCK allows one member to be modified by only one user at a time (see Note). When you edit a member in one development library, LOCK prohibits others from editing the same member in their development libraries. Another user cannot edit the member until you delete the member and its accounting information from your group or you promote the member to a common group.

Note: Depending upon the software configuration management plan for a project, a temporary copy of a member could exist in two development libraries at the same time. See Step 3: Establish authorization codes for more information, or see the project manager for the project.

The LOCK service provides the following capabilities:

Verifying a group
LOCK verifies that the group specified is valid. Group verification allows SCLM to control all source modifications to the higher groups of the hierarchy through the promote function.
Verifying an authorization code
The project administrator defines a list of authorization codes to each group in the project's database. An authorization code is an identifier that SCLM uses to control authority to update and promote members within a hierarchy.

The LOCK service can only lock those members in the group that are assigned one of the authorization codes defined to the group. See FLMGROUP macro for more information.
Verifying predecessors
The LOCK service guarantees that the member to be locked in the development library is the most current version of the member within the hierarchical view. Predecessors of the member are previous versions of a member existing within the same hierarchical view.

The LOCK service ensures that the member to be locked does not overlay changes to a predecessor. LOCK does this by verifying that the predecessor of each version of the member within the hierarchical view has not been modified.
Verifying build output
You cannot lock members that are outputs of a build. This verification prevents accidental modification of a build output member, such as text files and compiler listings. (These members are referred to as "noneditable" elsewhere in this document.)
Verifying access keys
The LOCK service also prevents you from accidentally modifying or deleting a member you do not control. The access key that you store with the accounting information for a member provides this verification. Locking a member with an access key allows you to prevent others from accidentally modifying or promoting the member if they make changes while working outside of SCLM.

Use the access key as a signal to other developers, not as a security measure. For example, you can use the access key to indicate the location of the member or the reason it was locked.

Command invocation format


>>-FLMCMD--LOCK,project--,-+---------+--,group--,type----------->
                           '-prj_def-'                  

>--,member--,-+----------+--,-+------------+--,-+--------+-----><
              '-authcode-'    '-access_key-'    '-userid-'

Call invocation format


>>-lastrc--:=--FLMLNK('LOCKbbbb',sclm_id--,group--,type--------->

>--,member--,-+-authcode-+--,-+-access_key-+--,-+-userid-+------>
              '-'--'-----'    '-'--'-------'    '-'--'---'   

>--,found_group--,max_prom_group--,$acct_info--,$list_info------>

>--,$msg_array);-----------------------------------------------><

ISPF interface panel

Figure 1. LOCK Service panel

   Menu  SCLM  Utilities  Help
 ──────────────────────────────────────────────────────────────────────────────
                     SCLM FLMCMD LOCK Service - Entry Panel

 SCLM Library:
    Project . . . SCLMTEST
    Alternate . .         
    Group . . . . DEV1    
    Type  . . . . SOURCE  
    Member  . . .         

 Authorization code  . .           (If blank, the default auth code is used)
 Access key  . . . . . .                
 User id . . . . . . . .           (If blank, your user id is used)







 Command ===>                                                                  
  F1=HELP      F2=          F3=END       F4=DATASETS  F5=FIND      F6=CHANGE
  F9=SWAP     F10=LEFT     F11=RIGHT    F12=SUBMIT

Parameters

project

The project name. The maximum parameter length is 8 characters. This parameter is used for FLMCMD only.

prj_def

The project definition name to be used for the lock. It defaults to project. The maximum parameter length is 8 characters. This parameter is used for FLMCMD only.

sclm_id

An SCLM ID associated with a given project and project definition. The INIT service generates the SCLM ID. The maximum parameter length is 8 characters. This parameter is used for FLMLNK only.

group

The group in which the member is to be locked. The specified group must be a development library. The maximum parameter length is 8 characters.

type

The type containing the member to be locked. The maximum parameter length is 8 characters.

member

The member to be locked. The maximum parameter length is 8 characters.

authcode

The authorization code to be used for the lock. If you do not supply an authcode, SCLM uses one of the following default values:

The authorization code from the existing member if the member being locked exists in the hierarchy
The default authorization code for the group if the member does not exist in the hierarchy.

The maximum parameter length is 8 characters.

access_key

The access key to be assigned to the member. It defaults to blank. The maximum parameter length is 16 characters. You must use the access key for any further manipulation of the member until you use the UNLOCK service to remove the access key.

userid

User ID of the person requesting the lock. It defaults to the current system user ID. The maximum parameter length is 8 characters.

found_group

An output parameter that indicates the group in which the first occurrence of the member exists within the hierarchy. The maximum parameter length is 8 characters. This parameter is used for FLMLNK only.

max_prom_group

An output parameter that indicates the highest group in the hierarchy to which the member can be promoted. This member's maximum promotable group is based on the authorization code you use for the lock. The maximum parameter length is 8 characters. This parameter is used for FLMLNK only.

$acct_info

An output parameter pointing to a record containing the static portion of the member's accounting record. See $acct_info for more details. This parameter is used for FLMLNK only.

$list_info

An output parameter pointing to an array of records that contains the dynamic portion of the member's accounting record. See $list_info for more details. This parameter is used for FLMLNK only.

$msg_array

An output parameter pointing to the message array. See Pointer parameter descriptions for more information about $msg_array. This parameter is used for FLMLNK only.

Return codes

Additional special services messages are written to the FLMMSGS ddname. See SCLM service messages for more information.

Other return codes might be produced by the FLMCMD or the FLMLNK processor. See SCLM service return codes for more information.

Possible return codes are:

0: Normal completion. If a member is already locked, and no information concerning the lock has changed (the change code, or language, for example), then no action will be taken, but the return code will still be 0. No audit or versioning records will be written in this case.
8: Error condition. The $msg_array parameter contains the error message associated with this condition.

Example of command invocation

FLMCMD LOCK,PROJ1,,USER1,SOURCE,FLM01MD2,,XXX#04

This service command locks the FLM01MD2 member of the SOURCE type in the USER1 group. The project name is PROJ1. The access key to be assigned to the member is XXX#04. The authcode and user ID parameters are defaults.

Example of call invocation

This example shows general syntax. Call invocations are language-specific. See Sample programs using SCLM services for specific examples.

lastrc := FLMLNK('LOCK    ',            (* service                  *)
                   sclm_id,             (* SCLM ID                  *)
                   'USER1   ',          (* group                    *)
                   'SOURCE  ',          (* type                     *)
                   'FLM01MD2',          (* member                   *)
                   'TESTAC  ',          (* authorization code       *)
                   'XXX#04          ',  (* access key               *)
                   '        ',          (* user ID                  *)
                   found_group,         (* found group              *)
                   max_prom_group,      (* maximum promotable group *)
                   $acct_info,          (* accounting information pointer *)
                   $list_info,          (* list information pointer *)
                   $msg_array);         (* message array pointer    *)

This service call locks the FLM01MD2 member of the SOURCE type in the USER1 group. The sclm_id parameter contains a valid SCLM ID returned from the INIT service. The authorization code to be used for the lock verification is TESTAC and the access key is XXX#04. USERID is the user requesting the lock. SCLM returns all messages in the $msg_array parameter.