IXGWRITE — Write log data to a log stream

Description

Use the IXGWRITE macro to allow a program to write a log block to a log stream. IXGWRITE returns a unique identifier for each log block written to the log stream.

System logger generates a time stamp for each log block as they are received from applications issuing IXGWRITE and writes the blocks to the log stream in that order. Applications that imbed their own time stamps in log blocks will find that the blocks may not be in application-generated time stamp order, especially if multiple applications are writing to a log stream simultaneously. In order to ensure chronological order of log blocks by application-generated time stamp, applications should provide their own serialization on the log stream.

For information on using the system logger services and the LOGR policy, see z/OS MVS Programming: Assembler Services Guide, which also includes information about related macros IXGCONN, IXGBRWSE, IXGINVNT, IXGDELET, and IXGQUERY.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with any PSW key. The caller must be supervisor state with any system (0-7) PSW key to either invoke this service in SRB mode or to use the MODE=SYNCEXIT keyword.
Dispatchable unit mode:	Task or SRB
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.
Locks:	No locks held.
Control parameters:	All control parameters must be in the primary address space with the following exceptions: The ECB should be addressable from the home address space. Any parameter area that is explicitly ALET-qualified as allowed by the input parameter (for example, the area referenced by the BUFFER parameter when the BUFFALET parameter is specified) must be in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). All storage areas specified must be in the same storage key as the caller, with the following exception: The parameter area is explicitly storage key qualified as allowed by the input parameters (example: the area referenced by the BUFFER parameter when the BUFFKEY parameter is also specified).

Programming requirements

Before issuing IXGWRITE, you must put the data you wish to write to the log stream into a buffer specified on the BUFFER parameter. IXGWRITE will then write this buffer to the log stream as a log block.
The current primary address space from which you issue the IXGWRITE service must be the same as the primary address space at the time you issued the IXGCONN request.
The parameter list for this service must be addressable in the caller's primary address space.
The calling program must be connected to the log stream with write authority through the IXGCONN service.
IXGWRITE cannot be issued if the connection is an import connection (IMPORTCONNECT=YES on the IXGCONN service). The IXGWRITE service must be issued under a write connection (IMPORTCONNECT=NO, which is the default).
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.
When coding the MODE=SYNCECB and ECB parameters, you must ensure that:
- The virtual storage area specified for the ECB resides on a full word boundary.
- You initialize the ECB field to zero.
- The ECB resides in either the common or home address space storage at the time the IXGWRITE request is issued.
- The storage used for output parameters, such as ANSAREA, RETBLOCKID, and TIMESTAMP, are accessible by both the IXGWRITE invoker and the ECB waiter.
When coding the MODE=SYNCEXIT parameter, you must ensure that the storage used for output parameters, such as ANSAREA, RETBLOCKID, and TIMESTAMP, are accessible by both the IXGWRITE invoker and the completion exit routine.

Restrictions

All storage areas specified on this macro must be in the same storage key as the caller's storage key, with the exception of the BUFFKEY parameter.
Storage areas that are not ALET-qualified must exist in the caller's primary address space. The ECB should be addressable from the home address space.
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 excption of BUFFER64 must reside in 31-bit storage.

Input register information

Before issuing the IXGWRITE 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
1: Used as a work register by the system
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

None.

Syntax

The standard form of the IXGWRITE macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGWRITE.

IXGWRITE

␢	One or more blanks must follow IXGWRITE.

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BUFFER=`buffer`	`buffer`: RS-type address or register (2) - (12).
BUFFER64=`buffer64`	`buffer64`: RS-type address or register (2) - (12).

,BLOCKLEN=`blocklen`	`blocklen`: RS-type address or register (2) - (12).

,RETBLOCKID=`retblockid`	`retblockid`: RS-type address or register (2) - (12).

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

,BUFFKEY=`buffkey`	`buffkey`: RS-type address or register (2) - (12).
,BUFFKEY=*	Default: BUFFKEY=*

,BUFFALET=`buffalet`	`buffalet`: RS-type address or register (2) - (12). Default: BUFFALET=0

,TIMESTAMP=`timestamp`	`timestamp`: RS-type address or register (2) - (12). Default: NO_TIMESTAMP

MODE=SYNC	Default: MODE=SYNC
MODE=ASYNCNORESPONSE
MODE=SYNCECB
MODE=SYNCEXIT

,REQDATA=`reqdata`	`reqdata`: RS-type address or register (2) - (12).

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`
,PLISTVER=0
,PLISTVER=1

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: 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)

Parameters

The parameters are explained as follows:

,STREAMTOKEN=streamtoken

Specifies the name (or address in a register) of a required 16-byte input field containing the token for the log stream that you want to write to. The stream token is returned by the IXGCONN service at connection to the log stream.

,BUFFER=buffer

,BUFFER64=buffer64

Specifies the field name (or address in a register) of the data to be written to the log.

BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.

The BUFFER and BUFFER64 parameters are mutually exclusive.

,BLOCKLEN=blocklen

Specifies the name (or address in a register) of a 4-byte input field that contains the length in bytes of the log block you are writing to the log stream.

The value of BLOCKLEN must be between 1 and the value for MAXBUFSIZE.

RETBLOCKID=retblockid

Specifies the name (or address in a register) of a 8-byte output field where IXGWRITE returns the unique block identifier for the log block written to the log stream.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

BUFFALET=buffalet

Specifies the name (or address in a register) of a 4-byte input field specifying the access list entry table (ALET) to be used to access the buffer specified on the BUFFER or BUFFER64 keyword. If the buffer is ALET-qualified, the ALET must index a valid entry on the task's dispatchable unit access list (DUAL) or specify a SCOPE=COMMON data space. An ALET that indexes the system logger PASN-AL list will not work.

The default is 0, which means that the buffer is in the calling program's primary address space.

BUFFKEY=buffkey

Specifies the name (or address in a register) of a 4-byte input field specifying the storage key for the buffer specified on the BUFFER or BUFFER64 parameter.

If the caller is running in problem state, the caller's PSW key and the key specified in the BUFFKEY parameter must match.

If the caller is running in supervisor state, specify any syntactically valid (0 through 15) key on the BUFFKEY parameter.

If you omit the BUFFKEY parameter, the default used is the PSW key of the caller.

TIMESTAMP=timestamp

Specifies the name (or address in a register) of a 16-byte output field where the Greenwich mean time and local time stamps associated with the requested log block are returned when the write request is successful. Both time stamps will be in time of day (TOD) clock format.

MODE=SYNC

MODE=ASYNCNORESPONSE

MODE=SYNCECB

MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=ASYNCNORESPONSE: Specifies that the request process asynchronously. The caller is not notified when the request completes and the answer area (ANSAREA) fields will not contain valid information.
To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB keyword is posted when the request completes. The ECB keyword is required with MODE=SYNCECB.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. If the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to RETBLOCKID and TIMESTAMP.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

,REQDATA=reqdata

Specifies the name (or address in a register) of a 8-byte input field containing user-defined data to pass to the complete exit. REQDATA is only valid with the MODE=SYNCEXIT parameter.

,ECB=ecb

Specifies the name (or address in a register) of a 4-byte input field that contains the event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space where the IXGWRITE service was issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

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 specifically referenced in higher versions.
1, which supports both the following parameters and parameters from version 0:
- REQDATA

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0 or 1

,RETCODE=retcode

Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.

,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

None.

Return and reason codes

When IXGWRITE macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.

Note: A program invoking the IXGWRITE service may indicate through the MODE parameter that requests which can not be completed synchronously should have control returned to the caller prior to completion of the request. When the request does complete, the invoker will be notified and the return and reason codes are in the answer area mapped by IXGANSAA.

The IXGCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:

00: IXGRSNCODEOK - Successful completion.
04: IXGRSNCODEWARNING - 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 IXGWRITE Macro
Return Code	Reason Code	Meaning and Action
00	xxxx0000	Equate Symbol: IxgRsnCodeOk Explanation: Request processed successfully.
04	xxxx0401	Equate Symbol: IxgRsnCodeProcessedAsynch Explanation: Program error. The program specified MODE=SYNCECB and the request must be processed asynchronously. Action: Wait for the ECB specified on the ECB parameter to be posted, indicating that the request is complete. Check the ANSAA_ASYNCH_RETCODE and ANSAA_ASYNCH_RSNCODE fields, mapped by IXGANSAA, to determine whether the request completed successfully.
04	xxxx0405	Equate Symbol: IxgRsnCodeWarningLossOfData Explanation: Environment error. Returned for READCURSOR, START OLDEST and RESET OLDEST requests. This condition occurs when a system and coupling facility fail and not all of the log data in the log stream could be recovered. For READCURSOR: A log block has been returned, but there may be log blocks permanently missing between this log block and the one previously returned. For START OLDEST and RESET OLDEST: The oldest log blocks in the log stream may be permanently missing, the browse cursor is set at the oldest available log block. Action: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
04	xxxx0407	Equate Symbol: IxgRsnCodeConnPossibleLossOfData Explanation: Environment error. The request was successful, but there may be log blocks permanently missing between this log block and the one previously returned. This condition occurs when a system or coupling facility fails and not all of the data in the log stream could be recovered. Action: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
04	xxxx0408	Equate Symbol: IxgRsnCodeDsDirectoryFullWarning Explanation: Environment error. The request was successful, but the log streams DASD data set directory is full. System logger cannot offload any further data from the coupling facility structure to DASD. The system logger will continue to process IXGWRITE requests until this log streams portion of the coupling facility structure becomes full. Action: Either delete enough data from the log stream to free up space in the log streams data set directory so that offloading can occur or disconnect from the log stream.
04	xxxx0409	Equate Symbol: IxgRsnCodeWowWarning Explanation: Environment error. The request was successful, but an error condition was detected during a previous offload of data. System logger might not be able to offload further data. System logger will continue to process IXGWRITE requests only until the interim storage for the log stream is filled. (Interim storage is the coupling facility for a coupling facility log stream and local storage buffers for a DASD-only log stream.) Action: Do not issue any further requests for this log stream and disconnect. Connect to another log stream. Check the system log for message IXG301I to determine the cause of the error. If you cannot fix the error, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
04	0000040A	Equate Symbol: IxgRsnCodeDuplexFailureWarning Explanation: Environment error. The request was successful, but the system logger was unable to duplex log data to staging data sets, even though the log stream definition requested unconditional duplexing to staging data sets by specifying the log stream attributes: STG_DUPLEX=YES, DUPLEXMODE=UNCOND, or STG_DUPLEX=YES,DUPLEXMODE=DRXRC. When DUPLEXMODE=UNCOND is specified, but Logger was unable to obtain a staging data set to duplex the log data. Therefore, the Logger duplexing is being done in local buffers (data space). When DUPLEXMODE=DRXRC is specified for a logstream and being used for (non-local) disaster recovery duplexing, if the internal buffers used for asynchronous buffering of the log blocks become full. Meaning the internal buffers became full before at least one of the full buffers could be written to the staging data set. Action: For DUPLEXMODE=UNCOND, if duplexing to staging data sets is required, disconnect from this log stream and connect to a log stream that can be duplexed to staging data sets. For DUPLEXMODE=DRXRC, if duplexing to a DRXRC-type staging data sets is required, then cause the log data to be offload to the log stream secondary storage (offload data sets) and then continue writing to the log stream.
08	xxxx0801	Equate Symbol: IxgRsnCodeBadParmlist Explanation: Program error. The parameter list could not be accessed. Action: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx0802	Equate Symbol: IxgRsnCodeXESError Explanation: System error. A severe cross-system extended services (XES) error has occurred. Action: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
08	xxxx0803	Equate Symbol: IxgRsnCodeBadBuffer Explanation: Program error. The virtual storage area specified on the BUFFER or BUFFER64 parameter is not addressable. Action: Ensure that the storage area specified on the BUFFER or BUFFER64 parameter is accessible to system logger for the duration of the request. If the BUFFKEY parameter is specified, make sure it contains a valid key associated with the storage area. If BUFFKEY is not used, ensure that the storage is in the same key as the program at the time the logger service was requested. The storage must be addressable in the caller's primary address space.
08	xxxx0806	Equate Symbol: 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 the request was issued from the connector's address space.
08	xxxx0809	Equate Symbol: IxgRsnCodeBadWriteSize Explanation: Program error. The size of the log block specified in the BLOCKLEN parameter is not valid. The value for BLOCKLEN must be greater than zero and less than or equal to the maximum buffer size (MAXBUFSIZE) defined in the LOGR policy for the structure associated with this log stream. Action: Ensure that the value specified on the BLOCKLEN parameter is greater than 0 and less than or equal to the MAXBUFSIZE which is returned on the log stream connect request.
08	xxxx080A	Equate Symbol: 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	Equate Symbol: 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	Equate Symbol: 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	Equate Symbol: 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: Re-issue the request, specifying an answer area of the required size.
08	xxxx0817	Equate Symbol: IxgRsnCodeBadAnsarea Explanation: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated. Action: Specify storage that is in the caller's 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	xxxx0818	Equate Symbol: IxgRsnCodeBadBlockidStor Explanation: Program error. The storage area specified by BLOCKID cannot be accessed. Action: Ensure that the storage area is accessible to system logger for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx081C	Equate Symbol: IxgRsnCodeNotAuthFunc Explanation: Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete or write data. You cannot write or delete data when connected with read authority. Action: Issue the IXGCONN service with AUTH=WRITE authority and then re-issue this request.
08	xxxx082D	Equate Symbol: IxgRsnCodeExpiredStmToken Explanation: Environment error. The stream token is no longer valid because the connector has been disconnected. Action: Connect to the log stream again before issuing any functional requests.
08	xxxx0837	Equate Symbol: IxgRsnCodeBadTimestamp Explanation: Program error. The storage area specified by TIMESTAMP cannot be accessed. Action: Ensure that the storage area is accessible to the system logger service for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx083D	Equate Symbol: IxgRsnCodeBadECBStor Explanation: Program error. The ECB storage area was not accessible to the system logger. Action: Ensure that the storage area is accessible to the system logger for the duration of the request. The storage must be addressable in the caller's home address space and in the same key as the caller.
08	xxxx083F	Equate Symbol: IxgRsnCodeTestartError Explanation: System error. An unexpected error was encountered while attempting to validate the buffer ALET. Action: See ANSAA_DIAG1 in the answer area mapped by the IXGANSAA macro for the return code from the TESTART system service.
08	xxxx0841	Equate Symbol: IxgRsnCodeBadBufferAlet Explanation: Program error. The buffer ALET specified is not zero and does not represent a valid entry on the caller's dispatchable unit access list (DUAL). See the ANSAA_DIAG1 field of the answer area, mapped by the IXGANSAA macro, for the return code from the TESTART system service. Action: Ensure that the correct ALET was specified. If not, provide the correct ALET. Otherwise, add the correct ALET to dispatchable unit access list (DUAL).
08	xxxx0849	Equate Symbol: IxgRsnCodeBadBuffkey Explanation: Program error. The buffer key specified on the BUFFKEY parameter specifies an invalid key. Either the key is greater than 15 or the program is running in problem state and the specified key is not the same key as the PSW key at the time the system logger service was issued. Action: For problem state programs, either do not specify the BUFFKEY parameter or else specify the same key as the PSW key at the time the system logger service was issued. For supervisor state programs, specify a valid storage key (0 <= key <= 15).
08	xxxx085C	Equate Symbol: IxgRsnCodeDsDirectoryFull Explanation: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to DASD has failed because the log stream's data set directory is full. If this reason code is issued by the IXGWRITE request, no further write requests can be processed until additional directory space is available for the log stream. System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data. However, the time that passes before you can write to the log stream is unpredictable. The system issues related messages IXG257I, IXG261E, IXG262A and IXG301I. Action: The system programmer must make more log stream data set directory space available. For information about how an authorized application program might respond to this reason code, see Setting Up the System Logger Configuration in the z/OS MVS Programming: Authorized Assembler Services Guide. For information about how an unauthorized application program might respond to this reason code, see IXGWRITE: Writing to a log stream in the z/OS MVS Programming: Assembler Services Guide.
08	xxxx085D	Equate Symbol: IxgRsnCodeWowError Explanation: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to DASD have failed because of severe errors. No further write requests can be processed until the offload error condition is cleared. System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data. However, the time that passes before you can write to the log stream is unpredictable. The system issues related message IXG301I. Action: The system programmer must correct the severe error condition inhibiting the log stream offload. If you are unable to correct the error, search problem reporting data bases for a fix for the problem. If no fixt exists, contact the IBM Support Center. You can retry your write request periodically or wait for the ENF signal that the log stream is available, or disconnect from this log stream and connect to another log stream. For information on how an authorized application program might respond to this reason code, see Setting up the system logger configuration in the z/OS MVS Programming: Authorized Assembler Services Guide. For information on how an authorized application program might respond to this reason code, see IXGWRITE: Writing to a log stream in the z/OS MVS Programming: Assembler Services Guide.
08	xxxx0860	Equate Symbol: IxgRsnCodeCFLogStreamStorFull Explanation: Environment error. The coupling facility structure space allocated for this log stream is full. No further requests can be processed until the log data in the coupling facility structure is offloaded to DASD log data sets. Action: Listen to the ENF signal 48 which will indicate that the log stream is available after the data has been offloaded to DASD. For IXGCONN requests, Listen to the ENF signal 48 which will indicate that the structure is available. Then, re-issue the request.
08	xxxx0861	Equate Symbol: IxgRsnCodeRebuildInProgress Explanation: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build 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 re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0862	Equate Symbol: IxgRsnCodeXESPurge Explanation: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing. Action: Listen for ENF signal 48 that will indicate one of the following: The log stream is available because the re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0863	Equate Symbol: 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 re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0864	Equate Symbol: IxgRsnCodeNoConnectivity Explanation: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build 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 re-build completed successfully. Re-issue the request. The re-build 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	xxxx0865	Equate Symbol: IxgRsnCodeStagingDSFull Explanation: Environment error. The staging data set allocated for this log stream on this system is full. No further requests can be processed until enough log data in the coupling facility structure is offloaded to DASD log data sets to relieve the staging data set's full condition. Action: Listen to the ENF signal 48 which will indicate that the log stream is available after room becomes available in the staging data set. Then, re-issue the request.
08	xxxx0867	Equate Symbol: IxgRsnCodeLocalBufferFull Explanation: Environment error. One of the two following problems was detected: The available local buffer space (data space storage) for the system logger address space is full. Ansaa_Diag1 and Ansaa_Diag2 in the Answer Area will contain 0 for this error return. The IXGWRITE is rejected because a caller attempted to write log data when the outstanding asynchronous write activity for this connection was considered too high. The limit for unauthorized IXGWRITE invokers is 2,000 and the limit of 10,000 is used for authorized callers. An unauthorized caller is a caller whose PSW key is >= 8 and that is not in supervisor state. ANSAA_DIAG1 in the answer area contains a value of 1 for this error return for unauthorized callers and a value of 2 for authorized callers. ANSAA_DIAG2 contains the total number of outstanding write requests for this connection. No further writing requests can be processed until the log data in the local buffer space is offloaded to DASD log data sets or this connector's prior IXGWRITE requests complete. Note: This reason code applies to both CF and DASD only log stream requests. Action: For authorized writers: Listen for the ENF signal 48 that will indicate that the log stream is available. With the first condition, logger issues the ENF signal after the data has been offloaded to DASD. With the second condition, logger issues the ENF signal 48 that the log stream is available when the number of in-flight authorized asynchronous writes is reduced below 85% of the limit. There will be no ENF signal issued when the unauthorized limit is relieved. For unauthorized callers: Wait for a short interval and then reissue the request. If the attempts continue to fail or the ENF signal is not issued for an unacceptable period, consider notifying operations or disconnecting from the log stream.
08	xxxx0868	Equate Symbol: IxgRsnCodeStagingDSFormat Explanation: Environment error. The staging data set allocated for this log stream on this system has not finished being formatted for use by System Logger. No further IXGWRITE requests can be processed until the formatting completes. Action: Listen to the ENF signal 48 which will indicate that the logstream is available after formatting process is finished. Then, re-issue the request.
08	xxxx0890	Equate Symbol: IxgRsnCodeAddrSpaceNotAvail Explanation: System error. The system logger address space failed and is not available. Action: Do not issue system logger requests.
08	xxxx0891	Equate Symbol: 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. Re-connect to the log stream, then re-issue 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	xxxx08D1	Equate Symbol: IxgRsnCodePrgramKey Explanation: Environment error. The request was rejected because of one of the following: The request was issued in SRB mode while the requestor was in problem program key (key 8-F). The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key. Action: Change the invoking environment to a system key (key 0-7).
08	xxxx08D2	Equate Symbol: IxgRsnCodeNoCompleteExit Explanation: Program error. MODE=SYNCEXIT was specified, but the connection request did not identify a complete exit. Action: Either change this request to a different MODE option, or reconnect to the log stream with a complete exit specified on the COMPLETEXIT parameter.
08	xxxx08D7	Equate Symbol: IxgRsnCodeRequestNotAllowed Explanation: Program error. The caller issued an IXGWRITE request while an import connection was active on this system (IXGCONN IMPORTCONNECT=YES). Action: Re-issue the request, based on the type of connection active.
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 1

Write data to the log stream synchronously.

          IXGWRITE STREAMTOKEN=TOKEN,                                  X
               BUFFER=BUFF,                                            X
               BLOCKLEN=BLKLEN,                                        X
               BUFFALET=BUFALET,                                       X
               RETBLOCKID=RETBLK,                                      X
               BUFFKEY=BUFKEY,                                         X
               TIMESTAMP=RET_TIME,                                     X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
BUFF     DC    CL256'BUFFER TEXT'     buffer to write to log stream
BLKLEN   DC    F'256'                 length of block to be written
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
BUFKEY   DC    F'8'                   buffer key
TOKEN    DS    CL16                   stream token from connect
RET_TIME DS    CL16                   returned timestamp of block
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
BUFALET  DC    F'1'                   buffer alet secondary
RETBLK   DS    CL8                    returned block id
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 2

Write data to the log stream asynchronously, if synchronous processing is not possible.

          IXGWRITE STREAMTOKEN=TOKEN,                                  X
               BUFFER=BUFF,                                            X
               BLOCKLEN=BLKLEN,                                        X
               BUFFALET=BUFALET,                                       X
               RETBLOCKID=RETBLK,                                      X
               MODE=SYNCECB,                                           X
               ECB=ANECB,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
*           if return code = '00000401'X then wait
*           on the ecb ANECB for the request to complete
*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BUFF     DC    CL256'BUFFER TEXT'     buffer to write to log stream
BLKLEN   DC    F'256'                 length of block to be written
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
BUFALET  DC    F'1'                   buffer alet secondary
ANECB    DS    F                      ecb to wait on
RETBLK   DS    CL8                    returned block id
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 3

Write data to the log stream using registers.

          LA R6,TOKEN                 load stream token in register 6
          IXGWRITE STREAMTOKEN=(6),                                    X
               BUFFER=BUFF,                                            X
               BLOCKLEN=BLKLEN,                                        X
               RETBLOCKID=RETBLK,                                      X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
BUFF     DC    CL256'BUFFER TEXT'     buffer to write to log stream
BLKLEN   DC    F'256'                 length of block to be written
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
RETBLK   DS    CL8                    returned block id
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area
R6       EQU   6                      set up register 6