USRBK | Back to Index page

| Prolog Control Block Contents USRBK DSECT USRBCBK 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.

USRBK Prolog | Top of page

     NAME       : HCPUSRBK
     DESCRIPTION: SSI complex wide user attributes
     DSECT      : USRBK
     FUNCTION   : The USRBK contains the minimal information needed to
                  identify a user logged on somewhere in the SSI complex.
                  The USRBK essentially has two forms.  Either embedded
                  within a VMDBK (for a user that is local on the
                  system with the VMDBK), or as a standalone block
                  for a user that is logged onto some other system in
                  the SSI complex.
     LOCATED BY : USRBKs representing local users are embedded in the
                  user's ORIGIN VMDBK and you locate it just as you
                  would a VMDBK (VMDCYCLE, etc.).  Clearly there is
                  an embedded USRBK in every VMDBK, ORIGIN or not,
                  and some non-ORIGIN fields do contain values (eg:
                  USRUSER is populated in all VMDBKs), however, the
                  one true embedded USRBK is in the ORIGIN VMDBK and
                  only its contents are maintained and considered to
                  be valid.
                  USRBKs representing non-local users are chained via
                  USRCHAIN off SYSUSRCH in SYSCM.
                  Both are in the userid hash table.
     CREATED BY : USRBKs representing local users are instantiated when
                  an ORIGIN VMDBK is allocated.  USRBKs representing a
                  non-local user are allocated by HCPUSR when it is
                  notified a user has logged onto a remote system.
     DELETED BY : USRBKs representing local users are deleted when an
                  origin VMDBK is fret'ed (either the user has logged
                  off or been relocated off).  USRBKs representing a
                  non-local user are deleted by HCPUSR when the
                  user logs off or has been migrated in.
     REFERENCES : VMDBK
     SERIALIZED : Deletion of the remote USRBKs is by MP defer.
                  A USRBK pointer is only valid until the next
                  loss of control.
     COMPATIBILITY AND MIGRATION CONCERNS : If the format of this
                  control block changes in future releases be sure
                  to increment the version counter.  Any changes
                  to the global portion must be done in an upwardly
                  compatible manner and added to the end (it's OK
                  to push the local section if need be).
     RELOCATION CONSIDERATIONS : None.  This block exists on each
                  system in the SSI complex and is not relocated
                  between systems.
     COMMENTS   : The USRBK is divided into two parts as it were.
                  The first part is data that is global (eg: should be
                  same on all systems) and will be included anytime
                  the block is broadcast (such as userid, the block
                  version, etc.).  Clearly the block version may
                  not be the same on each system, but it must be
                  broadcast so each system knows what it's dealing
                  with.  The system where the user is logged onto
                  determines the block's level.  If it's a downlevel
                  system, the uplevel systems won't find anything
                  of value in the new fields (and should be checking
                  the version before looking).  If it's an uplevel
                  system the downlevel systems won't know enough to
                  look at any new stuff.  The second part is data
                  that will be local to the system the USRBK is on
                  (eg: chain pointer, etc.).
                  If the USRBK is embedded in the VMDBK the address
                  of the VMDBK may be divined by NILL against the
                  USRBK address with the USRtoVMD mask.  Likewise a
                  routine can accept either a VMDBK or a USRBK as a
                  parameter and divine which it was passed by doing
                  a TMLL with USRorVMD (CC 0 means you have a VMDBK).
                  The above scheme assumes that a VMDBK always
                  starts on a page boundary and that a USRBK never
                  starts on a page boundary.  A standalone block
                  can never start on a page boundary as it will
                  always have a free storage header preceding it.
                  An embedded USRBK could only start on a page
                  boundary if it was the first field in a VMDBK.
                  A CKMAINT in HCPUSR verifies it's not.
                  If you have a known USRBK pointer you can
                  determine whether it's a standlone USRBK (that is
                  to say represents a non-local user) or an embedded
                  USRBK (that is to say a local user) by doing a
                  TM USRLFLAG,USRVMDBK.  If CC 3 is returned then,
                  as noted above, NILL with USRtoVMD gives you the
                  VMDBK address for the local user.

USRBK Control Block Content | Top of page

     USRBK DSECT
    Top of page

    Hex   Dec Type/Val   Lng Label (dup)    Comments
    ---- ---- --------- ---- -------------- --------
    0000    0 Structure      USRBK          SSI complex wide user attributes
    0000    0 Character    8 USRUSER        User logon identification USRUSER
                                            is also referred to as VMDUSER in
                                            an embedded USRBK.
    0008    8 Signed       2 USRPLXSL       System slot number to identify
                                            which system in the SSI complex
                                            the user is logged onto.
    000A   10 Signed       1 USRLEVEL       USRBK level
              00000001       USRLVLV1       1 USRLVLV1 Version 1 of the
                                            control block
    000B   11 Bitstring    1 USRGFLAG       USRBK global (SSI wide) flags
              1... ....      USRFESEC       B'10000000' USRFESEC This guest
                                            is Functionally Enabled to act as
                                            a SECondary user. Further details
                                            about this bit can be found in
                                            HCPSEC.
              .1.. ....      USRDISC        B'01000000' USRDISC This guest is
                                            currently disconnected. Can be
                                            loosely considered a mirror of
                                            VMDDISC
              ..1. ....      USRMSGV2       B'00100000' USRMSGV2 This guest
                                            supports node qualified secondary
                                            APIs
    000C   12 Bitstring    4 *              Reserved
              00000010       USRBRDSZ       *-USRBK Broadcast size - portion
                                            of USRBK that is globally known
                                            and broadcast amongst SSI members
    0010   16 Address      4 USRCHAIN       Chain of USRBKs representing
                                            remote users (embedded USRBKs for
                                            local users don't need a chain,
                                            they are "chained" via VMDCYCLE
                                            as it were)
    0014   20 Bitstring    1 USRLFLAG       USRBK local system flags
              1... ....      USRVMDBK       B'10000000' USRVMDBK This USRBK
                                            is embedded in a VMDBK (that is
                                            to say it represents a local
                                            user. If this bit is off we have
                                            a stand alone USRBK on a remote
                                            system).
              .1.. ....      USRBCed        B'01000000' USRBCed This USRBK
                                            was announced to the world by a
                                            broadcast create. Only valid in
                                            the embedded USRBK (that is to
                                            say USRVMDBK must be on for this
                                            bit to have meaning)
              ..1. ....      USRAFSEC       B'00100000' USRAFSEC This flag
                                            indicates that at some point
                                            during this user's session it was
                                            an Active Functional SECondary
                                            user for a primary user on this
                                            system. Further details about
                                            this bit can be found in HCPSEC.
              ...1 ....      USRVESTL       B'00010000' USRVESTL This flag is
                                            only set in a stand alone USRBK.
                                            It indicates the guest has
                                            recently relocated off this
                                            system but there are still
                                            vestigial remnants of the user on
                                            the system (the VMDBK has not yet
                                            completed logoff processing). Bit
                                            is turned off when logoff
                                            completes.
              .... .1..      USROLDBK       B'00000100' USROLDBK This flag is
                                            only set in a stand-alone USRBK.
                                            It is set ON when the local
                                            suspended system goes to
                                            joining/joined and indicates that
                                            the USRBK contains data from
                                            BEFORE the suspension. It is set
                                            OFF during prep-for-stable
    0015   21 Bitstring    3 *              Reserved
    0018   24 Bitstring    4 *              Reserved
    001C   28 Bitstring    4 *              Reserved
              00000004       USRSIZE        (*-USRBK+7)/8 USRBK size in
                                            double words
              00000020       USRBSIZE       USRSIZE*8 USRBK size in bytes
              0000F000       USRtoVMD       X'F000' Convert USRBK to VMDBK
                                            address
              00000FFF       USRorVMD       X'0FFF' Test whether USRBK or
                                            VMDBK address

     USRBCBK DSECT
    Top of page

    Hex   Dec Type/Val   Lng Label (dup)    Comments
    ---- ---- --------- ---- -------------- --------
    0000    0 Structure      USRBCBK        SSI complex wide user attributes
    0000    0 Signed       1 USRBCLVL       USRBCBK level USRLEVEL although
                                            clearly there does not need to be
                                            strict relationship between
                                            levels of the broadcast (USRBCBK)
                                            block and the USRBK.
    0001    1 Signed       1 USRBCSF        USRBCBK request subfunction
              00000001       USRSFLON       1 USRSFLON User has logged onto
                                            source system (create USRBK)
              00000002       USRSFLOF       2 USRSFLOF User has logged off
                                            source system (delete USRBK)
              00000003       USRSFUPD       3 USRSFUPD Update USRBK with
                                            attached USRBK
              00000004       USRSFWRP       4 USRSFWRP Final wrap-up joining
                                            msg... HCPUSRJN has sent all USER
                                            data for this system.
              00000005       USRSFSYN       5 USRSFSYN Synch USRBK (2 systems
                                            have claimed ownership of a user,
                                            who really has it).
              00000006       USRSFLCC       6 USRSFLCC Logon cross check
    0002    2 Bitstring    1 USRBCFLG       Flags
              1... ....      USRCOUNT       B'10000000' USRCOUNT Ignore USRBK
                                            and update user counts only
              .1.. ....      USRRLOIN       B'01000000' USRRLOIN This update
                                            request is due to a guest
                                            relocating onto the sending
                                            system (only set by the Update
                                            USRBK subfunction)
              ..1. ....      USRRETRY       B'00100000' USRRETRY This request
                                            is a RETRY for a broadcast that
                                            got RC=4 & allows RETRY to be
                                            treated differently than FIRST
                                            TRY. Tested on USRSFLOF requests
    0003    3 Bitstring    1 *              Reserved
    0004    4 Signed       2 USRBCSLT       Slot number of request source
    0006    6 Bitstring    2 *              Reserved
    0008    8 Bitstring   16 USRUSRBK       Broadcast portion of USRBK
    0018   24 Bitstring   16 *              Reserved (for expansion of
                                            broadcast portion of the USRBK)
    0028   40 Character    1 USRBCEXT (0)   Request extension Redefined for
                                            use by various subfunctions
                 Next three fields are sent with requests to keep
                 node specific user counts fairly accurate.
    0028   40 Signed       4 USRUSRS        Count of users currently logged
                                            on (from SYSUSRS)
    002C   44 Signed       4 USRDIALD       Count of users currently dialed
                                            (from SYSDIALD)
    0030   48 Signed       4 USRLUCNT       Count of users currently
                                            connected via SNA (from SYSLUCNT)
              00000007       USRBCSZ        (*-USRBCBK+7)/8 Size of USRBCBK

USRBK Storage Layout | Top of page

    *** USRBK - SSI complex wide user attributes
    *
    *     +-------------------------------------------------------+
    *   0 |                       USRUSER                         |
    *     +-------------+------+------+---------------------------+
    *   8 |  USRPLXSL   |:LEVEL|:GFLAG|///////////////////////////|
    *     +-------------+------+------+------+--------------------+
    *  10 |         USRCHAIN          |:LFLAG|////////////////////|
    *     +---------------------------+------+--------------------+
    *  18 |///////////////////////////|///////////////////////////|
    *     +---------------------------+---------------------------+
    *  20
    *
    *** USRBK - SSI complex wide user attributes

    *** USRBCBK - SSI complex wide user attributes
    *
    *     +------+------+------+------+-------------+-------------+
    *   0 |:BCLVL|:BCSF |:BCFLG|//////|  USRBCSLT   |/////////////|
    *     +------+------+------+------+-------------+-------------+
    *   8 |                       USRUSRBK                        |
    *     |                                                       |
    *     +-------------------------------------------------------+
    *  18 |///////////////////////////////////////////////////////|
    *     |///////////////////////////////////////////////////////|
    *     +-------------------------------------------------------+
    *
    *** USRBCBK - SSI complex wide user attributes

    *** Overlay for USRBCEXT in USRBCBK
    *
    *     +---------------------------+---------------------------+
    *  28 |         USRUSRS           |         USRDIALD          |
    *     +---------------------------+---------------------------+
    *  30 |         USRLUCNT          | 34
    *     +---------------------------+
    *
    *** Overlay for USRBCEXT in USRBCBK

USRBK Cross Reference | Top of page

    Symbol         Dspl Value
    -------------- ---- -----
    USRorVMD       001C 00000FFF
    USRtoVMD       001C 0000F000
    USRAFSEC       0014 20
    USRBCed        0014 40
    USRBCEXT       0028
    USRBCFLG       0002
    USRBCLVL       0000
    USRBCSF        0001
    USRBCSLT       0004
    USRBCSZ        0030 00000007
    USRBRDSZ       000C 00000010
    USRBSIZE       001C 00000020
    USRCHAIN       0010
    USRCOUNT       0002 80
    USRDIALD       002C
    USRDISC        000B 40
    USRFESEC       000B 80
    USRGFLAG       000B
    USRLEVEL       000A
    USRLFLAG       0014
    USRLUCNT       0030
    USRLVLV1       000A 00000001
    USRMSGV2       000B 20
    USROLDBK       0014 04
    USRPLXSL       0008
    USRRETRY       0002 20
    USRRLOIN       0002 40
    USRSFLCC       0001 00000006
    USRSFLOF       0001 00000002
    USRSFLON       0001 00000001
    USRSFSYN       0001 00000005
    USRSFUPD       0001 00000003
    USRSFWRP       0001 00000004
    USRSIZE        001C 00000004
    USRUSER        0000
    USRUSRBK       0008
    USRUSRS        0028
    USRVESTL       0014 10
    USRVMDBK       0014 80

This information is based on z/VM 7.2.0 Last updated on 24 Jun 2020 at 09:31:30 EDT.
Copyright IBM Corporation, 1990, 2020