Parameter Descriptions
- REQUEST=CROSS_INVALLIST
- Use this input parameter to specify that a cross-invalidate operation be performed against a given set of 1 to 4096 entries specified by a list of names in the BUFFER storage area or the buffers specified by BUFLIST. STARTINDEX and ENDINDEX determine the set of names provided by the user in the BUFFER or BUFLIST that will be processed by the request. Valid STARTINDEX and ENDINDEX values are 1-origin. The result of the operation is that with the exception of the connection specified by CONTOKEN, all connections that registered interest in the specified entries have interest deregistered and a cross-invalidate performed against their local caches.
- ,ANSAREA=NO_ANSAREA
- ,ANSAREA=ansarea
- Use this output parameter to specify an answer area to contain information returned from the
request if the request does not complete successfully or if the request initiated asynchronous
cross-invalidations. See the return and reason codes descriptions for this request to determine
which fields in the answer area are valid for non-zero return codes.
An asynchronous cross-invalidation sequence number (CAAASYNCXISEQNUM) 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).
- ,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
- ,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 (by using a register 2 - 12) of a 4-byte field that contains the ALET.
- ,BUFFER=buffer
- Use this input parameter to specify a buffer area to contain the set of 16-byte structure entry
names on which a cross-invalidate operation is to be performed.
Only 31-bit addressable virtual storage areas (below 2GB) are supported by the BUFFER specification. High virtual storage areas (above 2GB) can only be specified via the BUFLIST specification.
Requirements for the buffer length are as follows:- 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 structure entry names.
- If you specify a buffer size of less than or equal to 4096 bytes, you must ensure that the
buffer:
- ,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 (by using a register 2 - 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 structure entry names
identifying the entries on which a cross-invalidate operation is to be performed. BUFLIST specifies
a 128-byte storage area that consists of a list of 1 to 16 buffer address elements.
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 (by using a register 2 - 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.
- ,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.
- ,ENDINDEX=endindex
- Use this input parameter to specify the index into the name elements in the buffer storage area
or the buffers specified by BUFLIST of the last name element to be processed. 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 halfword 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 element
if an entry is not found.
- CONTINUE
- If an error occurs, processing is to continue with the next name element.
- TERMINATE
- If an error occurs, processing is to halt and the index of the name element that caused the error is returned in the answer area.
- ,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.
- 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.
- ,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.
- ,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.
- ,STARTINDEX=startindex
- Use this input parameter to specify the starting index for name element processing. Valid
STARTINDEX values are from 1 to the value of ENDINDEX. The first name element has index number 1.
To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword field containing the starting index value.