IXGOFFLD — Initiate offload 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.

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

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:

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.

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.