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.
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 or 64-bit |
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. |
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.
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.
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.
IBM® recommends that you use IXGOFFLD only when essential. The offloading process does entail some overhead and may degrade system logger performance.
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) | |
The parameters are explained as follows:
To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.
To code: Specify the RS-type address, or address in register (2)-(12), of a field.
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.
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
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.
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.
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.
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.
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:
Action: Do one of the following:
|
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:
|
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:
|
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:
|
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:
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:
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. |
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