IXGQUERY — Query a log stream for information

The requirements for the caller are:

• The parameter list for this service must be addressable in the caller's primary address space.
• Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
• Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the ANSAREA parameter.

• The caller's output buffer (see BUFFER and BUFFER64) must be in the caller's primary address space and cannot be ALET-qualified.
• All storage areas specified must be in the same storage key as the caller.
• The caller cannot have any enabled, unlocked task (EUT) FRRs established.
• There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
• You can call any of the system logger services in either AMODE 31 or 64, but the parameter list and all other data addresses, with the exception of BUFFER64 must reside in 31-bit storage.

Before issuing the IXGQUERY 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.

None.

The IXGQUERY 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 IXGQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

REQUEST=LSCONNINFO|ZAILOCINFO

An optional keyword input that specifies the type of system logger related information being requested.

DEFAULT: LSCONNINFO

REQUEST=LSCONNINFO

The program requests to obtain information for a connected log stream.

STREAMTOKEN=streamtoken

A required input parameter that specifies the log stream token that was returned by the IXGCONN service.

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

CHECKCONNSTATUS=NO|YES

An optional keyword input that indicates whether or not only the connection status of the log is to be checked.

DEFAULT: NO

CHECKCONNSTATUS=NO

Indicates that full IXGQUERY processing is to be performed.

,BUFFER=buffer

A required output parameter that specifies the buffer into which the requested data are to be copied. The contents of the buffer are mapped by IXGQBUF.

The buffer cannot be ALET qualified.

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

,BUFFLEN=bufflen

A required input parameter that specifies the size of the buffer, identified by the BUFFER keyword, relative to different output versions:

If you want to see the GROUP information specified for the log stream, you must specify at least 200 bytes. If you specify less than 200 bytes, IXGQUERY will not return the GROUP information.

If the user-specified buffer is less than 72 bytes, the query request will fail and a specific return or reason code (IxgRetCodeError, IxgRsnCodeBadBufSize) will be returned.

If the user-specified buffer is greater than or equal to 88 bytes, version one information will be returned.

If the user-specified buffer is greater than or equal to 168 bytes, version two information will be returned.

If the user-specified buffer is greater than or equal to 200 bytes, version three information will be returned. If you want to see the GROUP information specified for the log stream, you must specify at least 200 bytes. If you specify less than 200 bytes, IXGQUERY will not return the GROUP information.

See IXGQBUF in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for details.

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

CHECKCONNSTATUS=YES

Indicates only the connection status of the log stream is to be checked.

REQUEST=ZAILOCINFO

The program requests to obtain information for the system logger ZAI parameter options pertaining to the IBM zAware server location.

,BUFFER64=xbuffer64

A required output parameter that specifies the buffer (starting on a full word boundary) into which the requested data are to be copied. The location of this buffer may be anywhere in 64-bit storage.

The contents of the buffer are mapped by IXGQZBUF.

The buffer cannont be ALET qualified.

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

,BUFFLEN=bufflen

A required input parameter that specifies the size of the buffer, identified by the BUFFER64 keyword, relative to different output versions:

• If the user-specified buffer is less than 96 bytes, the query request will fail and a specific return or reason code (IxgRetCodeError, IxgRsnCodeBadBufSize) will be returned.
• If the user specified buffer is greater than or equal to 96 bytes, then version one information will be returned.

See IXGQZBUF in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for details.

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

,ANSAREA=ansarea

A required input parameter of a virtual storage area, called the answer area. The ANSAREA contains additional error status when the IXGQUERY service generates an error return code. The format of the returned data is defined by the IXGANSAA mapping macro.

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

,ANSLEN=anslen

A required input parameter that contains the length in bytes of the virtual storage area provided for ANSAREA.

The length of the answer area is described by the IXGANSAA mapping macro.

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

,RETCODE=retcode

An optional output 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=0

,PLISTVER=1

,PLISTVER=2

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

• IMPLIED_VERSION, which is 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. Note that on the list form, the default will cause the smallest parameter list to be created.
• MAX, if you want the parameter list to be the largest size 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 forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 0, which supports all parameters except those referenced in higher versions.
• 1, which supports both the following parameters and parameters from version 0:
  • CHECKCONNSTATUS
  • REQUEST
• 2, which supports both the following parameters and parameters from version 0 and 1:
  • BUFFER64

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

,MF=S

,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)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

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 can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on 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 in the following order:

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

,list addr

The name of a storage area to contain the parameters.

,attr

An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.

,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.

The IXGQUERY service can issue abend X'1C5' with reason code X'0805'. This abend indicates an abend during system logger processing. If you receive this abend, reissue the request. If the problem persists, contact the IBM Support Center.

The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.

Example 1:

         IXGQUERY STREAMTOKEN=OTOKEN,                                  @
               BUFFER=QRYBUFF,                                         @
               BUFFLEN=QRYBUFF_LEN,                                    @
               ANSAREA=XANSAREA,                                       @
               ANSLEN=XANSLEN,                                         @
               RSNCODE=RSCODE
OTOKEN   DS    CL16                    Output Stream token
QRYBUFF  DS    CL(QBUF_LEN)            IXGQUERY data area
QRYBUFF_LEN DC A(QBUF_LEN)             IXGQUERY data length
XANSAREA DS    CL(ANSAA_LEN)           Logger answer area
XANSLEN  DC    A(ANSAA_LEN)            Answer area length
RSCODE   DS    F                       Reason code
         DSECT  ,
         IXGQBUF  ,                    The macro for IXGQUERY data
         IXGANSAA ,                    The answer area macro

Example 2:

         IXGQUERY REQUEST=ZAILOCINFO,                                  +
               BUFFER64=QRYZAIBUFF,                                    +
               BUFFLEN=QRYZAIBUFF_LEN,                                 +
               ANSAREA=XANSAREA,                                       +
               ANSLEN=XANSLEN,                                         +
               RSNCODE=RSCODE                                           
QRYZAIBUFF    DS  CL(IXGQZBUF_VERS1_LENGTH)      output buffer          
QRYZAIBUFF_LEN DC  A(IXGQZBUF_VERS1_LENGTH)       buffer size           
XANSAREA DS    CL(ANSAA_LEN)                     Logger answer area     
XANSLEN  DC    A(ANSAA_LEN)                      Answer area length     
RSCODE   DS    F                                 Reason code            
         DSECT ,                                                        
         IXGQZBUF ,                        The macro for IXGQUERY data  
         IXGANSAA ,                        The answer area mapping      
         IXGCON ,                          Return/reason codes