applyLock

The apply lock request causes Transaction Server to set or clear a lock for any of the following entities:
  • Batch (ICL)
  • Outbound transmission
  • Entry
Locking any of the entities reserves it for access by only the operator that requests and receives the lock. Any subsequent attempt to access a locked entity results in access being denied to the new operator. Locks ensure that the entity is used by only one operator at a time.

When locking higher level entities, such as an outbound transmission or an entry, the lock request fails if any batch (ICL) within that entity is locked. Once access to the entity is no longer needed, release the lock to allow future access.

The following table shows the fields that are needed to create an apply lock request.

Table 1. applyLock Request
Field Description
Message Type The message type text for this message. The strings that can be used for the message type are:
  • AppBridgeConstants.MSGTYPE_APPLY_LOCK
  • applyLock
Using the string that is defined in the AppBridgeConstants interface is the preferred method for setting the message type.
Unit of Work The unit of work (UOW) to be locked or unlocked. When Transaction Server receives the apply lock request, it uses the UOW type specified in the request to determine which type of entity to lock or unlock. The following UOW type specifications are supported:
  • UOW.UOW_TYPE_PRESENTMENT_ID
  • UOW.UOW_TYPE_PRESENTMENT_GROUP_ID
  • UOW.UOW_TYPE_ENTRY_ID
The request also contains an ID value that identifies the specific UOW to be locked or unlocked. The UOW must be specified using the com.ibm.icpcs.utilities.dataobj.UOW object.
Payload Additional attributes may be added to the apply lock request by sending an optional payload. The payload is a collection of NameValuePairBean objects that contains one or more of the name value pairs that are shown in the next table. The NameValuePairBean object is in the class com.ibm.paydir.ima.txacc.app.bridge.NameValuePairBean.
Table 2. applyLock Payload Attributes
Parameter Data type Default value Description
lock Boolean true Indicates if the unit of work is to be locked or unlocked:
  • true - indicates locked.
  • false - indicates unlocked.
lockedBy String null The user ID of the user requesting the lock. This parameter is optional and is ignored if the unit of work is to be unlocked.
actionType Short null An optional code that indicates the type of action that requested the lock. If it is specified, the code is sent in the event message resulting from the lock. Valid codes are:
0
Transaction Correction and Reconciliation
1
Adjustment
businessDayId Long null An optional business day identifier that is used only when locking an outbound transmission. If it is specified, this business day ID is associated with the event message resulting from the lock.
Note: Not specifying a payload is the same as specifying an empty payload. The default values for all of the parameters are used. The default request is to lock the unit of work without specifying a locking ID, action type, or business day ID.

Example payload

The following example shows how to construct a unit of work and payload for locking an outbound transmission. In this example, the outbound transmission ID is 509, the locking ID is janedoe, the action type is adjustment, and the referencing business day ID is 32. 
UOW uow = new UOW (UOW.UOW_TYPE_PRESENTMENT_GROUP_ID, "509");
List <NameValuePairBean <Object>> payload = 
                                  new Vector <NameValuePairBean <Object>> ();
payload.add (new NameValuePairBean <Object> ("lock", true) );
payload.add (new NameValuePairBean <Object> ("lockedBy", "janedoe") );
payload.add (new NameValuePairBean <Object> ("actionType", (short) 1) );
payload.add (new NameValuePairBean <Object> ("businessDayId", 32L) );

In this example, Java™ automatically converts the boolean, short, and long values into the value objects needed by the bean object. For this to work, ensure that the correct data type for each parameter is used. Otherwise, the apply lock request fails with an invalid payload error.

Return values

If a response was requested for apply lock, Transaction Server returns the result of the lock or unlock operation in the reply. The following table shows the return values for apply lock.
Table 3. applyLock Return Values
Return value Description
0 Indicates that the lock or unlock was successful.
1 Indicates that the apply lock request failed because the unit of work was already in the state requested when Transaction Server received the lock request.
All other return values Indicates an error occurred. The error return message further describes the problem.