IXZXIXMC - Clear a Mailbox

Use the IXZXIXMC macro to clear a specified mailbox of any messages that have been placed into the mailbox but have not been received. IXZXIXMC returns an acknowledgement message to the sending JES member indicating that the message was cleared from the mailbox.

Typically, IXZXIXMC might be used by a JES dispatchable unit (JDU) that has restarted and does not want to process messages that were received from the previous JES start. IXZXIXMC also might be used by a JDU that becomes available after being unavailable and does not want to process messages that were placed in its mailbox during that time.

Refer to Clearing a Mailbox of Messages (IXZXIXMC Macro) for a description of using IXZXIXMC to clear a mailbox.

Environment

The requirements for the caller are:

Table 1. Environment
Variable	Value
JES environments:	JES2 or JES3 main task JES2 or JES3 subtask JES3 FSS
Minimum authorization:	Supervisor state with PSW key 0 or 1
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	None

Programming Requirements

JES2 programs must include the $MODULE macro so it is invoked before IXZXIXMC is invoked.

JES3 programs must include the ENVIRON= keyword on the IATYMOD macro so it is invoked before IXZXIXMC is invoked.

Restrictions

Do not issue IXZXIXMC until JES initialization processing has established an attachment to the JES XCF group; that is, after IXZXIT03 processing has completed.

When clearing a mailbox, you must do so under the same task in which the mailbox was built.

Input Register Information

Before issuing the IXZXIXMC 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 IXZXIXMC returns control, the general purpose registers (GPRs) contain:

Register: Content
0: Reason 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 IXZXIXMC returns control, the access registers (ARs) contain:

Register: Content
0,1: Used as work registers by the system
2-13: Unchanged
14,15: Used as work registers 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


>>-+-------+--IXZXIXMC----MBOXNAME=mboxname--------------------->
   '-label-'                                    

>----,GROUPTOKEN=grouptoken----+------------------+------------->
                               '-,RTNCODE=rtncode-'   

>--+------------------+----------------------------------------->
   '-,RSNCODE=rsncode-'   

   .-,MF=S-------------------------------.   
>--+-------------------------------------+---------------------><
   |                   .-,0D-----.       |   
   '-,MF=-+-(L-,mfctrl-+---------+-)---+-'   
          |            '-,mfattr-'     |     
          |            .-,COMPLETE-.   |     
          '-(E-,mfctrl-+-----------+-)-'

Parameters

label

Specifies an optional symbol, starting in column 1, to be used as the name on the IXZXIXMC macro invocation.

Default: no name

MBOXNAME=mboxname

Specifies the name (RS-type) or address (in GPR2-GPR12) of a required 16-character input field that contains the name of the mailbox to be cleared. Valid characters are A-Z, 0-9, $, #, @, and embedded and trailing blanks.

Default: none

GROUPTOKEN=grouptoken

Specifies the name (RS-type) or address (in GPR2-GPR12) of a required fullword input field that contains the group token. Refer to Retrieving the JES XCF Group Token for the procedure for retrieving the JES XCF group token.

Default: none

RTNCODE=rtncode

Specifies the name (RS-type) of an optional fullword output field or register (GPR2-GPR12) into which the return code is copied from GPR 15.

Default: none

RSNCODE=rsncode

Specifies the name (RS-type) of an optional fullword output field or register (GPR2-GPR12) into which the reason code is copied from GPR 0.

Default: none

MF=S | L | E

Specifies the form of the macro as standard (S), list (L), or execute (E). This keyword is optional.

MF=S

Specifies the standard form of the macro; that is, to build the in-line parameter list and invoke the desired service. Processing also includes checking for all required keywords and supplying defaults, if any, for omitted optional parameters.

MF=(L,mfctrl{,mfattr | 0D})

Specifies the list form of the macro; that is, defining an area to be used for the parameter list. If you code MF=L, do not code anything else except a label, the macro name, and the following values:

mfctrl: Specifies the name of a storage area to contain the parameters.
mfattr | 0D: Specifies 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 mfattr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
Default: 0D

MF=(E,mfctrl,COMPLETE)

Specifies the execute form of the macro; that is, builds the parameter list specified by mfctrl. Processing also includes checking for all required keywords and supplying defaults, if any, for omitted optional parameters.

mfctrl: Specifies the name (RS-type) or address (in GPR1-GPR12) of a storage area for the parameter list.
COMPLETE: Specifies the desired degree of macro parameter syntax checking. Syntax checking includes checking for all required keywords and supplying default values, if any, for all omitted optional parameters.

Default: COMPLETE

Default: S

ABEND Codes

When control returns to your program, if you receive a return code of X'C', it indicates that processing failed because the IXZXIXMC service ended abnormally, and you will also receive an associated ABEND code. Refer to z/OS MVS System Codes for a description of the following possible ABEND codes:

DC5: JES XCF detected an unrecoverable error during attach or detach processing.
EC5: JES XCF detected an unrecoverable error while attempting recovery from a previous abend.

Return and Reason Codes

When the IXZXIXMC macro returns control to your program, GPR 15 (and rtncode if you coded RTNCODE) contains the return code and GPR 0 (and rsncode if you coded RSNCODE) contains the reason code.

Return Code (hex)	Reason Code (hex)	Meaning and Action
0	0	Meaning: Processing was successful. The mailbox was cleared. All messages that were in the mailbox were acknowledged with a return code that indicates the messages were not received. Action: None
4	4	Meaning: Processing failed because the parameter list passed to the IXZXIXMC service contains an eyecatcher that is not valid. Action: Check the parameter list to be certain it was not overlaid with other data.
4	8	Meaning: Processing failed because the parameter list passed to the IXZXIXMC service contains a version indicator that is not valid. Action: The caller might need to be recompiled. Check the parameter list to be certain it was not overlaid with other data.
4	C	Meaning: Processing failed because the group token passed to the IXZXIXMC service was not valid. Action: Verify that the correct group token is being passed to IXZXIXMC.
4	10	Meaning: Processing failed because the mailbox name passed to the IXZXIXMC service routine does not exist. Action: Verify that the correct mailbox name is being passed to IXZXIXMC.
4	14	Meaning: Processing failed because the ASCB or TCB of the caller of the IXZXIXMC service does not match that of the mailbox builder (the caller of IXZXIXMB). Action: You attempted to clear a mailbox under a different task than that used to build the mailbox. You can only clear the mailbox when under the task from which IXZXIXMB was issued. Be certain that both the ASCB and TCB of the caller match those of the mailbox builder, and rerun the program.
4	18	Meaning: Processing failed because the IXZXIXMC service was issued on a member that is detaching. Action: Check to be certain this is not a symptom of a serialization problem within your JES XCF group.
4	1C	Meaning: Processing failed because the parameter list passed to the IXZXIXMC service routine specified a mailbox name that is not valid. Action: Be certain you specified MBOXNAME= correctly. Only A-Z, 0-9, $, #, @, and embedded and trailing blanks are valid.
C	0	Meaning: Processing failed because the IXZXIXMC macro service abended. Action: Refer to z/OS MVS System Codes for a description of the abend code and its associated reason codes.