USRBK Back to Index page
Control Block Contents 
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
 DESCRIPTION: SSI complex wide user attributes
 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.
 SERIALIZED : Deletion of the remote USRBKs is by MP defer.
              A USRBK pointer is only valid until the next
              loss of control.
              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 6.3.0 Last updated on 22 May 2013 at 13:56:16 EDT.
Copyright IBM Corporation, 1990, 2013