IEEQEMCS — Query EMCS console

The requirements for the caller are:

The calling program may include mapping macro IEEZB887 which can be used to map the information that is returned in the buffer addressed by BUFPTR.

The calling program may also optionally include macro IEEZB888, which contains the declarations for the reason and return codes used by IEEQEMCS.

None.

Before issuing the IEEQEMCS macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

If REQUEST=FULL is specified, the service must read the data space of each console being reported on. Depending on the number of consoles, this can degrade performance of the service.

The IEEQEMCS macro is written as follows:

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IEEQEMCS macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

REQUEST=COUNT

REQUEST=SUMMARY

REQUEST=INFO

REQUEST=FULL

An optional parameter that indicates the type of information request. The default is REQUEST=COUNT.

REQUEST=COUNT

Return only the number of EMCS consoles meeting the search criteria.

REQUEST=SUMMARY

Return the number and names of the consoles that meet the search criteria.

,BUFPTR=bufptr

An optional input parameter that contains the address of the storage that the console display will be returned in. This field is only valid for a SUMMARY, INFO, or FULL request.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,BUFSIZE=bufsize

When BUFPTR=bufptr is specified, a required input parameter that contains the size of the storage buffer. This field is only valid when BUFPTR is specified.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

,TOKEN=token

An optional input parameter that returns the address of an 8-byte token used to return additional EMCS console information on subsequent calls if BUFSIZE is insufficient. This field is only valid for a SUMMARY, INFO, or FULL request.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,RECSIZE=recsize

When TOKEN is specified, RECSIZE is a required input parameter that contains the address of a 4-byte output area that will contain the recommended size of the output storage buffer if BUFSIZE is insufficient. This size represents only enough storage to store information about the one console represented by the TOKEN at the time of this call to IEEQEMCS. The RECSIZE contains data only when return code = is IEEQE_RC_NOSTOR.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

REQUEST=INFO

Return the number, names, and console data information, but no message data space statistics for the consoles meeting the search criteria.

REQUEST=FULL

Return the number, names, console data information, and message data space statistics for the consoles meeting the search criteria.

,STATUS=ACTIVE

,STATUS=INACTIVE

,STATUS=ALL

,STATUS=BACKLOG

,STATUS=ERR

An optional parameter that indicates the status of the EMCS consoles to be returned. The default is STATUS=ACTIVE.

,STATUS=ACTIVE

Return only active consoles.

,STATUS=INACTIVE

Return only inactive consoles.

,STATUS=ALL

Return both active and inactive consoles.

,STATUS=BACKLOG

Return consoles with unretrieved messages. The BKLG_NUM keyword can specify the minimum number of unretrieved messages a console must have to be returned.

,STATUS=ERR

Return only EMCS consoles in an error condition.

,BKLG_NUM=bklg_num

An optional input parameter that indicates the minimum number of unretrieved messages a console must have for it to be returned on a STATUS(BACKLOG) call.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

,CN=cn

An optional input parameter that indicates a console name to search for. The name include wildcard characters.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,SYS=sys

An optional input parameter that indicates the system name where the console was last activated. The system name may include wildcarded characters.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,KEY=key

An optional input parameter that indicates the KEY that was used to activate the console. The key name may include wildcard characters.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,AUTH=ANY

,AUTH=MASTER

,AUTH=SYS

,AUTH=IO

,AUTH=CONS

,AUTH=ALL

,AUTH=INFO

,AUTH=SYSONLY

,AUTH=IOONLY

,AUTH=CONSONLY

,AUTH=ALLONLY

,AUTH=INFOONLY

An optional parameter that indicates console command authority. The default is AUTH=ANY.

,AUTH=ANY

Return consoles with any authority.

,AUTH=MASTER

Return consoles with MASTER authority only.

,AUTH=SYS

Return consoles with SYS authority or MASTER authority.

,AUTH=IO

Return consoles with IO authority or MASTER authority.

,AUTH=CONS

Return consoles with CONS authority or MASTER authority.

,AUTH=ALL

Return consoles with IO, SYS, and CONS authority, or MASTER authority.

,AUTH=INFO

Return consoles with INFO, IO, SYS, CONS, or MASTER authority.

,AUTH=SYSONLY

Return consoles with SYS authority only.

,AUTH=IOONLY

Return consoles with IO authority only.

,AUTH=CONSONLY

Return consoles with CONS authority only.

,AUTH=ALLONLY

Return consoles with IO, SYS, and CONS authority only.

,AUTH=INFOONLY

Return consoles with INFO authority only.

,ATTR=ANY

,ATTR=YES

,ATTR=ROUT

,ATTR=HC

,ATTR=AUTO

,ATTR=AUTON

,ATTR=MN

,ATTR=NONE

,ATTR=INTIDS

,ATTR=UNKNIDS

An optional parameter that indicates routing attributes of the console. The default is ATTR=ANY.

,ATTR=ANY

Return consoles regardless of routing attributes.

,ATTR=YES

Return consoles that are receiving some type of undelivered messages.

,ATTR=ROUT

Return consoles receiving any routing codes.

,ATTR=HC

Return consoles receiving the hardcopy message set.

,ATTR=AUTO

Return consoles receiving AUTO(YES) messages.

,ATTR=AUTON

Return consoles not receiving AUTO(YES) messages.

,ATTR=MN

Return consoles receiving any type of MONITOR messages.

,ATTR=NONE

Return consoles with no routing attributes.

,ATTR=INTIDS

Return consoles receiving messages directed to console id zero.

,ATTR=UNKNIDS

Return consoles receiving messages directed to "unknown" console ids, such as consoles with one-byte id.

,DOM=ANY

,DOM=YES

,DOM=NORMAL

,DOM=ALL

,DOM=NONE

An optional parameter that indicates the DOM attribute of the consoles. The default is DOM=ANY.

,DOM=ANY

Return consoles regardless of their DOM attribute.

,DOM=YES

Return consoles that are receiving DOMs (either DOM(NORMAL) or DOM(NONE) consoles).

,DOM=NORMAL

Return consoles that are DOM(NORMAL) only.

,DOM=ALL

Return consoles that are DOM(ALL) only.

,DOM=NONE

Return consoles that are DOM(NONE) only.

,CONSCNT=conscnt

An optional input parameter that contains the address of a 4-byte output area that will contain the number of consoles meeting the specified criteria. The output area is only filled in for a COUNT request.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,RETCODE=retcode

An optional parameter into which the return code is to be copied from GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0.

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION

The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.

MAX

The largest size parameter list currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

If you can tolerate the size change, IBM® recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

1

The currently available parameters.

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 1

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

A required input parameter that specifies the macro form.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

IBM recommends that you use the modify and execute forms of IEEQEMCS in the following order:

• Use IEEQEMCS ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
• Use IEEQEMCS ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
• Use IEEQEMCS ...MF=(E,list-addr,NOCHECK), to execute the macro.

,list addr

The name of a storage area to contain the parameters. For MF=E and MF=M, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOCHECK

Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

None.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code.

Example

          .
          .
*         Initialize BUFSIZE and TOKEN
          L     REG9,INITSIZE
          ST    REG9,BUFSIZE
          MVC   TOKEN,INITTOKEN
          Set up addresses for IEEQEMCS
          LA    REG9,TOKEN
          ST    REG9,TOKENPTR
          LA    REG9,RECSZ
          ST    REG9,RECSZPTR
*         Get storage for output buffer
          STORAGE OBTAIN,LENGTH=BUFSIZE,ADDR=BUFPTR,COND=NO,LOC=ANY
*         Issue IEEQEMCS
DOQEMCS   EQU   *
          IEEQEMCS REQUEST=FULL,        Full info                      X
               STATUS=ALL,              Active or inactive consoles    X
               TOKEN=TOKENPTR,          Token                          X
               BUFPTR=BUFPTR,           Buffer address                 X
               BUFSIZE=BUFSIZE,         Buffer size                    X
               RECSIZE=RECSZPTR,        Recommended size               X
               RETCODE=RETCODE,         Return code                    X
               RSNCODE=RSNCODE,         Reason code                    X
               MF=(E,PLIST,COMPLETE)
*         Check return and reason codes from IEEQEMCS
          LA  REG14,IEEQE_RC_OK       Check if all consoles have been
          C   REG14,RETCODE             returned
          BE  ALLOK                   All consoles have been returned,
                                        so process them
          LA  REG14,IEEQE_RC_NOCONS   Check if no consoles have been
          C   REG14,RETCODE             returned
          BE  DONE                    No consoles met the filter, so   X
                                        exit
          LA  REG14,IEEQE_RC_NOSTOR   Check if the storage buffer could
          C   REG14,RETCODE             not hold all the consoles
          BNE ERROR                   No, there was some kind of error
          LA  REG14,IEEQE_RS_TOKSZCONS
          C   REG14,RSNCODE
          BE  SOMEOK                  The buffer was too small to hold X
                                      all the consoles meeting this    X
                                      filter, but IEEQEMCS put as many X
                                      consoles as possible in the      X
                                      buffer.  Process the consoles,   X
                                      and call IEEQEMCS again.
          LA  REG14,IEEQE_RS_TOKSZNOCONS
          C   REG14,RSNCODE
          BE  GETMORE                 The buffer was too small for     X
                                      even one console.  Free the      X
                                      buffer, get more storage, and    X
                                      call IEEQEMCS again.
          .
          .
          .
ALLOK     EQU *
*         Call PROCCONS to process the output buffer.
          LA   REG15,PROCCONS
          BALR REG14,REG15
*         There are no more consoles to process, so exit
          XR   REG15,REG15            Zero return code
          B    DONE
SOMEOK    EQU *
*         Call PROCCONS to process the consoles returned in
*         the output buffer.
          LA   REG15,PROCCONS
          BALR REG14,REG15
*         There is more console information to be retrieved, so
*         loop back to DOQEMCS.
          B    DOQEMCS
PROCCONS  EQU  *
*         Process consoles, and return to caller.
          ST   REG14,RETADDR
          L    HDRREG,BUFPTR          Load pointer to buffer in R2
          USING ECDM_HDR,HDRREG       This should be the ECDM header   X
                                      pointer
          L    SUMMREG,ECDM_HDR_SIZE  Load the size of the header
          AR   SUMMREG,HDRREG         Find the address of the summary  X
                                      block
          LH   REG15,ECDM_NENT        Load number of entries
          ST   REG15,NUMCONS
          USING ECDM_SUMM,SUMMREG
          USING ECDM_INFO,INFOREG
          USING ECDM_DSP,DSPREG
          USING ECDM_CNSW,CNSWREG
          USING ECDM_MSCP,MSCPREG
CONSLOOP  LTR  REG15,REG15            Is the number of entries zero?
          BZ   CONSDONE               Yes, exit loop
          L    REG8,ECDM_SUMM_SIZE    Put size of summ block in R10
          L    ENDREG,ECDM_SUMM_CONS_SIZE Put size of all blocks for   X
                                          this console in R11
          AR   REG8,SUMMREG           Get address of end of the        X
                                      summary block in R8 (work reg)
          AR   ENDREG,SUMMREG         Get address of the end of the    X
                                      console block in R11
BLKLOOP   LR   REG9,REG8              Copy work addr into R9
          SR   REG9,ENDREG            Are we at the end of the block?
          BZ   DOCONS                 Yes, do the actual console       X
                                      processing
          LA   REG9,ECDM_TYPE_INFO    Load the type of block in R9
          CH   REG9,0(REG8)           Is this an info block?
          BE   INFOBLK                Yes, branch to info block
          LA   REG9,ECDM_TYPE_DSP     Load the type of block in R9
          CH   REG9,0(REG8)           Is this a DSP block?
          BE   DSPBLK                 Yes, branch to data space block
          LA   REG9,ECDM_TYPE_MSCP    Load the type of block in R9
          CH   REG9,0(REG8)           Is this an MSCOPE block?
          BE   MSCPBLK                Yes, branch to MSCOPE block
          B    ERROR                  There was a bad type, so exit
INFOBLK   LR   INFOREG,REG8           Load INFO block addr into R4
          A    REG8,ECDM_INFO_SIZE    Increment size of block
          B    BLKLOOP                Find next block
DSPBLK    LR   DSPREG,REG8            Load DSP block addr into R5
          A    REG8,ECDM_DSP_SIZE     Increment size of block
          B    BLKLOOP                Find next block
MSCPBLK   LR   MSCPREG,REG8           Load MSCP block addr into R6
          A    REG8,ECDM_MSCP_SIZE    Increment size of block
          B    BLKLOOP                Find next block
DOCONS    EQU  *                      Console processing
*         At this point, do any processing on this individual
*         console that is necessary.
          .
          .
          .
*         Now, decrement the console count, and process the
*         next console in the buffer (if there is one).
          L    REG15,NUMCONS
          BCTR REG15,0                Decrement console count
          ST   REG15,NUMCONS
          LR   SUMMREG,REG8           Get address of next block in R3
          B    CONSLOOP               process next block
CONSDONE  L    REG14,RETADDR
          BR   REG14
          .
          .
          .
GETMORE   EQU  *
*         There was not enough storage to complete the request, so
*         get some more.
*         First delete the old storage
          STORAGE RELEASE,LENGTH=BUFSIZE,ADDR=BUFPTR
*         Now, since IEEQEMCS returned a recommended storage
*         size, move that amount into BUFSIZE, and obtain the
*         storage buffer.
          MVC   BUFSIZE,RECSZ
          STORAGE OBTAIN,LENGTH=BUFSIZE,ADDR=BUFPTR,COND=NO,LOC=ANY
*         Loop to issue IEEQEMCS again
          B     DOQEMCS
          .
          .
          .
ERROR     EQU   *
*         Do any error handling here
          .
          .
          .
DONE      EQU   *
*         IEEQEMCS found no more consoles, so release the output
*         buffer.
          STORAGE RELEASE,LENGTH=BUFSIZE,ADDR=BUFPTR
*         Now, continue on with other processing, etc.
          .
          .
          .
*         Declare constants and variables
BUFSIZE   DS    F
BUFPTR    DS    F
TOKENPTR  DS    F
RECSZPTR  DS    F
TOKEN     DS    CL8
RECSZ     DS    F
RETCODE   DS    F
RSNCODE   DS    F
NUMCONS   DS    F
RETADDR   DS    F
INITSIZE  DC    XL4'300'
INITTOKEN DC    XL8'0'
*         IEEQEMCS parameter list
          DS    0F
          IEEQEMCS MF=(L,PLIST)
*         IEEQEMCS return code equates
          IEEZB888
*         Include mapping of ECDM blocks
          IEEZB887
          END