RLHDR Back to Index page
 
Prolog 
Control Block Contents 
   RLHDR DSECT
Storage Layout 
Cross Reference (Contains links to field and bit definitions)
Programming Interface Information:
This information is NOT intended to be
used as Programming Interfaces of z/VM.


  RLHDR Prolog Top of page
 
 NAME       : HCPRLHDR
 DESCRIPTION: Live Guest Relocation Control Socket Message
              Header
 DSECT      : RLHDR
 FUNCTION   : This control block is the Live Guest Relocation
              Control Socket Message Header.  Every piece of
              data going from the relocation source to the
              relocation target over an LGR CONTROL socket
              must start with this header, so that it may be
              routed properly on the relocation target.
              Since no routing occurs on the relocation
              source, this header is optional on LGR CONTROL
              socket messages from the relocation target to
              the source as long as both pieces of code know
              what to expect.
 LOCATED BY : Any routine processing an ISFC message sent
              from the relocation source to the relocation
              target over an LGR CONTROL socket can find this
              header as the first piece of user-defined data
              in the first MBHBK "buffer fragment".  It is
              pointed to by MBHBFPTR in the MBHBF located at
              MBHBK.MBHLIST.
              Example of locating the RLHDR:
              HCPUSING MBHBK,R4               Address MBHBK
              HCPUSING MBHBF,MBHLIST,MBHBK    Address MBHBF
              LG       R5,MBHBFPTR            Locate RLHDR
              HCPUSING RLHDR,R5               Address RLHDR
 CREATED BY : Any routine that is creating an ISFC message to
              send over an LGR CONTROL socket may create this
              header.  The header is required on all messages
              from the relocation source to the relocation
              target.
 DELETED BY : Any routine that is deleting an ISFC message
              that was sent or was meant to be sent over the
              LGR CONTROL socket. The header is required on
              all messages from the relocation source to the
              relocation target.
 REFERENCES : None
 SERIALIZED : Single Thread Access.
              Since only one thread is dealing with the ISFC
              message at a time and this header is part of the
              ISFC message, there can only be one thread
              accessing this instance of the control block at
              a time and no serialization is needed.
 RELOCATION CONSIDERATIONS : None
 COMPATIBILITY AND MIGRATION CONCERNS : Any/all new fields
              should be added to the end of the header and
              the length needs to be updated.
 NOTES      : There is no PL/AS version of this control block because
              no code accessing this block is written in PL/AS.
              There are some instances where messages are sent over
              the LGR CONTROL socket without this header.  In these
              cases, the message is being sent from the relocation
              target to the relocation source.  One example of this
              is the reply msg sent from destination-side storage
              eligiblity checking (HCPRLLDE) to source-side storage
              eligibility checking (HCPRLLSE).
 
 
  RLHDR Control Block Content Top of page
 

 RLHDR DSECT Top of page
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure RLHDR Live Guest Relocation Control Socket Message Live Guest Relocation CONTROL Socket Message Header Fullword 1: 0000 0 Bitstring 1 RLHVERSN Version number of the RLHDR header. This field indicates the version of the RLHDR DSECT. When RLHDR is changed in the future, this number is increased via RLHVRS. 00000001 RLHVRS 1 Increment this whenever the format of this DSECT changes. Initial value is 1. 0001 1 Bitstring 1 RLHSUBSY Subsystem or Package Router This field indicates what router is to handle this request. The list of valid LGR routers are: 00000004 RLHSTMGT X'04' RLHSTMGT Storage Management Subsystem 00000002 RLHRDP X'02' RLHRDP Relocation Data Package Router This is currently used by the Input/Output and Virtual Simulation Subsystems 00000001 RLHVSIM X'01' RLHVSIM Virtual Simulation Subsystem 0002 2 Signed 2 RLHHLEN Header Length This is the length of the header so code interested in the data following it can skip over this header. Fullword 2: 0004 4 Bitstring 1 RLHRES0 Reserved space 0005 5 Bitstring 1 RLHRES1 Reserved space 0006 6 Signed 2 RLHRES2 Reserved space Fullword 3 & 4: 0008 8 Character 8 RLHUSER USERID of the user being relocated This field specifies the userid that is being moved, tested, queried, or cancelled. Fullword 5: The next FULLWORD of the RLHDR control block is available for each piece of LGR code to use as they see fit. There are 3 pieces of data defined here: 1. The HALFWORD request type. This identifies the request being sent to the destination. 2. The VERSION NUMBER of the request-type message. 3. The RETURN CODE from the destination system. 0010 16 Signed 2 RLHREQT Request Type Each subsystem is allowed to use this field as it wishes to distinguish the different types of requests sent from the source system. Each subsystem has a section defined below to add their own constants/equates. Note: The same value can be used by different subsystems. 0012 18 Bitstring 1 RLHMSGVN Message Version Number This is the version number for the Request Type message and is set by source code building the message to send to the destination. 0013 19 Bitstring 1 RLHRETCD Return code from the destination system This area is to send a return code from the destination to the source. It is usually used whenever an "OK" (RC=0) message needs to be sent and there is no other return data. 00000000 RLHRCOK X'00' RLHRCOK Return code zero for source Fullword 6: 0014 20 Signed 4 RLHRES3 Reserved for IBM use Fullword 7 & 8: 0018 24 Dbl-Word 8 RLHRES4 Reserved for IBM use 00000004 RLHSIZE (*-RLHDR+7)/8 size in double words 00000020 RLHBSIZE RLHSIZE*8 size in bytes Request values for Virtual Simulation SUBSYSTEM (VSIM) When RLHSUBSY = VSIM, RLHREQT could be any of the VSIM request values listed here. *** IMPORTANT ** The VSIM Request Types located below should stay in sync with the VSIM Branch table in HCPRLAVR (VSIM Router). Any addition below should also be reflected there even if no routing is needed (ex: like Request Type 7). 00000001 RLHVSBD 0001 Request to build skeleton VMDBK handled by HCPRLUBD 00000002 RLHVSRD 0002 Request to build resume the guest on the destination system handled by HCPRLURD 00000003 RLHVSABD 0003 Request to abend the destination system handled by HCPRLUAB 00000004 RLHVSET 0004 Request VSIM Eligibility Tests be run on the Destination system handled by HCPRLEVD 00000005 RLHVSDT 0005 Alert destination of cancel or terminate handled by HCPRLODR 00000006 RLHVSRS 0006 Request to return status info handled by HCPRLOSS 00000007 RLHVSSS 0007 Response to RLHVSRS. not routed (recv'd by HCPRLORS) 00000008 RLHVSTS 0008 Destination asking source to cancel the relocation. handled by HCPRLOTR The following create new sockets via HCPRLARS: 000000AF RLHVSNR 0175 New Relocation. Creates a new Main CONTROL SOCKET. This is called for MOVE and TEST. handled by HCPRLORR 000000B0 RLHVSNCS 0176 Create new non-main CONTROL SOCKET. This is used for MOVE trifurcation. handled by HCPRLARS 000000B1 RLHVSSOC 0177 Create new STATUS or CANCEL SOCKET. This is used to create a new CONTROL SOCKET from the destination to the source when STATUS or CANCEL is issued on the destination system. handled by HCPRLARS Request values for Relocation Data package SUBSYSTEM When RLHSUBSY = RDP, RLHREQT could be any of the RDP request values listed here. NOTES : RLHSUBSY=RDP is used by the I/O Subsystem and the VSIM Guest State Relocation code. See IOMSG DSECT in HCPRLX ASSEMBLE for RDP's use of RLHSUBSY Request values for Storage Management SUBSYSTEM (STMGT) When RLHSUBSY = STMGT, RLHREQT could be any of the STMGT request values listed here. 00000100 RLHSTELG X'0100' Perform eligibility checks 00000101 RLHSTCRS X'0101' Create spaces request The following create new sockets via HCPRLARS: 000000AF RLHSTSOC 0175 Create a new STORAGE MANAGEMENT data-transfer Socket. This is called for MOVE. 000000B0 RLHTHSOC 0176 Create a new THROTTLE socket. This is called for MOVE.
 
 
  RLHDR Storage Layout Top of page
 
          
*** RLHDR - Live Guest Relocation Control Socket Message
*
*     +------+------+-------------+------+------+-------------+
*   0 |:VERSN|:SUBSY|  RLHHLEN    |:RES0 |:RES1 |  RLHRES2    |
*     +------+------+-------------+------+------+-------------+
*   8 |                       RLHUSER                         |
*     +-------------+------+------+---------------------------+
*  10 |  RLHREQT    |:MSGVN|:RETCD|         RLHRES3           |
*     +-------------+------+------+---------------------------+
*  18 |                       RLHRES4                         |
*     +-------------------------------------------------------+
*  20
*
*** RLHDR - Live Guest Relocation Control Socket Message
 
 
  RLHDR Cross Reference Top of page
 
 
Symbol         Dspl Value
-------------- ---- -----
RLHBSIZE       0018 00000020
RLHHLEN        0002
RLHMSGVN       0012
RLHRCOK        0013 00000000
RLHRDP         0001 00000002
RLHREQT        0010
RLHRES0        0004
RLHRES1        0005
RLHRES2        0006
RLHRES3        0014
RLHRES4        0018
RLHRETCD       0013
RLHSIZE        0018 00000004
RLHSTCRS       0018 00000101
RLHSTELG       0018 00000100
RLHSTMGT       0001 00000004
RLHSTSOC       0018 000000AF
RLHSUBSY       0001
RLHTHSOC       0018 000000B0
RLHUSER        0008
RLHVERSN       0000
RLHVRS         0000 00000001
RLHVSABD       0018 00000003
RLHVSBD        0018 00000001
RLHVSDT        0018 00000005
RLHVSET        0018 00000004
RLHVSIM        0001 00000001
RLHVSNCS       0018 000000B0
RLHVSNR        0018 000000AF
RLHVSRD        0018 00000002
RLHVSRS        0018 00000006
RLHVSSOC       0018 000000B1
RLHVSSS        0018 00000007
RLHVSTS        0018 00000008
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:54:24 EDT.
Copyright IBM Corporation, 1990, 2022