REGISTRY request parameters

The RTCS-dependent products can create their own product registry instances. For example, the BMC AMI Ops Infrastructure CAS's CASPERM registry or BMC AMI Ops Automation product's TOMPLEX repository registry.

The data stored in an RTCS-managed registry is retained in an MVS data space that is owned by the creating address space. A VLDS-backed registry uses the MVS DIV facility to harden the information stored in the registry data space into a VSAM LINEAR data set on DASD. This stored information persists over an address space and MVS system or sysplex shutdowns. The information is reloaded into the MVS data space when an address space re-establishes an RTCS registry instance for it.

You can share registry in a single MVS image or in a sysplex via XCF. When a registry is being shared via XCF, the registry instance in the address space which has the backing VLDS allocated to it and which owns the MVS data space containing the stored information is known as the Local Owner or the Local Owning instance.

You also can create Remote registry instances in other address spaces (which are executing on other MVS images in the sysplex) to access the information in the shared registry via XCF. For a Remote registry instance, neither the local MVS data space nor (if the registry is backed) an MVS allocation is held for the backing VLDS itself. Only the Local Owner allocates with DISP=OLD the Backing VLDS and copies the information hardened in into the actual MVS data space. Data retrieved from or to be stored into a registry by an address space that is using a Remote registry instance is transmitted to and from the Local Owning address space via XCF.

You can issue the RTCS REGISTRY operator command to any address space that has created an RTCS registry instance (whether it is a Local or a Remote instance) by using the MVS MODIFY (F) operator command. For more information about RTCS commands, see RTCS-commands. 

The REGISTRY command syntax is as follows:

F cscbName,REGISTRY,request [operand]

For more details, see the following request parameters:

• ACQUIRE
• ALTER

• EXPOSE

• HARDEN
• REALLOCATE
• REINIT
• RELEASE
• STATUS
• TRANSFER
• UNEXPOSE
• UNALLOCATE

ACQUIRE

The ACQUIRE request is used to establish a local ownership of the backing VLDS for a shared registry by a member of the XCF GROUP indicating that this local registry instance is now available for access from the other member's remote registry instances.

The following rules apply when you use ACQUIRE:

• The registry must be shared in the sysplex via XCF.
• The registry must not have an existing local owner.
• The backing VLDS must not currently be allocated via DISP=OLD by any member of the XCF GROUP.

The member (address space) processes the ACQUIRE request by using the REGISTRY command as follows:

• The backing VLDS is dynamically allocated via DISP=OLD. Make sure that no other address space in the sysplex is holding any allocation for the VLDS.
• If the backing VLDS cannot be allocated via DISP=OLD, the ACQUIRE request fails.
• The Access Control Block (ACB) is opened for the backing VLDS and its size is determined.
• The MVS data space is created with a matching size.
• The MVS Data In Virtual (DIV) facility is used to map the information in the backing VLDS into the recently created MVS data space.
• This member's registry instance is now the Local Owner of the registry. Also, other members of the XCF GROUP are made aware that this member is now the Local Owner of the backing VLDS.
• The local owning registry instance is marked available for access from the remote instances and the XCF GROUP is informed that it is now exposed for remote requests.

No operands are defined for ACQUIRE.

ALTER

The ALTER request is used to update the previously established parameters for the registry instance that are used by this member (address space).

The following ALTER request operands are supported:

• DSNAME (VLDS-CLUSTER-Name)
  This operand updates the CLUSTER name of the backing VLDS that is dynamically allocated via DISP=OLD. When this member's registry instance reacquires ownership of the backing VLDS, regardless of whether you have explicitly requested the REALLOCATE or ACQUIRE request or the XCF GROUP's VLDS ownership (in case of a shared registry) is being dynamically reconfigured. For example, in case of a failure or termination of a member, which was formerly a Local Owner . 
  
  
• TRACE (OFF | NONE | DEBUG | SIMPLE | EXTENDED)
  This operand adjusts the type of registry diagnostic trace messages that are produced for this registry instance.  The diagnostic trace messages are activated only at the request of BMC Support to investigate a reported problem.
• ELIGIBLE-OWNER (YES | NO)
  This operand sets the eligibility of the current member to become the Local Owner of the backing VLDS. Only the eligible owners can automatically acquire the local ownership of the backing VLDS after it has been released by another member of XCF GROUP, which was formerly the Local Owner. If you indicate that a registry instance is not an eligible owner, the backing VLDS does not get allocated on system considered to be inappropriate. For example, a member of the XCF GROUP for a shared registry that is executing on an MVS image is small, under-powered, non-resilient, or not suitable for full production work.

The following request parameters set limits on the values of the performance parameters that the registry DIV services subtask uses. For more information, see RTCS-initialization-member. These parameters are supported for any special cases that might arise.

• DIV-SAVE-MAXIMUM (nnn)
  This operand updates the maximum time in seconds to allow the registry DIV services subtask to wait before you make the hardening updates to the registry data space into the backing VLDS. This is usually set to 10 seconds. 
• DIV-SAVE-MINIMUM (nnn)
  This operand updates the minimum time in seconds to force the registry DIV services subtask to wait before you make the hardening updates to the registry data space into the backing VLDS. This is usually set between two to five seconds only. 
• DIV-SAVE-LIMIT (nnnn)
  This operand updates the maximum number of registry update requests that are processed before the registry DIV services subtask forces all pending updates to be hardened into the backing VLDS. This is usually set to a large value (such as hundreds) to allow a large number of updates to be processed so that the registry holds up further updates to the MVS data space while previously processed updates are hardened into the backing VLDS.
  
  

EXPOSE

The EXPOSE request is used to indicate that this member's already-established Local Owning registry instance is available for access from other member's remote instances.

The following rules apply when you use EXPOSE:

• The registry must be shared in the sysplex via XCF.
• The registry instance which is the target of this EXPOSE request must be the current Local Owner. If the current registry instance is not the current Local Owner, the EXPOSE request is rejected.
• The other members of the XCF GROUP must have previously been made aware that this member is the Local Owner of the backing VLDS.
• This Local Owning registry instance is EXPOSEd to the XCF GROUP by updating this member status in the XCF GROUP, which makes the registry available for access from other remote instances.

No operands are defined for EXPOSE.

HARDEN

The HARDEN request is used to harden the previously made updates and additions to data stored to the MVS data space for the Local Owning instance into the backing VLDS.

The following rules apply when you use HARDEN:

• The registry must be backed by a VLDS because the HARDEN requests for a non-backed registry are rejected.
• Pending, un-hardened changes to the registry's MVS data space are hardened into the backing VLDS by using DIV SAVE.

No operands are defined for HARDEN.

REALLOCATE

The REALLOCATE request is used to establish local ownership of the backing VLDS for a registry by a this instance (address space) or member (if the registry is being shared).  If a registry is shared, other members are notified that this member is now the Local Owner of the backing VLDS. This new local owning instance is not exposed; therefore, this instance cannot be accessible from any other member remote instances.

The following rules apply when you use REALLOCATE:

• If the registry is shared, any member in the XCF GROUP cannot already have allocated the backing VLDS and be the Local Owner.
• The backing VLDS is dynamically allocated via DISP=OLD; this requires that no other address space in the sysplex hold allocation for the VLDS.
• If the backing VLDS cannot be allocated via DISP=OLD, the ACQUIRE request fails.
• The Access Control Block (ACB) is opened for the backing VLDS and its size is determined.
• The MVS data space is created with a matching size.
• The MVS Data in Virtual (DIV) facility is used to map the information in the backing VLDS into just created MVS data space.
• This registry instance is now becomes the Local Owner of the registry, which might not be shared.
  
  

REINIT

REINIT performs the same function as  ACQUIRE except that the content of the backing VLDS that gets dynamically allocated via DISP=OLD is examined and confirmed to be empty and uninitialized.

The following rules apply when you use REINIT:

• The registry must be shared in the sysplex via XCF.
• The registry must not have an existing Local Owner; the backing VLDS must not currently be allocated via DISP=OLD by any member of the XCF GROUP.
• The backing VLDS's cluster name has been updated by using the ALTER DSNAME request, which is used must be empty. Make sure that it is not initialized just after a use of DEFINE.
• After the ACB for the backing VLDS is opened, in addition to determining the size of the VLDS, ensure that:
  • The VLDS has been newly defined.
  • The VLDS has not been initialized.
  • The VLDS has never had any data written into it.

No operands are defined for REINIT.

RELEASE

The RELEASE request is used to relinquish local ownership of the backing VLDS by this registry instance and member (the registry must be shared).

Other members of the XCF GROUP are notified that this member is no longer the Local Owner of the backing VLDS. The registry is unavailable for access from any other member instances until one of the other eligible members ACQUIRE the registry, which results in registry being exposed. Therefore, RELEASE is opposite of ACQUIRE.

The following rules apply when you use RELEASE:

• The registry instance must be the current Local Owner.
• The registry must be being shared.

The registry member processing the RELEASE request command proceeds as follow:

• The registry is marked as DRAINING.
• The current local owning instance is set to UNEXPOSED, therefore new access requests from remote member instances are not accepted.
• Pending updates to the MVS data spaces are hardened into the backing VLDS, the DIV MAP is undone, and the ACB is closed for the VLDS.
• The registry's MVS data space is destroyed and the backing VLDS is dynamically deallocated.
• Other members in the XCF GROUP are made aware that this member is no longer the Local Owner of the backing VLDS (that is, it no longer holds a DISP=OLD allocation for the backing VLDS).
• The XCF GROUP members are signaled that they are eligible to become the Local Owner. The members can attempt to become the new Local Owner by dynically allocating DISP=OLD the backing VLDS.

STATUS

The STATUS request displays a set of messages that indicate the current status of a registry instance, which is active in the address space.

The STATUS command provides the following two regID values that are applicable only for the RTCS Subsystem address space:

• SYSTEM
• MEMORY
  
  

TRANSFER

The TRANSFER request is used to perform the following:

• Release the local ownership of the registry by the current member
• Notify a specific member of the XCF GROUP that it should be the first to attempt to acquire the backing VLDS and become the new Local Owner

The following rules apply when you use TRANSFER:

• The registry must be shared in the sysplex via XCF.
• The registry instance at which the TRANSFER request is directed must be the current Local Owner.
• If this member's registry instance is not the current Local Owner, the TRANSFER request is rejected. 
• The ownership of the backing VLDS can be transferred only from the Local Owner to a remote instance. The remote instance must be the existing member of the XCF GROUP.

TRANSFER request processing proceeds as follows:

• The current registry instance is confirmed to be the current Local Owner of a VLDS-backed shared registry (a non-backed registry has no backing VLDS whose ownership can be transferred).
• The target XCF MEMBER Name is checked to make sure that it is an active remote registry instance in the XCF GROUP.
• The registry is marked as DRAINING.
• The current Local Owning instance is set to UNEXPOSED, therefore, no new access requests from remote MEMBER instances will be accepted.
• Pending updates to the MVS data space are hardened into the backing VLDS, the DIV MAP is undone, and the ACB for the VLDS is marked as Closed.
• The registry's MVS data space is destroyed and the backing VLDS is dynamically deallocated.
• Other members in the XCF GROUP are made aware that this member is no longer the Local Owner of the backing VLDS 
• The target XCF GROUP member designated by the TO() operand is notified that it must initiate the ACQUIRE processing to become the new Local Owner by dynamically allocating DISP=OLD to the backing VLDS.

The following TRANSFER request operand is required:

TO(target-MEMBER-name)

You can obtain the XCF MEMBER names of potential remote instance TRANSFER targets from the OSZ0244I messages that are issued in response to a STATUS request. An example follows:

In this example, XCF member RTCS0044SYSA is the current Local Owning instance. The XCF GROUP contains only two members. The local ownership of the backing VLDS can be transferred from the current Local Owner (RTCS0044SYSA) to the only other member (RTCS0064SYSB) in the XCF GROUP, which is currently a remote instance.

UNEXPOSE

The UNEXPOSE request is used to:

• Retain the local ownership of the registry (including the backing VLDS) by the currently local owning member
• Disallow access from other remote member instances of the XCF GROUP

The following rules apply when you use UNEXPOSE:

• The registry must be shared in the sysplex via XCF.
• The registry instance at which the UNEXPOSE request is directed must be the current Local Owner.

UNEXPOSE request processing proceeds as follows:

• The current registry instance is the current Local Owner of a shared registry (the registry may be backed or non-backed).
• The current local owning instance is set to UNEXPOSED, therefore, new access requests from remote member instances will be accepted.
• Other members in the XCF GROUP are informed that this member is no longer accepting requests to retrieve or store information in the registry.

Although a non-backed registry can be shared, an UNEXPOSE request is typically used with a VLDS-backed registry. This is done to prepare for some activity on the same system where the current local owning instance is active, such as making a backup or in anticipation of an UNALLOCATE request. The registry remains available for data retrieval and storage on the system where the Local Owning member is executing.

If the registry is VLDS-backed, its ownership can be transferred to another member, or it can be UNALLOCATEd. Other members in the XCF GROUP are made aware that the registry retains its same (current) Local Owner, but remote instances are prohibited from forwarding registry access and update requests to the Local Owner.

No operands are defined for UNEXPOSE.

UNALLOCATE

The UNALLOCATE request is used to:

• Terminate access to a VLDS-backed registry.
• Stop making updates to the backing VLDS.
• Deallocate the VLDS CLUSTER, after which the registry has no Local Owner.

The UNALLOCATE request is typically used when the backing VLDS needs to be deallocated and the exclusive DSNAME ENQ is released. Thus the VSAM CLUSTER itself can be accessed for maintenance or manipulation by other program. For example, a backup utility such as IDCAMS REPRO.

The following rules apply when you use UNALLOCATE:

• The registry instance at which the UNALLOCATE request is directed must be the current Local Owner.

The UNALLOCATE request processing proceeds as follows:

• The current registry instance confirmed to be the Local Owner of a VLDS-backed registry. 
• The registry is marked as DRAINING.
• If the registry is being shared, the current local owning instance is set to UNEXPOSED, therefore, no new access requests from any remote MEMBER instances will be accepted.
• The pending updates to the MVS data space are hardened into the backing VLDS, the DIV MAP is undone, and the ACB for the VLDS is closed.
• The registry's MVS data space is destroyed and the backing VLDS is dynamically deallocated.
• If the registry is shared, the current member informs the other members of the XCF GROUP that they no longer consider this registry instance to be acquired.

No operands are defined for UNALLOCATE.