IXGDELET — Deleting log data from a log stream

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 the service in SRB mode or use the MODE=SYNCEXIT keyword.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=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 parameter:	All control parameters must be in the primary address space with the following exceptions: The ECB should be addressable from the home address space. All storage areas specified must be in the same storage key as the caller.

• The current primary address space must be the same primary address space used at the time your program 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.
• 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.
• If there are multiple connections to a log stream, each connected application must serialize delete requests so that a delete of log blocks does not occur, for example, in the middle of another application's browse session.
• 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 IXGDELET request is issued.
  • The storage used for output parameters, such as ANSAREA and OBLOCKID, are accessible by both the IXGDELET invoker and the ECB waiter.
• When coding the MODE=SYNCEXIT parameter, you must ensure that the storage used for output parameters, such as ANSAREA and OBLOCKID, are accessible by both the IXGDELET invoker and the completion exit routine.

• All storage areas specified in this service must be in the same storage key as the caller's storage key and must exist in the caller's primary 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.

Before issuing the IXGDELET 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 standard form of the IXGDELET macro is written as follows:

The parameters are explained as follows:

,STREAMTOKEN=streamtoken

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

,BLOCKS=ALL

,BLOCKS=RANGE

Specifies whether all or just a subset of log blocks in a log stream be deleted.

• BLOCKS=ALL: Specifies that all the log blocks in the specified log stream be deleted.
• BLOCKS=RANGE: Specifies that the range of log blocks, older than the block specified on the BLOCKID parameter, be deleted. The BLOCKID parameter is required with BLOCKS=RANGE, See z/OS MVS Programming: Assembler Services Guide for more information on deleting a range of log blocks.

,BLOCKID=blockid

Specifies the name or address (using a register) of a 8-byte input field which contains a log block identifier. BLOCKID is required with the BLOCKS=RANGE parameter. All blocks in the log stream older than the block specified on BLOCKID will be deleted. Note that the block specified in BLOCKID is not deleted.

Block identifiers are returned in the RETBLOCKID field of the IXGWRITE service.

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

,FORCE=NO

,FORCE=YES

Specifies whether this delete request can be overridden by a resource manager exit.

If you specify FORCE=NO, which is the default, the delete request can be overridden by the resource manager exit.

If you specify FORCE=YES, the delete request cannot be overridden by a delete exit.

,OBLOCKID=oblockid

Specifies the name or address (using a register) of an 8 character output field where the resource manager places the override block identifier.

,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 parameter is posted when the request completes. The ECB parameter 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 parameters.

,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 (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

• You initialize the ECB.
• The ECB must reside in either common storage or the home address space where the IXGDELET request was issued.
• The virtual storage area specified for the ECB must reside on a fullword boundary.

,DIAG=NO_DIAG

,DIAG=NO

,DIAG=YES

Specifies whether or not the DIAG option on the IXGCONN for this logstream will be in effect for this delete log data request. Refer to the DIAG keyword on the IXGINVNT, IXGCONN and IXGBRWSE macro services.

If you specify DIAG=NO_DIAG, which is the default, then the DIAG option on the IXGCONN for this logstream will be in effect for this delete log data request.

If you specify DIAG=NO, then Logger will not take additional diagnostic action as defined on the logstream definition DIAG parameter.

If you specify DIAG=YES, then Logger will take additional diagnostic action as defined on the logstream definition DIAG parameter providing the IXGCONN connect DIAG specification allows it.

,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, supports all parameters except those specifically referenced in higher versions.
• 2, supports both the following parameters and parameters from version 0:
  • FORCE
  • OBLOCKID
  • 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 (using 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.

None.

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

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 : Delete all data from the log stream.

          IXGDELET STREAMTOKEN=TOKEN,                                  X
               BLOCKS=ALL,                                             X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
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
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 2 : Delete a range of data from the log stream asynchronously, if synchronous processing is not possible.

          IXGDELET STREAMTOKEN=TOKEN,                                  X
               BLOCKS=RANGE,                                           X
               BLOCKID=BLOCKID,                                        X
               MODE=SYNCECB,                                           X
               ECB=ANECB,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
*         If rsncode = '00000401'X then wait on
*         the ecb ANECB.
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
BLOCKID  DS    CL8                    block id from which to delete
TOKEN    DS    CL16                   stream token from connect
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
ANECB    DS    F                      ecb on which to wait
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 3 : Delete all data from the log stream using registers with the macro.

          LA   R6,TOKEN              load stream token into register 6
          IXGDELET STREAMTOKEN=(6),                                    X
               BLOCKS=ALL,                                             X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
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
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area
R6       EQU   6