Programming Interface Information: This information is NOT intended to be
used as Programming Interfaces of z/VM.

IRCBK

Prolog
Control Block Contents
IRCBK DSECT
IRCVRGID DSECT
IRCVROBJ DSECT
Storage Layout
Cross Reference

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 V3R1.0.
Last updated on 30 Mar 2001 at 08:05:02 EDT.
Copyright IBM Corporation, 1990, 2001