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 (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 V5R2.0.
    Last updated on 12 Apr 2006 at 16:59:53 EDT.

    Copyright IBM Corporation, 1990, 2005