|
The parameter descriptions for REQUEST=DELETE_NAMELIST are listed
in alphabetical order. Default values are underlined: - REQUEST=DELETE_NAMELIST
- Use this input parameter to specify that you want to delete a
set of entries from the structure. Each entry is represented by a
name block, mapped by the IXLYDNNB macro, stored in the area specified
by BUFFER or the buffers specified by BUKLIST.
- ,ANSAREA=NO_ANSAREA
- ,ANSAREA=ansarea
- Use this output parameter to specify an answer area to contain
information returned from the request. 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 answer area
information returned from the request will be stored.
- ,ANSLEN=anslen
- Use this input parameter to specify the size of the storage area
specified by ANSAREA.
Use either CAALEVEL0LEN or CAALEVEL1LEN 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 accomodate the level of the IXLYCAA mapping
appropriate to the requested function. When the value of PLISTVER
is 0 — 3, the minimum answer area length is CAALEVEL0LEN; when
the value of PLISTVER is 4 — 6, the minimum answer area length
is CAALEVEL1LEN.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 2-byte field that contains the length of the answer
area (ANSAREA).
- ,BUFADDRSIZE=31
- ,BUFADDRSIZE=64
- Use this input parameter to specify whether a 31-bit or a 64-bit
address is specified by a BUFLIST entry.
- 31
- The entry in BUFLIST is 31 bits in size.
- 64
- The entry in BUFLIST is 64 bits in size.
- ,BUFADDRTYPE=VIRTUAL
- ,BUFADDRTYPE=REAL
- Use this input parameter to specify whether the buffer addresses
specified in the BUFLIST list are virtual storage or real storage
addresses.
- VIRTUAL
- The buffer addresses are virtual storage addresses. The virtual
storage can be pageable or nonpageable. See the PAGEABLE parameter
for information about managing storage binds when specifying virtual
storage addresses.
- REAL
- The buffer addresses are real storage addresses.
It is the caller's responsibility to manage the binds between the
data buffer virtual storage and the real storage addresses provided.
The caller must ensure that the data buffer virtual storage remains
bound to the real storage addresses provided until the request completes.
- ,BUFALET=NO_BUFALET
- ,BUFALET=bufalet
- Use this input parameter to specify an access list entry token
(ALET) to be used in referencing all of the buffers specified by BUFLIST.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 4-byte field that contains the ALET.
- ,BUFFER=buffer
- Use this input parameter to specify a buffer area to contain the
returned name blocks tha define the entries that are to be deleted.
Only 31-bit addressable virtual storage areas (below
2GB) are supported bh the BUFFER specification.
High virtual storage areas (above 2GB) can only be specified via
the BUFLIST specification.
The
format of the registration block is described by mapping macro IXLYDNNB.
You
can define the buffer size to be a total of up to 65536 bytes, but
it should not be larger than what you actually require to hold the
maximum number of name blocks, subject to the other buffer length
requirements stated below.
Other requirements depend on the
size you select: - If you specify a buffer size of less than or equal to 4096 bytes,
you must ensure that the buffer:
- Is 256, 512, 1024, 2048, or 4096 bytes.
- Starts on a 256-byte boundary.
- Does not cross a 4096-byte boundary.
- Does not start below storage address 512.
- If you specify a buffer size of greater than 4096 bytes, you must
ensure that the buffer:
- Is a multiple of 4096 bytes.
- Is less than or equal to 65536 bytes.
- Starts on a 4096-byte boundary.
- Does not start below storage address 512.
See the BUFSIZE parameter description for defining the
size of the buffer. See z/OS MVS Programming: Sysplex Services Guide for
more information on buffers.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of an area (with a length of BUFSIZE) to contain the name
blocks.
- ,BUFINCRNUM=bufincrnum
- Use this input parameter to specify the number of 256-byte segments
comprising each buffer in the BUFLIST list.
Valid BUFINCRNUM values are 1,2,4,8, or 16, which correspond to
BUFLIST buffer sizes of 256, 512, 1024, 2048, and 4096 bytes respectively.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 1-byte field that contains 1,2,4,8, or 16.
- ,BUFLIST=buflist
- Use this input parameter to specify a list of buffers to hold
the name blocks identifying the entries to be deleted from the structure.
BUFLIST specifies a 128-byte storage area that consists of a list
of 1 to 16 buffer address elements.
The format of the name block
is described by mapping macro IXLYDNNB.
Either
31-bit addressable (below 2GB) or 64-bit addressable (above 2GB)
real or virtual storage areas are supported for the BUFLIST specification,
depending on the specification for the BUFADDRTYPE and BUFFADDRSIZE keywords.
However, pageable high shared virtual storage areas (above 2GB) may
not be used.
The format of the list is a set
of 8-byte elements. The BUFADDRSIZE keyword denotes whether four or
eight bytes of the element are used. - If BUFADDRSIZE=31 is specified, then the first four bytes of each
element are reserved space and the last four bytes contain the address
of the buffer.
- If BUFADDRSIZE=64 is specified, then the full eight bytes specify
the address of the buffer.
The BUFLIST buffers must: - Reside in the same address space or data space as defined by BUFALET.
- Be the same size: either 256, 512, 1024, 2048, or 4096 bytes
as defined by BUFINCRNUM.
- Start on a 256-byte boundary and not cross a 4096-byte boundary.
- Not start below storage address 512.
Note: The buffers do not have to be contiguous in storage.
XES treats BUFLIST buffers as a single buffer even if the buffers
are not contiguous.
See the BUFNUM and BUFINCRNUM keyword
descriptions for specifying the number and size of buffers.
See z/OS MVS Programming: Sysplex Services Guide for
more information on buffers.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of a 128-byte field that contains a list of buffer addresses.
- ,BUFNUM=bufnum
- Use this input parameter to specify the number of buffers in the
BUFLIST list. Valid BUFNUM values are from 1 to 16.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a 1-byte
field that contains the number of buffers (1 to 16) in the list (BUFLIST)
- ,BUFSIZE=bufsize
- Use this input parameter to specify the size of the BUFFER area.
See the BUFFER parameter description for valid buffer sizes.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a fullword field that contains the size of the buffer
(BUFFER) in bytes.
- ,BUFSTGKEY=CALLERS_KEY
- ,BUFSTGKEY=bufstgkey
- Use this input parameter to specify a storage key that you define
and use when referencing the buffer specified by BUFFER.
If you
do not specify BUFSTGKEY, or if you specify BUFSTGKEY=CALLERS_KEY,
all references to the buffer are in the caller's PSW key.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of a 1-byte field that contains the storage key in the format
kkkkxxxx, where kkkk is the key and xxxx is ignored.
- ,CONTOKEN=contoken
- Use this input parameter to specify the connect token that was
returned by the IXLCONN service in the IXLCONN answer area, mapped
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 (using a register
from 2 to 12) of a 16-byte field that contains the connect token.
- DELETETYPE=DIRANDDATA
- DELETETYPE=UNCHNDATA
- DELETETYPE=CHDATA
- DELETETYPE=ANYDATA
- Use this input parameter to specify the type of delete processing
that is to be performed.
- DIRANDATA
- 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_NAMELIST
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 cast-out 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.
- ,ENDINDEX=endindex
- Use this input parameter to specify the ending index for name
block processing. The index value must be greater than or equal to
the value specified for STARTINDEX.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a 2-byte
field containing the ending index value.
- ERRORACTION=CONTINUE
- ERRORACTION=TERMINATE
- Use this input parameter to specify whether processing is to continue
with the next name block if an entry is not found or a version mismatch
occurs.
- CONTINUE
- If an error occurs, processing is to continue with the next name
block.
- TERMINATE
- If an error occurs, processing is to halt and the index of the
name block that caused the error is returned in the answer area.
- HALTONCHANGED=NO
- HALTONCHANGED=YES
- Use this input parameter to specify whether the DELETE_NAMELIST
request should be halted when a structure entry in the set of entries
to be deleted 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_NAMELIST request should continue processing a structure
entry which contains changed data or for which the cast-out lock is
held.
- HALTONCHANGED=YES
- The DELETE_NAMELIST 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.
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_NAMELIST request is halted, the application is expected
to take some action to change the state of the indicated structure
entry data to "unchanged" (that is, the cast-out lock is not held
and the status of the data is unchanged) before resuming the request
by setting the STARTINDEX keyword to CaaDNLIndex. 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_NAMELIST 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=(E,mfctrl)
- ,MF=(E,mfctrl,COMPLETE)
- 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=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 (using a register
from 2 to 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 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.
- ,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.
- ,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 wish 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.
- ,PAGEABLE=YES
- ,PAGEABLE=NO
- Use this input parameter to identify whether the storage areas
specified by BUFFER or BUFLIST are in pageable or potentially pageable
storage.
- YES
- Specify this option to indicate that the BUFFER or BUFLIST buffers
reside in pageable virtual storage. XES performs the required page
fixing to fix the buffers in real storage while the cache or list
request transfers data to or from the coupling facility.
This includes storage obtained from pageable subpools, disabled
reference (DREF) storage, and may include storage that has the potential
to become pageable during the processing of a request. (An example
is address space storage owned by any swappable address space, for
which a PGSER FIX has been successfully processed, but for which the
owning address space gets swapped during processing of a cache or
list request.) This does not include implicitly non-pageable storage
(for example, storage obtained from non-pageable subpools).
The system takes responsibility for managing binds to central storage
for the duration of the cache or list request, regardless of what
address space owns the storage or whether the storage-owning address
space is swappable or nonswappable. The storage can be owned by any
address space.
High shared virtual storage areas (above 2GB) may not
be used.
- NO
- Specify this option to indicate that the BUFFER or BUFLIST buffers
reside in non-pageable virtual storage. XES does not page fix the
buffers in real storage.
This includes implicitly non-pageable storage areas (for example,
storage obtained from non-pageable subpools), and may include storage
that has the potential to become pageable during the processing of
a request (An example is address space storage owned by any swappable
address space, for which a PGSER FIX has been successfully processed,
but for which the owning address space gets swapped-out during processing
of a cache or list request.)
The system takes responsibility for managing binds to central storage
for the duration of the cache or list request, if and only if the
non-pageable storage is owned by either the requestor's address space
or the connector's address space. If the storage is owned by any other
address space, then the invoker is responsible for ensuring that the
virtual storage remains non-pageable for the duration of the request
(including the case in which the storage is owned by a swappable address
space that is swapped during processing of an IXLCACHE or IXLLIST
request). Subject to this consideration, the storage can be owned
by any address space. See z/OS MVS Programming: Sysplex Services Guide.
- ,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 (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 (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 (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 (using a register
from 2 to 12) of a 16-byte field where the system will put the request
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 (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 (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.
- ,STARTINDEX=startindex
- Use this input parameter to specify the starting index for name
block processing. Valid STARTINDEX values are from 1 to the value
of ENDINDEX. The first registration block has index number 1.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of a 2-byte field containing the starting index value.
- 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_NAMELIST
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.
- VERSCOMPTYPE=NONE
- VERSCOMPTYPE=EQUAL
- VERSCOMPTYPE=LESSOREQUAL
- Use this input parameter to specify how the structure entry version
number comparison is to be performed.
- VERSCOMPTYPE=NONE
- No version number is provided for comparison, therefore a version
number comparison is not to be performed.
- VERSCOMPTYPE=EQUAL
- The version number for the structure entry must be equal to the
value specifed in the corresponding name block mapped by IXLYDNNB.
- VERSCOMPTYPE=LESSOREQUAL
- The version number for the structure entry must be less than
or equal to the value specified in the corresponding name block mapped
by IXLYDNNB.
|