IXGOFFLD — Initiate offload to DASD log data sets

Description

The IXGOFFLD macro allows the caller to intiate an offload of log data from the coupling facility structure for coupling facility log streams and from local storage buffers for DASD-only log streams to DASD log data sets.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state. Any PSW key
Dispatchable unit mode: Task
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 31-bit Start of changeor 64-bitEnd of change
ASC mode: Primary or access register (AR)
Interrupt status: Enabled for I/O and external interrupts

The caller's parameter list must be resident in the caller's primary address space.

All storage areas specified must be in the same storage key as the caller.

Locks: No locks may be held.
Control parameters: None.

Programming requirements

  • Before issuing this request, the caller must have issed IXGCONN to connect to the log stream. The caller must specify specify AUTH=WRITE on the IXGCONN request.
  • The current primary address space must be the same as the HOME address space at the time you issued the IXGCONN macro.
  • 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.

Restrictions

All storage areas specified must be in the same storage key as the caller. Storage areas must exist in the caller's primary address space.

Input register information

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

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code, if register 15 contains a non-zero return code
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system

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.

Performance implications

IBM® recommends that you use IXGOFFLD only when essential. The offloading process does entail some overhead and may degrade system logger performance.

Syntax

The IXGOFFLD macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
One or more blanks must precede IXGOFFLD.
   
IXGOFFLD  
   
One or more blanks must follow IXGOFFLD.
   
STREAMTOKEN=streamtoken streamtoken: RS-type address or address in register (2) - (12).
   
,ANSAREA=ansarea ansarea: RS-type address or address in register (2) - (12).
   
,ANSLEN=anslen anslen: RS-type address or address in register (2) - (12).
   
  ,RETCODE=retcode retcode: RS-type address or register (2) - (12).
   
  ,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).
   
  ,PLISTVER=IMPLIED_VERSION Default: PLISTVER=IMPLIED_VERSION
  ,PLISTVER=MAX  
  ,PLISTVER=0  
   
  ,MF=S Default: MF=S
  ,MF=(L,list addr) list addr: RS-type address or register (1) - (12).
  ,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)  
   

Parameters

The parameters are explained as follows:

name
An optional symbol, starting in column 1, that is the name on the IXGOFFLD macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
STREAMTOKEN=streamtoken
A required input parameter that specifies the log stream token that was returned on the IXGCONN service.

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

,ANSAREA=ansarea
A required input parameter of a virtual storage area, called the answer area. The ANSAREA contains additional error status when the IXGOFFLD 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
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.
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.

ABEND codes

1C5 Ixg_Abend_Code - A System Logger abend has occurred.
Reason Code (Hex)
Explanation
xxxx085F
IxgRsnCodePercToRequestor -

Explanation: Environment error. Percolation to the service requestor's task occurred because of an abend during system logger processing. Retry was not allowed.

Action: Issue the request again. If the problem persists, contact the IBM Support Center.

Return and reason codes

When the IXGOFFLD macro returns control to your program:
  • GPR 15 (and retcode, if you coded RETCODE) contains a return code.
  • When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded RSNCODE) contains a reason code.
00
IxgRetCodeOk - Successful completion
04
IxgRetCodeWarning - The request was processed successfully, however a warning condition was encountered.
08
IxgRetCodeError - An error has been encountered. The associated reason code provides more information.
0C
IxgRetCodeCompError - A system logger component error has been encountered.

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.

Table 1. Return and Reason Codes for the IXGOFFLD Macro
Return Code Reason Code Meaning and Action
00 xxxx0000 IxgRsnCodeOk -

Explanation: Request processed successfully.

08 xxxx0801 IxgRsnCodeBadParmlist -

Explanation: Program error. The parameter list is not valid. Either the parameter list storage is inaccessible, or the version of the macro used was not valid.

Action: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request, and that the macro version is correct. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.

08 xxxx0802 IxgRsnCodeXESError -

Explanation: System error. A severe cross-system extended services (XES) error has occurred.

Action: In the answer area mapped by IXGANSAA, see ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.

08 xxxx0806 IxgRsnCodeBadStmToken -
Explanation: Program error. One of the following occurred:
  • The stream token was not valid.
  • The specified request was issued from an address space other than the connector's address space.
Action: Do one of the following:
  • Make sure that the stream token specified is valid.
  • Ensure that IXGOFFLD requests were issued from the connector's address space.
08 xxxx080A IxgRsnCodeRequestLocked -

Explanation: Program error. The program issuing the request is holding a lock.

Action: Ensure that the program issuing the request is not holding a lock.

08 xxxx0814 IxgRsnCodeNotAvailForIPL -

Explanation: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.

Action: See the explanation for system messages issued during system logger initialization.

08 xxxx0815 IxgRsnCodeNotEnabled -

Explanation: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.

Action: Make sure the program issuing the request is enabled for I/O and external interrupts.

08 xxxx0816 IxgRsnCodeBadAnslen -

Explanation: Program error. The answer area length (ANSLEN parameter) is not large enough. The system logger returned the required size in the Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro.

Action: Reissue the request, specifying an answer area of the required size.

08 xxxx0817 IxgRsnCodeBadAnsarea -

Explanation: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This might occur after the system logger address space has terminated.

Action: Specify storage that is in the callers primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.

08 xxxx0819 IxgRsnCodeSRBMode -

Explanation: Program error. The calling program is in SRB mode, but task mode is the required dispatchable unit mode for this system logger service.

Action: Make sure the calling program is in task mode.

08 xxxx081C IxgRsnCodeNotAuthFunc -

Explanation: Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete, write, offload or update data. You cannot write, delete, update or offload data when connected with read authority.

Action: Issue the IXGCONN service with AUTH=WRITE authority and then reissue this request.

08 xxxx082D IxgRsnCodeExpiredStmToken -

Explanation: Environment error. The stream token is no longer valid because the connector has been disconnected.

Action: Reconnect to the logstream before issuing any functional requests.

08 xxxx0840 IxgRsnCodeBadVersion -

Explanation: Environment error. The parameter list passed to the service routine has an incorrect version indicator.

Action: Make sure that the level of MVS™ executing the request and the macro library used to compile the invoking routine are compatible.

08 xxxx0861 IxgRsnCodeRebuildInProgress -

Explanation: Environment error. No requests can be processed for this log stream because a coupling facility structure rebuild is in progress for the structure associated with this log stream.

Action: Listen for ENF signal 48 that will indicate one of the following:
  • The log stream is available because the rebuild completed successfully. Reissue the request.
  • The rebuild failed and the log stream is not available.
08 xxxx0862 IxgRsnCodeXESPurge -

Explanation: Environment error. An cross-system extended services (XES) request has been purged due to rebuild processing.

Action: Listen for ENF signal 48 that will indicate one of the following:
  • The log stream is available because the rebuild completed successfully. Reissue the request.
  • The rebuild failed and the log stream is not available.
08 xxxx0863 IxgRsnCodeStructureFailed -

Explanation: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.

Action: Listen for ENF signal 48 that will indicate one of the following:
  • The log stream is available because the rebuild completed successfully. Reissue the request.
  • The rebuild failed and the log stream is not available.
08 xxxx0864 IxgRsnCodeNoConnectivity -

Explanation: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to rebuild the log stream in another coupling facility or the log stream will be disconnected.

Action: Listen for ENF signal 48 that will indicate one of the following:
  • The log stream is available because the rebuild completed successfully. Reissue the request.
  • The rebuild failed and the log stream is not available.
  • The log stream has been disconnected from this system.

If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.

08 xxxx0890 IxgRsnCodeAddrSpaceNotAvail -

Explanation: System error. The system logger address space failed and is not available.

Action: Do not issue system logger requests.

08 xxxx0891 IxgRsnCodeAddrSpaceInitializing -

Explanation: System error. The system logger address space is not available because it is IPLing.

Action: Listen for ENF signal 48, which will indicate when the system logger address space is available. When it's available, reconnect to the log stream, then reissue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.

08 xxxx08DF IxgRsnCodeOffLoadFlushError -

Explanation: System error. The flush service called by IXGOFFLD encountered a XES error.

Action: Examine the answer area, which contains more detailed information about the error.

0C xxxx0000 Equate Symbol: IxgRetCodeCompError
Explanation: User or System error. One of the following occurred:
  • You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
  • System logger component error occurred.

Action:If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.

Example

Issue IXGOFFLD to initiate offload processing for a log stream.
         IXGOFFLD                                                      @
               STREAMTOKEN=OTOKEN,                                     @
               ANSAREA=XANSAREA,                                       @
               ANSLEN=XANSLEN,                                         @
               RSNCODE=RSCODE
OTOKEN   DS    CL16                    Output Stream token
XANSAREA DS    CL(ANSAA_LEN)           Logger answer area
XANSLEN  DC    A(ANSAA_LEN)            Answer area length
RSCODE   DS    F                       Reason code
         DSECT  ,
         IXGANSAA ,                   The answer area macro