|
Programming Interface Information:
This information is NOT intended to be used as Programming Interfaces of z/VM. |
USRBK
Control Block Contents
USRBK DSECT
USRBCBK DSECT
Cross Reference (Contains links to field and bit definitions)
USRBK Prolog
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
USRBK DSECT
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
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
*** 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
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
Copyright IBM Corporation, 1990, 2011