|
Programming Interface Information:
This information is NOT intended to be
used as Programming Interfaces of z/VM. |
IRCBK
Control Block Contents
IRCBK DSECT
IRCVRGID DSECT
IRCVROBJ DSECT
Cross Reference (Contains links to field and bit definitions)
IRCBK Prolog
NAME : HCPIRCBK
DESCRIPTION: *IDENT Resource Communication block
DSECT : IRCBK
FUNCTION : This DSECT maps the data exchanged between the
*IDENT system service and an authorized
resource.
LOCATED BY : Registers
CREATED BY : HCPEXC when building a request for a server
HCPEXE when processing a deliver for a request
from a different system
HCPIDS when getting a reply buffer for a
server
DELETED BY : HCPEXC when completing the function
HCPEXD when handling a return from the server
for the target system
HCPEXE on an error in deliver processing
HCPIDS on an IUCV SEND error
HCPIDS when a message-complete interruption is
received.
SERIALIZED : Task ownership
COMMENTS :
This control block is conceptually one piece of data *
mapped by three structures. There is a fixed-length *
portion and two variable-length portions, all described *
in greater detail below. In storage, these must be *
adjacent, and in the order: *
1) Fixed-length area *
2) Supplementary GID information *
3) Object token information. *
*
The fixed-length section is set up as containing a header *
and function-specific sections. The header contains only *
general control block information, and is frozen at the *
defined length. CHANGING THE LENGTH OF THE HEADER SECTION *
WILL RESULT IN MAKING THE CONTROL BLOCK INCOMPATIBLE WITH *
PREVIOUS RELEASES OF THE BLOCK. *
The function-specific sections are different, but the *
length of that section is determined by the length of *
the longest of the set of function-specific sections. *
A field in the header contains this execution-time- *
calculated length so that fields can be added to the *
function-specific section in future releases while still *
allowing the new blocks to coexist with the old ones. *
*
A variable-length section may contain no data; in this *
case, the length field contains the length of itself *
alone (a 4-byte length field, for example, would contain *
the value '4' if the length of the corresponding data *
field is zero). *
*
For future expansion, function-specific fields can be *
added to the function-specific area, or other *
function-specific sections can be added. Variable-length *
sections can be added after the last variable length *
section. *
*
*
Function type EXEC *
------------------ *
The IRCBK can reside in free storage, or in a frame *
delivered to exec processing by the CP Application *
Mailbox. When the exec function originally acquires an *
IRCBK, it does so from free storage. If the request *
is transmitted to a remote system, the CP Application *
Mailbox on that system delivers a page to the exec *
function which contains a copy of that IRCBK. That *
copy is used and the information returned to the *
originating system. *
*
In addition, a two-way IUCV SEND is done to the server. *
The reply buffer specified on that SEND is another copy *
of the IRCBK, gotten from free storage.
IRCBK Control Block Content
IRCBK DSECT
Hex Dec Type/Val Lng Label (dup) Comments
---- ---- --------- ---- -------------- --------
0000 0 Structure IRCBK *IDENT Resource Communication
block
Header
0000 0 Dbl-Word 8 IRCHDR (0) Ensure doubleword boundary
0000 0 Bitstring 1 IRCTYPE Type of communication with the
resource.
0001 1 Bitstring 3 * Reserved for IBM use
0004 4 Signed 4 IRCTOTLN Total length (unsigned), in
bytes, of the block, including
the variable-length fields.
0008 8 Signed 4 IRCFFXLN Length (unsigned) in bytes of the
longest of the fixed-length
portions of the function-specific
sections. This field can be set
to IRCFIXLN by the creator of the
block only.
000C 12 Character 4 * Reserved for IBM use
00000010 IRCHDRLN (*-IRCHDR) Length of the IRCBK
header.
0010 16 Signed 4 IRCFNSPC (0) Beginning of the type-specific
section.
Information for exec() communication.
0010 16 Signed 4 IRCEX (0) Beginning of the type-specific
area for exec() communication.
0010 16 Bitstring 1 IRCIDFLG ID information flag
1... .... IRCSTUID X'80' Indicates that the UID
should be changed.
.1.. .... IRCSTGID X'40' Indicates that the GID
should be changed
0011 17 Character 3 * Reserved for IBM use
0014 20 Signed 4 * Reserved for IBM use.
0018 24 Signed 4 IRCEUID Effective UID. This is the user's
effective UID at the time the
request is made.
001C 28 Signed 4 IRCEGID Effective GID. This is the user's
effective GID at the time the
request is made.
0020 32 Signed 4 IRCSRET Return code from the server. If
this value indicates anything
other than a successful request
(the field contains 0), bits zero
and one of IDFLG are ignored and
an error is returned to the
issuer of DIAGNOSE X'280'.
0024 36 Signed 4 IRCSREAS Reason code from the server. CP
passes this value to the issuer
of DIAGNOSE X'280'.
0028 40 Signed 4 IRCNUID New UID. This is the UID to which
the user's eUID and ssUID must be
set.
002C 44 Signed 4 IRCNGID New GID. This is the GID to which
the user's eGID and ssUID must be
set.
Reset location counter.
00000020 IRCFIXLN (*-IRCFNSPC) Length of the
longest of the function-specific
sections.
Mapping of variable area IRCVAREX.
There are two structures that start in the area beginning at IRCVAREX.
One structure maps the supplementary GID length and data, and the other
maps the object token length and data. Both of these sets of data are
required, and they must be in the following order: 1) Supplementary GID
information 2) Object token information.
Supplementary GID data
Note that this mapping is not part of the IRCBK DSECT and must be
properly based in order to be used. The supplementary GID data length
must immediately follow the last field in the function-specific section
of the IRCEXEC function. The proper calculation is: (address of IRCBK +
length of header section + length of function-specific section) or
(IRCBK @ + IRCHDRLN + IRCFFXLN).
IRCVRGID DSECT
Hex Dec Type/Val Lng Label (dup) Comments
---- ---- --------- ---- -------------- --------
0000 0 Structure IRCVRGID *IDENT Resource Communication
block
0000 0 Signed 4 IRCSGLN Length (unsigned) in bytes of the
supplementary GID data, including
the length field itself. This
length must be equivalent to an
integral number of fullwords, and
must be at least equal to
IRCSGMN.
00000004 IRCSGMN L'IRCSGLN Minimum length
permitted to be specified in
IRCSGMN. This minimum represents
a IRCSGIDS length of zero.
0004 4 Signed 4 IRCSGIDS (0) Supplementary GIDs
Object token data
Note that this mapping is not part of the IRCBK DSECT and must be
properly based in order to be used. The object length must immediately
follow the last byte of the variable-length section that maps the
supplementary GID data. The proper calculation is: (address of IRCBK +
length of header section + length of function-specific section + length
of supplementary GID data) or (IRCBK @ + IRCHDRLN + IRCFFXLN +
IRCSGLN).
IRCVROBJ DSECT
Hex Dec Type/Val Lng Label (dup) Comments
---- ---- --------- ---- -------------- --------
0000 0 Structure IRCVROBJ *IDENT Resource Communication
block
0000 0 Signed 4 IRCOBJLN Length (unsigned) in bytes of the
object token, including the
length field itself. Must be at
least IRCOBJMN.
00000004 IRCOBJMN L'IRCOBJLN Minimum length
permitted to be specified in
IRCOBJLN. This minimum represents
a IRCOBJTK length of zero.
0004 4 Bitstring 1 IRCOBJTK (0) Object token. The object token
represents the object for which
the UID/GIDs are being queried.
For example, this could represent
a setid file residing in the byte
file system.
IRCBK Storage Layout
*** IRCBK - *IDENT Resource Communication block
*
* +------+--------------------+---------------------------+
* 0 |:TYPE |////////////////////| IRCTOTLN |
* +------+--------------------+---------------------------+
* 8 | IRCFFXLN |///////////////////////////|
* +---------------------------+---------------------------+
*
*** IRCBK - *IDENT Resource Communication block
*** Overlay for IRCFNSPC in IRCBK
*
* +------+--------------------+---------------------------+
* 10 |:IDFLG|////////////////////|///////////////////////////|
* +------+--------------------+---------------------------+
* 18 | IRCEUID | IRCEGID |
* +---------------------------+---------------------------+
* 20 | IRCSRET | IRCSREAS |
* +---------------------------+---------------------------+
* 28 | IRCNUID | IRCNGID |
* +---------------------------+---------------------------+
* 30
*
*** Overlay for IRCFNSPC in IRCBK
*** IRCVRGID - *IDENT Resource Communication block
*
* +---------------------------+
* 0 | IRCSGLN |
* +---------------------------+
*
*** IRCVRGID - *IDENT Resource Communication block
*** IRCVROBJ - *IDENT Resource Communication block
*
* +---------------------------+
* 0 | IRCOBJLN |
* +---------------------------+
*
*** IRCVROBJ - *IDENT Resource Communication block
IRCBK Cross Reference
Symbol Dspl Value
-------------- ---- -----
IRCEGID 001C
IRCEUID 0018
IRCEX 0010
IRCFFXLN 0008
IRCFIXLN 002C 00000020
IRCFNSPC 0010
IRCHDR 0000
IRCHDRLN 000C 00000010
IRCIDFLG 0010
IRCNGID 002C
IRCNUID 0028
IRCOBJLN 0000
IRCOBJMN 0000 00000004
IRCOBJTK 0004
IRCSGIDS 0004
IRCSGLN 0000
IRCSGMN 0000 00000004
IRCSREAS 0024
IRCSRET 0020
IRCSTGID 0010 40
IRCSTUID 0010 80
IRCTOTLN 0004
IRCTYPE 0000
This information is
based on z/VM V4R1.0.
Last updated on 6 Jun 2001 at 11:42:08 EDT.
Copyright IBM Corporation, 1990, 2001