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.2.0 Last updated on 24 Jun 2020 at 09:30:04 EDT.
Copyright IBM Corporation, 1990, 2020