Parameter Descriptions

The parameter descriptions for REQUEST=DELETE_NAME are listed in alphabetical order. Default values are underlined:

REQUEST=DELETE_NAME

Use this input parameter to specify that one or more data items specified by NAME and NAMEMASK are to be deleted from the cache structure.

,ANSAREA=NO_ANSAREA

,ANSAREA=ansarea

Use this output parameter to specify an answer area to contain:

A restart token (CAARESTOKEN) or extended restart token (CAAEXTRESTOKEN) that is returned from a request that exceeds the model-dependent time-out criteria. See the RESTOKEN and EXTRESTOKEN parameters for a description of the restart token.
An asynchronous cross-invalidation sequence number (CAAASYNCXISEQNUM) that is returned from a request that initiates cross-invalidates of local caches asynchronously to the completion of the request.
See the IXLAXISN service for a description of how to use the returned CAAASYNCXISEQNUM to determine when cross-invalidates of local caches associated with the request have completed.

The format of the answer area is described by the IXLYCAA mapping macro.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of ANSLEN) where the information returned from the request will be put.

,ANSLEN=anslen

Use this inppaameter to specify the size of the storage area specified by ANSAREA.

Use either CAALEVEL0LEN, CAALEVEL1LEN or CAALEVEL2LEN of the IXLYCAA mapping macro to determine the minimum size of the answer area. The answer area length must be at least large enough to accommodate the level of the IXLYCAA mapping appropriate to the requested function.

When the connection specified ASYNCXI=1 on the IXLCONN invocation and AXIOVERRIDE=0 was specified or defaulted to for the IXLCACHE request, the answer area length is a required parameter and must be a minimum value of CAALEVEL2LEN to contain a returned asynchronous cross-invalidation sequence number (CAAASYNCXISEQNUM).
When the value of PLISTVER is 4 or above, the minimum answer area length is CAALEVEL1LEN.
When the value of PLISTVER is 0 - 3, the minimum answer area length is CAALEVEL0LEN.

To Code: Specify the RS-type name or address (by using a register 2 - 12 2 to ) of a 2-byte field that contains the length of the answer area (ANSAREA).

,CONTO=conken

Use this input parameter to specify the connect token that was returned by the IXLCONN service in the IXLCONN answer area, which is mapped which is by IXLYCONA. The connect token uniquely identifies your connection to the cache structure, and must be specified on each IXLCACHE invocation.

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of a 16-byte field that contains the connect token.

,AXIOVERRIDE=0

,AXIOVERRIDE=axioverride

Use this input parameter to specify whether the asynchronous cross-invalidation control setting of IxlConnAsyncXiYes (1) for the connection identified by CONTOKEN should be overridden for this request. Valid values are 0 (IxlCacheAXiOverrideNo) or 1 (IxlCacheAXiOverrideYes).

The AXIOVERRIDE keyword is meaningful to processing only when the connection specified ASYNCXI=1 on the IXLCONN invocation when connecting to the cache structure and the cache structure is allocated in a CFLEVEL=23 or higher coupling facility.

A value of 0 (IxlCacheAXiOverrideNo) indicates that the asynchronous cross-invalidation control for the connection as specified on the IXLCONN invocation should be used for the request. Cross-invalidates against local caches for this request will preferentially be initiated asynchronously to the completion of the request when asynchronous cross-invalidations are supported by the coupling facility where the cache structure is allocated.

A value of 1 (IxlCacheAXiOverrideYes) indicates that the ASYNCXI specification of IxlConnAsyncXiYes (1) by the connector on the IXLCONN invocation should be overridden for this request only. Cross-invalidations generated by this request will be processed synchronously to the completion of the request.

Any value other than 0 or 1 for AXIOVERRIDE will have the same behavior as specifying a value of 0 (IxlCacheAXiOverrideNo).

If cross-invalidates against local caches for this request were initiated asynchronously to the completion of the request, an asynchronous cross-invalidation sequence number is returned in CAAASYNCXISEQNUM of the cache answer area (ANSAREA).

The asynchronous cross-invalidation sequence number can be used on a subsequent invocation of IXLAXISN to ensure that the asynchronous cross-invalidations associated with this request have completed.

When cross-invalidations are initiated synchronously to the completion of the request or no cross-invalidations occurred for the request, no asynchronous cross-invalidation sequence number is returned.

To Code: Specify the RS-type name or address (by using a register 2 - 12 2 to ) of a one-byte input field that contains the value indicating whether the asynchronous cross-invalidation control setting of the connector should be overridden

,DELETETYPE=DIRANDDATA

,DELETETYPE=UNCHNDATA

,DELETETYPE=CHDATA

,DELETETYPE=ANYDATA

Use this input parameter to specify the type of delete processing that is to be performed. DELETETYPE is valid only for structures allocated in a coupling facility of CFLEVEL=5 or higher.

DIRANDDATA: For each applicable structure entry, invalidate the name and remove the name from storage and cast-out classes, and release all directory and data entry resources for the structure for reuse by the structure. The system deregisters interest in all connections with registered interest in the entry and, optionally, performs a cross-invalidate against their local caches.
Cross-invalidation against local caches may be suppressed to improve overall coupling facility performance and to quicken the completion of DELETE_NAME requests.
UNCHNDATA: For each applicable structure entry, if the data is unchanged, release the data entry resources for the entry for reuse by the structure. The system does not delete the directory entry and does not perform a cross-invalidate.
CHDATA: For each applicable structure, if the data is changed, release the data entry resources for the entry for reuse by the structure, set the change bit, the castout lock, and the castout lock state to zero, and remove the directory entry from the castout class. The system does not delete the directory entry and does not perform a cross-invalidate.
ANYDATA: For each applicable structure, whether the data is changed or unchanged, release the data entry resources for the entry for reuse by the structure. If the data is changed, set the change bit, the castout lock, and the castout lock state to zero, and remove the directory entry from the cast-out class. The system does not delete the directory entry and does not perform a cross-invalidate.

,EXTRESTOKEN=NO_EXTRESTOKEN

,EXTRESTOKEN=extrestoken

Use this input parameter to specify an extended restart token that can be used to resume processing of a DELETE_NAME request that completed prematurely. The extended restart token is returned in the answer area (field CAAEXTRESTOKEN), and should be specified on the next DELETE_NAME request to resume processing with the next data item to be processed.

If the request does not exceed the model-dependent time-out criteria or request processing was not halted (HALTONCHANGED=NO) or defaulted to NO), the extended restart token will not be provided.

Note:

Specifying an extended restart token of all zeros causes cache services to treat all of the entries as unprocessed.
Do not specify an extended restart token other than the one returned in the answer area or one set to all zeros, because results will be unpredictable.
Specifying an extended restart token requires that the length of the answer area be at least the length of CAALEVEL1LEN.

Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token. Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token (RESTOKEN).

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the extended restart token.

HALTONCHANGED=NO

HALTONCHANGED=YES

Use this input parameter to specify whether the DELETE_NAME request should be halted when a structure entry is encountered that either contains changed data or for which the cast-out lock is currently held.

HALTONCHANGED is only meaningful when delete operations are issued to cache structures allocated in a coupling facility that supports request halting based on data changed status and cast-out lock state.

HALTONCHANGED=NO

The DELETE_NAME request should continue processing a structure entry which contains changed data or for which the cast-out lock is held.

HALTONCHANGED=YES

The DELETE_NAME request should be halted if a structure entry contains changed data or for which the cast-out lock is held. The structure entry is not deleted. Specifying HALTONCHANGED=YES can prevent the inadvertent loss of changed data that has not yet been cast out to permanent storage. When the request is halted due to the presence of a structure entry that meets the halt criteria, information identifying the structure entry is returned in the answer area specified by ANSAREA. A restart token is returned in the answer area for resuming the halted request.

HALTONCHANGED=YES is intended to prevent the inadvertent loss of changed data that has not yet been cast out to permanent storage. When the DELETE_NAME request is halted, the application is expected to take some action to change the state of the indicated structure entry data to "unchanged" (i.e. the cast-out lock is not held and the status of the data is unchanged) before resuming the request with the restart token. One such action could be to read the entry data for castout, write the data to permanent storage, then reset the cast-out lock to the not-held state.

Restarting the DELETE_NAME request before taking such an action to change the state of the structure entry data to "unchanged" may result in the request halting on the same structure entry again thus preventing the request from proceeding further to process all intended structure entries.

When the request is halted due to the presence of a structure entry that meets the halt criteria, the request will complete with a return code IXLRETCODEWARNING, reason code IXLRSNCODEHALTCHANGEDDATA and the answer area specified by ANSAREA will contain specific information to identify the entry that was found to be in the "changed" state.

,MF=S

,MF=(L,mfctrl)

,MF=(L,mfctrl,mfattr)

,MF=(L,mfctrl,0D)

,MF=(M,mfctrl)

,MF=(M,mfctrl,COMPLETE)

,MF=(M,mfctrl,NOCHECK)

,MF=(E,mfctrl)

,MF=(E,mfctrl,COMPLETE)

,MF=(E,mfctrl,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.

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 coded with the list form of the macro.

Use MF=M to specify the modify form of the macro. Use the modify form to generate code to put the parameters into the parameter list.

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 stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,mfctrl

Use this output parameter to specify a storage area to contain the parameters.

To Code: Specify the RS-type name or address (by using a register 2 - 12) of the parameter list.

,mfattr

Use this input parameter to specify the name of a 1- to 60-character string that can contain any value that is valid on an assembly language Data Studio 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.

,COMPLETE

,NOCHECK

Use this input parameter to specify the degree of macro parameter syntax checking the system is to do.

COMPLETE: Use this input parameter to require that the system check for required parameters and supply defaults for omitted optional parameters.
Note: In the macro expansion you might see some defaults for optional parameters that are not documented here. The ones that are not documented do not have any effect on the macro. For example, if SMILE=var were an optional parameter and the default is SMILE=NO_SMILE then it would not be documented. However, if the default was SMILE=:-), then it would be documented because a value would be the default.
NOCHECK: Use this parameter to specify that the system is not to check for required parameters nor to supply defaults for omitted optional parameters.

,MODE=SYNCSUSPEND

,MODE=SYNCECB

,MODE=SYNCEXIT

,MODE=SYNCTOKEN

,MODE=ASYNCECB

,MODE=ASYNCEXIT

,MODE=ASYNCTOKEN

Use this input parameter to specify:

Whether the request is to be performed synchronously or asynchronously
How you want to be notified of request completion if the request is processed asynchronously.

See z/OS MVS Programming: Sysplex Services Guide for more information on understanding synchronous and asynchronous cache operations.

SYNCSUSPEND: The request processes synchronously. If necessary, the request is suspended until it can complete synchronously. To use this option, your program must be enabled for I/O and external interrupts.
SYNCECB: The request processes synchronously if possible. If the request processes asynchronously, the ECB specified by REQECB is posted when the request completes.
SYNCEXIT: The request processes synchronously if possible. If the request processes asynchronously, your complete exit is given control when the request completes.
SYNCTOKEN: The request processes synchronously if possible. If the request processes asynchronously, an asynchronous request token is returned to the area specified by REQTOKEN. Use the returned request token on the IXLFCOMP macro to determine whether your request has completed.
Note: ANSAREA is a required parameter when MODE=SYNCTOKEN is specified.
ASYNCECB: The request processes asynchronously. The ECB specified by REQECB is posted when the request completes.
ASYNCEXIT: The request processes asynchronously. Your complete exit is given control when the request completes.
ASYNCTOKEN: The request processes asynchronously. An asynchronous request token is returned to the area specified by REQTOKEN. Use the returned request token on the IXLFCOMP macro to determine whether your request has completed.
Note: ANSAREA is a required parameter when MODE=ASYNCTOKEN is specified.

,NAME=name

Use this input parameter to specify the name of the data item to be deleted from the cache structure.

You may delete multiple data items with one invocation of this macro, if they have similar names. See the description of the NAMEMASK parameter for how to do this.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the name of the data item.

,NAMEMASK=1111111111111111

,NAMEMASK=namemask

Use this input parameter to specify which characters in the name specified by NAME are to be used in selecting data items for processing. This parameter allows you to select multiple data items based on common characters in NAME.

The position of each bit in NAMEMASK corresponds to the same relative character position in NAME. A one indicates that the corresponding letter should be used in selecting entries; a zero indicates that the corresponding letter should not be used.

Specifying a name mask with all zeros causes all names to be selected for processing. Specifying a name mask with all ones causes only the name specified by NAME to be selected.

For more information on how NAMEMASK may be used, see z/OS MVS Programming: Sysplex Services Guide.

To Code: Specify the RS-type name or address (by using a register 2 - 12 2 to ) of a 2-byte field that contains the bit-mask for the name specified on the NAME keyword.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Use this input parameter to specify the version of the macro. See Understanding IXLCACHE Version Support for a description of the options available with PLISTVER.

,REQDATA=NO_REQDATA

,REQDATA=reqdata

Use this input parameter with MODE=SYNCEXIT or MODE=ASYNCEXIT to pass any data you choose to the complete exit. The exit will get control only if the request is processed asynchronously.

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of an 8-byte field that contains the data to be passed to the complete exit.

,REQECB=reqecb

Use this output parameter with either MODE=SYNCECB or MODE=ASYNCECB to specify the address of an ECB, which is to be posted when the request completes if the request was processed asynchronously.

Before coding REQECB, you must ensure that:

You initialize the ECB before you issue the request.
The ECB resides in either common storage or the home address space where IXLCONN was issued.
Any tasks that wait for the ECB to be posted reside in the home address space where IXLCONN was issued.

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of a 4-byte field that contains the address of the ECB to be posted when the request completes. The ECB must be aligned on a fullword boundary.

,REQID=NO_REQID

,REQID=reqid

Use this input parameter to specify a user-defined request identifier to be associated with the request. You can specify this request identifier on the IXLPURGE macro to cancel a request that has not yet been processed.

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of an 8-byte field that contains the user-defined request identifier.

,REQTOKEN=reqtoken

Use this output parameter with either MODE=SYNCTOKEN or MODE=ASYNCTOKEN to specify the address of a storage area to receive the request token that is returned when the request will be processed asynchronously. This token, which uniquely identifies the request, must be used as input to the IXLFCOMP macro, which you use to determine if the request has completed.

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of a 16-byte field where the system will put the request token.

,RESTOKEN=NO_RESTOKEN

,RESTOKEN=restoken

Use this input parameter to specify an extended restart token that can be used to resume processing of a DELETE_NAME request that completed prematurely. The extended restart token is returned in the answer area (field CAARESTOKEN), and should be specified on the next DELETE_NAME request to resume processing with the next data item to be deleted.

If the request does not exceed the model-dependent time-out criteria or request processing was not halted (HALTONCHANGED=NO or defaulted to NO), the extended restart token will not be provided.

Note:

Specifying a restart token of all zeros causes cache services to treat all of the entries as unprocessed.
Do not specify a restart token other than the one returned in the answer area or one set to all zeros, because results will be unpredictable.

Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token. Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token (EXTRESTOKEN).

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the restart token.

,RETCODE=retcode

Use this output parameter to specify a field to contain the return code. (The return code is also returned in register 15.)

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of a 4-byte field that will contain the return code when the request has completed.

,RSNCODE=rsncode

Use this output parameter to specify a field to contain the reason code returned, if applicable. (The reason code is also returned in register 0.)

To Code: Specify the RS-type name or address (by using a register from 2 to 12) of a 4-byte field that will contain the reason code (if any) when the request has completed.

SUPPCROSSINVAL=NO

SUPPCROSSINVAL=YES

Use this input parameter to specify whether cross-invalidate processing associated with the DELETETYPE=DIRANDDATA request should be suppressed.

SUPPCROSSINVAL is only meaningful when delete operations are issued to cache structures allocated in a coupling facility that supports suppressing cross invalidation processing.

SUPPCROSSINVAL=NO: Cross-invalidation should be performed (not suppressed) against the local caches of all connections with registered interest in a successfully deleted structure entry.
SUPPCROSSINVAL=YES: Cross-invalidation should not be performed (suppressed) against the local caches of all connections with registered interest in a successfully deleted structure entry. Cross-invalidation signals associated with the cross-invalidation of local caches are not sent which improves overall performance by reducing coupling facility link traffic, saving CPU cycles and quickening the completion of the DELETE_NAME request.
When requesting that the system suppress cross-invalidation of the local cache of a deleted data item, the IXLVECTR macro cannot be used to check the validity of that local cache data item using the vector index that had been associated with the data item. The vector index will be in an indeterminate state until it is subsequently reused for a new data item. The application must take its own measures to ensure the data integrity of the local cache buffers and the subsequent reuse of the associated vector indexes.

,VERSCOMP=NO_VERSCOMP

,VERSCOMP=verscomp

Use this imput parameter to specify a value to be compared to the version number of the entry designated by NAME.

VERSCOMP is meaningful only for structures allocated in a coupling facility of CFLEVEL=5 or higher.

If the condition specified by VERSCOMPTYPE is not met, the entry is not processed and processing continues with the next entry to be considered.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains a value to be compared to each entry's version number.

,VERSCOMPTYPE=EQUAL

,VERSCOMPTYPE=LESSOREQUAL

Use this input parameter to specify how the structure entry version number comparison is to be performed.

VERSCOMPTYPE is meaningful only for structures allocated in a coupling facility of CFLEVEL=5 or higher and may be specified only when VERSCOMP also is specified.

VERSCOMPTYPE=EQUAL: The version number for the structure entry must be equal to the value specified for VERSCOMP.
VERSCOMPTYPE=LESSOREQUAL: The version number for the structure entry must be less than or equal to the value specified for VERSCOMP.