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 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 - 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

 
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