|
The parameter descriptions for REQUEST=READ_COCLASS are listed
in alphabetical order. Default values are underlined: - REQUEST=READ_COCLASS
- Use this input parameter to specify that the directory entry names
and information for a specified cast-out class (COCLASS) be stored
in the areas specified by BUFFER or BUFLIST. You may filter the amount
of information returned by the request by using the NAME and NAMEMASK
parameters.
- ,ANSAREA=NO_ANSAREA
- ,ANSAREA=ansarea
- Use this output parameter to specify an answer area to contain
information returned from the request. The information can include
a restart token or extended restart token when the request exceeds
the model-dependent time-out criteria or the specified buffer area
is full. The format of the answer area is described by the IXLYCAA
mapping macro.
Upon
successful completion of the request the answer area contains the
number of directory entries processed by the request (field CAADIRCOUNT).
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 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 output parameter to specify a buffer area to contain
the data that is read from the specified cast-out class.
You must
ensure that the storage area specified by 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.
Use the BUFSIZE description for specifying the size
of the buffer.
Upon completion of the request, the buffer
is arranged in 32-byte segments, starting at offset zero. The mapping
of the buffers
is described by the IXLYCANB mapping macro. For each named data item
reported on, the following information is returned to the buffer:
- The data item name
- The user data in the directory entry
- The size of the data entry (that is, the number of elements in
the data entry)
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 receive the requested information.
- ,BUFLIST=buflist
- Use this output parameter to specify a list of buffers to hold
the data that is read from the specified cast-out class. BUFLIST specifies
a 128-byte storage area that consists of a list of 0 to 16 buffer
addresses.
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 same data space.
- Be 4096 bytes.
- Start on a 4096-byte boundary.
- Not start below storage address 512.
Note: The buffers do not have to be contiguous in storage.
Cache services treat BUFLIST buffers as a single buffer even if the
buffers are not contiguous.
Use the BUFNUM parameter to
specify the number of buffers in the buffer list.
See z/OS MVS Programming: Sysplex Services Guide for
more information on buffers.
Upon
completion of the request, the buffers are arranged in 32-byte segments,
starting at offset zero. The mapping of the buffers
is described by the IXLYCANB mapping macro. For each named data item
reported on, the following information is returned to the buffers:
- The data item name
- The user data in the directory entry
- The size of the data entry
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of a 128-byte area 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 0 to 16. A value of zero
indicates that no data is to be read into the buffers.
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
(0 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 buffers specified by BUFLIST or the buffer
specified by BUFFER.
If you do not specify BUFSTGKEY, or if you specify BUFSTGKEY=CALLERS_KEY,
all references to the buffer(s) are performed using the caller's PSW
key.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of an 8-bit field that contains the storage key in the
format B'kkkkxxxx', where kkkk is the key and xxxx is ignored.
- ,COCLASS=coclass
- Use this input parameter to specify the cast-out class for which
directory names and directory entry user data should be retrieved.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 2-byte field that contains the cast-out class value.
- ,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.
- ,DIRINFOFMT=NAMELIST
- ,DIRINFOFMT=DIRENTRYLIST
- Use this input parameter to specify the amount of information
to be returned for each directory entry.
DIRINFOFMT is meaningful
only for structures allocated in a coupling facility of CFLEVEL=5
or higher.
- NAMELIST
- Return a subset of the information for each directory. The information
returned includes:
- Name
- User data
- Size of the data entry.
- DIRENTRYLIST
- Return all information for each directory. The information returned
includes:
- Name
- User data
- Storage class assigned to
- Indication of whether data is currently cached
- Indication of whether data is changed (if cached)
- Castout class assigned to (if changed)
- Parity bits
- Value and state of the cast-out lock
- Indication of which connected users have registered interest
- Size of the data entry
- Version number.
See the IXLYDEIB macro for the format of the data returned
in the BUFFER area or the BUFLIST buffers.
- ,EXTRESTOKEN=NO_EXTRESTOKEN
- ,EXTRESTOKEN=extrestoken
- Use this input parameter to specify an extended restart token
that can be used to resume processing of a READ_COCLASS request that
completed prematurely because it exceeded the model-dependent time-out
criteria or because the specified buffer area is full. The extended
restart token is returned in the answer area (field CAAEXTRESTOKEN),
and should be specified on the next READ_COCLASS 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 the buffer
does not become full, 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.
- ,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.
- ,NAME=NO_NAME
- ,NAME=name
- Use this input parameter to filter by name, the data item for
which directory entry data will be read. You may use this parameter
along with the NAMEMASK parameter to select certain data items. See
the NAMEMASK parameter for more information on this option.
The
entry name and user data associated with NAME, possibly NAMEMASK,
and the specified cast-out class (COCLASS) are retrieved. If NAME
is not specified, all the data items in the specified cast-out class
are read.
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 (using a register
from 2 to 12) of a 2-byte field that contains the bit-mask for the
name specified on the NAME keyword.
- ,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.
- ,RESTOKEN=NO_RESTOKEN
- ,RESTOKEN=restoken
- Use this input parameter to specify a restart token that can be
used to resume processing of a READ_COCLASS request that completes
prematurely because it exceeds the model-dependent time-out criteria
or the specified buffer area (BUFLIST or BUFFER) is full. The restart
token is returned in the answer area, and should be specified on the
next READ_COCLASS request to resume processing with the next directory
entry to be processed.
If the request does not exceed the model-dependent
time-out criteria or the buffer does not become full, the returned
token will contain all binary zeros.
Note: - Specifying an extended 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.
- ,RTATYPE=NORMAL
- ,RTATYPE=ENHANCED
- Use this input parameter to specify the restart token algorithm
that can be used to resume processing of a READ_COCLASS request that
completed prematurely.
- NORMAL
- Use the normal restart token algorithm. The normal restart token
algorithm might return duplicate entries that match the user's requested
filtering criteria in some cases, and also miss entries that match
the user's requested filtering criteria in some cases. When using
this option, be prepared to handle any duplicate entries that might
be returned.
- ENHANCED
-
Use the enhanced restart token algorithm. The enhanced restart
token algorithm might return duplicate entries that match the user's
requested filtering criteria in some cases; however, unlike the normal
algorithm, it will never miss any entries that match the requested
filtering criteria. When using this option, be prepared to handle
any duplicate entries that may be returned.
Note: The request
to use the enhanced restart token algorithm might or might not be
honored, depending on the presence or absence of the required support
in the coupling facility that contains the cache structure. CaaEnhancedRtAlgPresent,
the cache answer area field, will indicate whether the coupling facility
support for the enhanced restart token algorithm is present and thus,
whether it is possible to honor this request.
- ,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.
|