Parameter Descriptions

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

REQUEST=WRITE_DATA

Use this input parameter to specify that the data item identified by NAME be written from the areas specified by BUFFER or BUFLIST, and/or ADJAREA to the cache structure.

,ADJAREA=NO_ADJAREA

,ADJAREA=adjarea

Use this input parameter to specify a storage area to contain the adjunct data to be written to an entry in the cache structure. Specify ADJAREA only when ELEMNUM is greater than 0.

If the structure supports adjunct data and ADJAREA is not specified or ADJAREA=NO_ADJAREA is specified, binary zeros are written to the adjunct area. If the structure does not support adjunct data and ADJAREA is specified, ADJAREA is ignored. (Adjunct areas for a structure are established through the IXLCONN macro.)

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-byte area that contains the adjunct data you want associated with this data entry.

,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. On a successful completion of a request, the following information is returned in the answer area:

If changed data is written to the cache, the total number of entries containing either changed or locked-for-cast-out data, that are assigned to the storage class to which the entry was written, is returned (field CAATOTCHANGED).
If changed data is written to the cache, the total number of data items assigned to the cast-out class to which data was just written is returned (field CAACOCOUNT).
If WHENREG=NO was specified and the request replaced a previously specified vector index for the entry, the replaced vector index is returned (fields CAAINVLCVINUM and CAAINVLCVI).

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 may 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).

,ASSIGN=YES

,ASSIGN=NO

Use this input parameter to specify whether a directory entry will be assigned for NAME if one does not currently exist.

YES: A directory entry will be assigned.
NO: No directory entry will be assigned.
ASSIGN=NO is meaningful only for cache structures allocated in a coupling facility of CFLEVEL=9 or higher.

,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 hold the entry data to be written to the cache structure. 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.

You can define the buffer size to be a total of up to 65536 bytes. 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 data to be written to the entry in the structure.

,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 entry data to be written to the cache structure. BUFLIST specifies a 128-byte storage area that consists of a list of 0 to 16 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 specifications for the BUFADDRTYPE and BUFADDRSIZE 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:

All 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.

For structures allocated in CFLEVEL=0 through CFLEVEL=3 coupling facilities, one of BUFFER or BUFLIST is required. For structures allocated in CFLEVEL=4 or higher coupling facilities, one of BUFFER or BUFLIST is required when CHANGED=YES and optional when CHANGED=NO.

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 storage 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 written to the entry. If you do not want buffers, but want to specify this parameter, code BUFNUM=NO_BUFNUM.

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 buffer list.

,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.

,CHANGED=NO

,CHANGED=YES

Use this input parameter to specify whether changed data is to be written to an entry in the cache structure.

NO

The data to be written is unchanged:

The cached copy is the same as the permanent storage copy.
In a store-through process, the permanent storage copy will be updated (by the user) to match the cached copy, either before the cast-out lock is released (if GETCOLOCK=YES was specified), or before serialization on the named data item is released.

If the entry already exists in the structure, the entry must contain unchanged data or the request will fail. You cannot overwrite changed data with unchanged data.

For structures allocated in CFLEVEL=4 or higher coupling facilities, ELEMNUM=0 and one of BUFFER and BUFLIST are optional when CHANGED=NO is specified.

YES

The data to be written is changed. The changed data will be assigned to the specified cast-out class (COCLASS) superseding any previously specified cast-out class for the data. With the exception of your connection, all users with registered interest in the data will have their interest deregistered such that their locally cached copies of the data are invalidated.

,COCLASS=coclass

Use this input parameter to specify the cast-out class to which the data item being written is to be assigned. Any previous assignment is updated to the new specification.

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.

,CROSSINVAL=NO

,CROSSINVAL=YES

Use this input parameter to specify whether cross-invalidate processing should be performed when writing unchanged data.

NO: Cross-invalidate processing is not performed. All users with registered interest in the data item remain registered, and the copies of the data item in their local cache buffers remain valid.
YES: Cross-invalidate processing is performed. All users with registered interest in the data item, with the exception of your connection, have their interest deregistered and the copies of the data item in their local cache buffers invalidated.

,ELEMNUM=elemnum

Use this input parameter to specify the number of elements to be allocated to the data entry. Valid ELEMNUM values are from 0 to the MAXELEMNUM value that was returned to the connector in the connect answer area. For structures allocated in a CFLEVEL=0 coupling facility, ELEMNUM values can be in the range of 1 to 16. For structures allocated in coupling facilities with a CFLEVEL between CFLEVEL=1 and CFLEVEL=3, ELEMNUM values can be in the range of 1 to 255. For structures allocated in coupling facilities with a CFLEVEL=4 or higher, ELEMNUM values can be in the range of 0 to 255 where 0 is valid only when CHANGED=NO.

Considerations for specifying ELEMNUM are:

If this request creates a new entry, the number of elements is set to the ELEMNUM value.
If the entry already exists, the number of elements is updated to this ELEMNUM value.

If the data passed in BUFFER/BUFLIST does not fill up all the space in the elements, the extra space will be padded with zeros. If the data passed in BUFFER/BUFLIST is greater than the amount of space in the elements, the data will be truncated.

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 elements.

,GETCOLOCK=NO

,GETCOLOCK=YES

Use this input parameter to specify whether the cast-out lock should be obtained when writing unchanged data.

NO: The cast-out lock is not obtained.
YES: The cast-out lock is obtained.

,LOCALREGCNTLNO

,LOCALREGCNTL=YES

Use this keyword to specify whether the WRITE_DATA request should be suppressed (write suppression) when the user's connection (local cache) is the only registered interest in the data item identified by NAME in the cache structure, and no subsystem data (data entry) for the data item is cached.

LOCALREGCNTL=YES is only meaningful when write requests are issued to cache structures allocated in a coupling facility that supports write suppression based on local cache registration. If the cache structure is allocated in a coupling facility that does not support write suppression based on local cache registration, the WRITE_DATA request will be performed as if LOCALREGCNTL=NO was specified.

NO

The WRITE_DATA request will be performed normally without write suppression.

YES

Suppress the WRITE_DATA request when the user's connection is the only registered interest in the directory entry and the data entry does not have cached subsystem data. When the write operation is suppressed, no data is written to the cache structure. The WRITE_DATA request will complete with a return code IXLRETCODEWARNING, reason code IXLRSNCODELOCALREGWRTSUPPRESS.

If LOCALREGCNTL=YES is requested on a WRITE_DATA request for a cache structure that is currently in the system-managed Duplex Established phase, the request for write suppression is ignored.

CHANGED=YES is required when LOCALREGCNTL=YES is specified.

When the subsystem data is not written to the cache structure, the local cache buffer contains the only valid copy of the subsystem data. Hardening of the subsystem data to permanent storage should be performed to ensure availability and successful recovery of data in the event of a failure.

When issuing a WRITE_DATA request with LOCALREGCNTL=YES to write data to a cache structure that is in user-managed duplex mode, the following programming technique should be followed:

When using registration, assignment or write suppression protocols in the primary structure of a user-managed duplexed structure, unconditional writes of changed data to the secondary structure specifying LOCALREGCNTL=NO should be performed after successful write operations to the primary structure. If the write operation to the primary structure resulted in the write being suppressed, then the write operation should not be issued to the secondary structure.

,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=name

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

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.

,NEWVERS=newvers

Use this input parameter to specify the value that is to be assigned to the entry version number.

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

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

,OLDNAME=NO_OLDNAME

,OLDNAME=oldname

Use this input parameter to specify the name of the data item for which your interest should be deregistered.

For structures allocated in a coupling facility of CFLEVEL=4 or lower, you must also specify the name of the data item for which interest is to be registered after the interest is deregistered in OLDNAME. Identify the data item to which interest is to be registered with NAME. The VECTORINDEX currently associated with the entry specified by OLDNAME will be reassigned to the name of the data item specified by NAME.
For structures allocated in a coupling facility of CFLEVEL=5 or higher, you can specify that interest in the name of the data item specified by OLDNAME is to be deregistered without registering interest in the entry specified by NAME.

In either case, whenever deregistration of interest is requested, VECTORINDEX must be specified.

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 old data item that was associated with VECTORINDEX.

,PARITY=00110000

,PARITY=parity

Use this input parameter to update the directory entry parity bits for the data item specified by NAME. The parity bits are updated only when CHANGED=YES is specified and the initial value of the directory entry parity bits is null (that is, B'11'). If these conditions are not met, the PARITY value is ignored.

Bits two and three of the 8-bit PARITY field are the parity bits. Valid parity values are:

xx00xxxx - Parity equals 0
xx01xxxx - Parity equals 1
xx11xxxx - Null (parity is not set)

Note that when a directory entry is created, the parity bits are initialized to the null value.

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

,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.

,PROCESSID=NO_PROCESSID

,PROCESSID=processid

Use this input parameter to specify a user-defined process identifier to be compared with the cast-out lock along with the connection identifier.

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

,REGUSER=YES

,REGUSER=NO

Use this input parameter to specify, for structures allocated in coupling facilities with CFLEVEL=5 or higher, whether the request should register connection interest in the entry.

YES: Specify this option to indicate that connection interest registration will be performed.
VECTORINDEX is required when REGUSER=YES is either specified or selected by default.
NO: Specify this option to indicate that no connection interest will be registered. Be careful when using REGUSER=NO because preference to reclaiming is given to entries that have data but no registered interest.
VECTORINDEX is required when REGUSER=NO is specified along with OLDNAME for the deregistration of interest. VECTORINDEX is ignored when REGUSER=NO is specified without the specification of OLDNAME.

,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.

,STGCLASS=stgclass

Use this input parameter to assign a storage class to the data item being written. Any previous assignment is updated to the new specification.

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 class.

,USERDATA=NO_USERDATA

,USERDATA=userdata

Use this input parameter to specify user-defined information to be written to the directory entry for the data item specified by NAME. The information is written only if either of the following is true:

There is no entry data in the structure for NAME.
There is unchanged entry data in the structure for NAME.

If one of these conditions is not met, USERDATA is ignored. If you do not want to write user data, but want to specify this parameter, code USERDATA=NO_USERDATA.

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 data.

,VECTORINDEX=vectorindex

Use this input parameter to specify an index into your local cache vector to be associated with the data item specified by NAME. The vector index identifies a vector entry that cache services will use to indicate both your interest in the data item and the validity of the copy of the data item in your local cache buffer.

With WHENREG=NO, for structures allocated in a coupling faciltiy with CFLEVEL=4 or lower, VECTORINDEX is required. If the vector index you specify is already associated with another data item, you must disassociate the vector index from the old name by specifying OLDNAME before the vector index can be associated with the data item specified by NAME.
For structures allocated in a coupling facility with CFLEVEL=5 or higher, VECTORINDEX is required when either REGUSER=YES or OLDNAME is specified with WHENREG=NO.
With WHENREG=YES, which is valid only when the cache structure is allocated in a CFLEVEL=2 or higher coupling facility, the vector index you specify must be the same as the vector index with which you currently have a registered interest in the data item. When VECTORINDEX is specified and the vector index does not equal the vector index with which you currently have a registered interest in the data item, the request fails. The vector index with which you are currently registered is returned in the cache answer area.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the vector index for NAME.

,VERSCOMP=NO_VERSCOMP

,VERSCOMP=verscomp

Use this input parameter to specify a version number 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 request is terminated with no resultant change to the structure.

Note that use of VERSCOMP is needed to ensure that updates to the version number requested with the VERSUPDATE keyword are not processed multiple times as a result of internal request redrive logic. When VERSCOMP is requested along with VERSUPDATE to update the version number, then if the initial execution of the request succeeds, any subsequent internal redrive of the request will fail due to a version number miscompare, preventing multiple updates from occurring on the request. Conversely, if the initial execution of the request was unsuccessful, then any subsequent internal redrive of the request will be able to execute successfully and update the version number only once.

In either of these cases, if the request is internally redriven and experiences a version number miscompare on the redrive, a return and reason code of IXLRSNCODESTATUSUNKNOWN will be returned. This reflects the fact that it is not known whether the observed version number miscompare resulted from the version number update succeeding on the original issuance of the request (causing the miscompare on the redriven request), or the observed version number miscompare was present all along, or resulted from a version number update made by another request. When this return and reason code is returned, it is up to the user to determine whether or not the requested update has actually occurred, and take the appropriate recovery action.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the comparative 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.

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.

,VERSUPDATE=NONE

,VERSUPDATE=INC

,VERSUPDATE=DEC

,VERSUPDATE=SET

Use this input parameter to specify how the entry version number will be updated or, for those cases where an entry is created, initialized.

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

Note that, depending on the VERSUPDATE specification, internal request redrive logic may cause a request to INCrement the version number more than once, DECrement the version number more than once, or SET the version number more than once. If it is necessary to ensure that this kind of multiple operation does not occur, version number comparison must also be requested. See the description of the VERSCOMP keyword.

VERSUPDATE=NONE: The version number is not updated.
On a request that causes an entry to be created, the version number is set to contain all binary zeros.
VERSUPDATE=INC: The version number will be incremented.
On a request that causes an entry to be created, the version number for the created entry is set to contain all binary zeros except for the low order bit, which is set to one.
VERSUPDATE=DEC: The version number will be decremented.
On a request that causes an entry to be created, the version number for the created number is set to contain binary ones.
VERSUPDATE=SET: The version number will be set to the value specified by NEWVERS, including the case where an entry is created.

,WHENREG=YES

,WHENREG=NO

Use this input parameter to specify whether previous registration of interest by the requesting user in the data item specified by NAME is a prerequisite to this request.

YES

The request is processed only if your interest in the data item is already registered. If your interest is not registered, the request will fail.

NO

The request is processed regardless of whether your interest in the data item is already registered.

If the entry already exists in the structure, the data and your interest is updated.
If the entry does not exist in the structure, a new entry is created, and your interest is registered.

See the VECTORINDEX parameter description for how to register interest in a data item.