![](dblue_rule.gif) |
The parameter descriptions for REQUEST=WRITE are listed in alphabetical
order. Default values are underlined: - REQUEST=WRITE
- Use this input parameter to write data to a list entry.
- ,ADJAREA=NO_ADJAREA
- ,ADJAREA=adjarea
- Use this input parameter to specify a storage area to contain
the adjunct data to be written to the existing or new entry.
Specify
ADJAREA only for structures that support adjunct data. (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.
- ,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 mapping macro IXLYLAA.
On a successful completion (for a synchronous request: RC=0, for
an asynchronous request: ECB is posted, IXLFCOMP indicates completion,
or your complete exit ran) of the request, the following information
is returned to the answer area:
- List entry controls of the existing or new entry (field LAALCTL).
- The number of list entries or elements residing on the list (field
LAALISTCNT).
- The total number of allocated entries in the structure (field
LAATOTALCNT).
- The total number of allocated elements in the structure (field
LAATOTALELECNT).
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of an area (with a length of ANSLEN) that will contain
the information returned by the request.
- ,ANSLEN=anslen
- Use this input parameter to specify the size of the storage area
specified by ANSAREA.
Check the prologue of the IXLYLAA mapping macro for the minimum
required size of the answer area, or use the length field (LAA_LEN)
in the LAA.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 2-byte field that contains the size, in bytes,
of the answer area.
- ,AUTHCOMP=NO_AUTHCOMP
- ,AUTHCOMP=authcomp
- Use this input parameter to specify a value to be compared to
the list authority value of the list specified by LISTNUM. You must
supply the LISTNUM parameter.
If the comparison does not meet the condition specified by the
AUTHCOMPTYPE parameter (EQUAL or LESSOREQUAL), the request fails.
Note: The AUTHCOMP parameter is valid only for list structures allocated
in a coupling facility with CFLEVEL=1 or higher.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of the 16-byte field that contains the list authority
value.
- ,AUTHCOMPTYPE=EQUAL
- ,AUTHCOMPTYPE=LESSOREQUAL
- Use this input parameter to specify how the list authority comparison
is to be performed.
- EQUAL
- The list authority for the list specified by LISTNUM must be equal
to the value specified for AUTHCOMP.
- LESSOREQUAL
- The list authority for the list specified by LISTNUM must be less
than or equal to the value specified for AUTHCOMP.
Note: The AUTHCOMPTYPE parameter is valid only for list structures
allocated in a coupling facility with CFLEVEL=1 or higher.
- ,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 existing or new entry. Only
31-bit addressable (below 2GB) virtual storage areas are supported
for the BUFFER specification.
You
can define the buffer size to be a total of up to 65536 bytes. Depending
on the size you select, the following restrictions apply: - 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.
- 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.
See the BUFSIZE parameter description for defining the
size of the buffer.
Note: You cannot code BUFFER with MODE=ASYNCNORESPONSE.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of an area (with a length of BUFSIZE) that contains the entry
data.
- ,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 existing or new entry. BUFLIST
specifies a 128-byte storage area that consists of a list of 0 to
16 buffer addresses.
The 128-byte storage area must: - Consist of 0 to 16 elements.
- Each element consists of an 8-byte field in which:
- The left (high-order) four bytes are reserved and
- The right (low-order) four bytes contain the address of a buffer.
The BUFLIST buffers must: - Reside in the same address space or data space.
- Be the same size: either 256, 512, 1024, 2048, or 4096 bytes.
- Start on a 256-byte boundary and not cross a 4096-byte boundary.
Note: The buffers do not have to be contiguous in storage. List services
treats BUFLIST buffers as a single, contiguous buffer, even if the
buffers are not contiguous.
See BUFNUM and BUFINCRNUM parameter
descriptions for defining the number and size of buffers.
Note: You cannot code BUFLIST with MODE=ASYNCNORESPONSE.
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 written to the list entry.
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 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.
- ,CONTOKEN=contoken
- Use this input parameter to specify the connect token that was
returned by the IXLCONN service. The connect token uniquely identifies
your connection to the list structure, and must be specified on each
IXLLIST invocation.
The connect token is available in the IXLCONN answer area mapped
by IXLYCONA.
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.
- ,CURSORUPDTYPE=NEXT
- ,CURSORUPDTYPE=NEXTCOND
- ,CURSORUPDTYPE=CURRENT
- ,CURSORUPDTYPE=CURRENTCOND
- Use this input parameter to specify how the list cursor is to
be updated when UPDATECURSOR=YES is specified.
Note: The NEXTCOND,
CURRENT, and CURRENTCOND values are valid only for list structures
allocated in a coupling facility with CFLEVEL=1 or higher.
- CURSORUPDTYPE=NEXT
- Update the list cursor to point to the list entry before or after
the target entry. The direction of the cursor update depends on the
value specified for LISTPOS or LISTDIR.
- CURSORUPDTYPE=NEXTCOND
- Update the list cursor to point to the list entry before or after
the target entry only if the target list entry is moved or deleted.
You set the list cursor direction (so that it will point to either
before or after the target entry) with SETCURSOR on a WRITE_LCONTROLS
request.
The list cursor will be reset to binary zeros if
either: - The entry is the last entry on the list and the list cursor direction
is set to a head-to-tail direction.
- The entry is the first entry on the list and the list cursor is
set to a tail-to-head direction.
- CURSORUPDTYPE=CURRENT
- Set the list cursor to point to the list entry processed for the
request.
If the list entry is deleted or moved to another list,
then the list cursor will be reset to binary zeros.
- CURSORUPDTYPE=CURRENTCOND
- Set the list cursor to point to the list entry processed only
if the list cursor value currently is zero and the target list entry
is not deleted or moved to another list.
If the list entry is
deleted or moved to another list, then the list cursor will remain
binary zeros.
- ,ELEMNUM=elemnum
- Use this input parameter to specify the number of elements to
be allocated to the existing or new data entry. Valid ELEMNUM values
are from zero to the MAXELEMNUM value that was specified on the IXLCONN
macro.
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 the ELEMNUM value specified.
Note: If the data from the buffers exceeds the amount of space in
the elements, the data will be truncated. If the data from the buffers
is less than the amount of space in the elements, the remaining space
will be padded with binary zeros.
If you specify an ELEMNUM value of zero:
- No entry data will be written to the new entry.
- Any entry data in the existing entry will be deleted.
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.
- ,ENTRYID=entryid
- Use this input parameter to designate the entry identifier of
an existing entry to be updated. ENTRYID applies only to locating
an existing entry; it does not determine the identifier of a new entry
should one be created.
If an entry with this identifier does not
exist (and ENTRYTYPE=ANY or ENTRYTYPE=NEW is specified) a new entry
is created on the LISTNUM list with a unique entry identifier assigned
by list services.
The new entry identifier is returned in the answer area in the field
LCTLENTRYID in LAALCTL. (The entry identifier you specify will be
ignored.)
When ENTRYID is specified with ENTRYNAME, ENTRYKEY,
or LISTPOS, list services uses
only ENTRYID to determine if the entry already exists.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of a 12-byte field that contains the entry identifier.
- ,ENTRYKEY=NO_ENTRYKEY
- ,ENTRYKEY=entrykey
- Use this input parameter to either:
- Designate the entry key of an existing entry to be updated.
- Assign an entry key of your choice to a new entry.
The existing entry must reside on the LISTNUM list; the
new entry will be created on the LISTNUM list.
Whether the
specified entry key designates an existing entry or is assigned to
a new entry depends on what ENTRYTYPE value you specify and whether
the entry already exists.
If there is a sublist of entries
on the list all with the same key as the ENTRYKEY key (or that satisfies
the KEYREQTYPE criteria, if specified), the LISTPOS parameter determines
which entry in the sublist (the HEAD or TAIL entry) is updated, or,
if an entry is created, at which end of the sublist (the HEAD or TAIL)
the new entry is positioned.
If this request creates a new
entry, but ENTRYKEY is not specified (and the structure supports keyed
entries), list services assigns
a default key value to the new entry as follows: - If LISTPOS=HEAD, the new list entry key is set to all binary zeros.
- If LISTPOS=TAIL, the new list entry key is set to all binary ones.
Specify ENTRYKEY only for structures that support keyed
entries.
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of a 16-byte field that contains the
entry key.
- ,ENTRYNAME=entryname
- Use this input parameter to either:
- Designate the entry name of an existing entry to be updated.
- Assign an entry name to a new entry to be created.
The new entry will be created on the LISTNUM list. The existing
entry can reside on any list.
Specify ENTRYNAME only for structures
that support named entries. Each entry name is unique within the 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 entry name.
- ,ENTRYTYPE=ANY
- ,ENTRYTYPE=OLD
- ,ENTRYTYPE=NEW
- Use this input parameter to specify whether you want to create
a new entry, update an existing entry, or either.
- ANY
- Either update an existing entry or create a new entry. If the
designated entry exists, its data is replaced with the new data. If
the designated entry does not exist, one will be created with the
new data.
- OLD
- Update an existing entry. The designated entry must already exist,
or the request fails.
- NEW
- Create a new entry.
- If you specify ENTRYNAME, a new entry is created only if the entry
does not already exist. If the entry exists, the request fails.
- If you specify ENTRYKEY, a new entry will be created regardless
of whether another entry with the same key already exists on the designated
list.
- If you specify LISTPOS without ENTRYNAME or ENTRYKEY, a new entry
is created at the specified HEAD or TAIL of the list.
Note: When a new entry is created, the ENTRYID is returned
in the answer area in the LCTLENTRYID field of LAALCTL.
- ,KEYREQTYPE=EQUAL
- ,KEYREQTYPE=LESSOREQUAL
- ,KEYREQTYPE=GREATEROREQUAL
- Use this input parameter to specify how, if at all, the entry
key of the existing entry to be updated can differ from the entry
key specified by ENTRYKEY. KEYREQTYPE applies only to locating an
existing entry; it does not determine the key of a new entry should
one be created.
- EQUAL
- The entry must have a key that equals the ENTRYKEY key.
- LESSOREQUAL
- The entry must have a key that is less than or equal to the ENTRYKEY
key.
- GREATEROREQUAL
- The entry must have a key that is greater than or equal to the
ENTRYKEY key.
Note: - When no entries on the list meet the requirements of the KEYREQTYPE,
and a new entry cannot be created (ENTRYTYPE=OLD was specified), the
request will be failed with a return code X'8' and reason
code IXLRSNCODENOENTRY, or a new list entry will be allocated, depending
on the other options specified (ENTRYTYPE=NEW or ENTRYTYPE=ANY).
- When LESSOREQUAL or GREATEROREQUAL are specified, if no entries
on the list have an entry key value equal to the specified value,
but entries exist with an entry key value greater than (if GREATEROREQUAL
was specified), or less than (if LESSOREQUAL was specified) the entry
key value specified, the entry with an entry key value closest to
the value specified will be selected. When multiple entries have
the same entry key value, LISTPOS is used to resolve whether the first
or last entry with the entry key value is selected.
- ,LISTDIR=TOTAIL
- ,LISTDIR=TOHEAD
- Use this input parameter with UPDATECURSOR to specify the direction
in which the list cursor is moved as a result of this request. See
the UPDATECURSOR parameter for a full description of LISTDIR.
- ,LISTKEYINC=NO_LISTKEYINC
- ,LISTKEYINC=listkeyinc
- Use this input parameter to specify a value to be added to the
list key after the entry key is set to the list key value. If the
entry key is not set to the list key value, the list key value will
not be changed. If the result of adding the value specified by LISTKEYINC
to the list key value is greater than the maximum list key value,
the system fails the request.
Note: The LISTKEYINC parameter is valid only for list structures allocated
in a coupling facility with CFLEVEL=1 or higher.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of the fullword field that contains the value to be
added to the list key after the entry key is set to the list key value.
- LISTKEYTYPE=NOLISTKEY
- LISTKEYTYPE=CREATE
- LISTKEYTYPE=ANY
- Use this input parameter to specify when the designated entry
key is to be set to the current list key value. You can set the entry
key to the current list key value when you create the entry.
(Set the list key and maximum list key values with a WRITE_LCONTROLS
request.)
Note: The LISTKEYTYPE parameter is valid only for list structures
allocated in a coupling facility with CFLEVEL=1 or higher.
- LISTKEYTYPE=NOLISTKEY
- Do not set the entry key for the target list entry to the current
list key value. If the list entry is created and the list structure
supports entries with keys, then the other parameters specified (such
as ENTRYKEY) will determine the resultant entry key value.
- LISTKEYTYPE=CREATE
- Set the entry key for the designated list entry to the current
list key value if the entry is created by this request.
- LISTKEYTYPE=ANY
- Set the entry key for the designated list entry to the current
list key value if the entry is created by this request. (This parameter
also applies when you MOVE an entry.)
- ,LISTNUM=NO_LISTNUM
- ,LISTNUM=listnum
- Use this input parameter to specify the number of the list to
which the data will be written. Use LISTNUM in the following ways:
- With LISTPOS and/or ENTRYKEY to designate an existing entry to
be updated, or a position on the list for a new entry.
- With ENTRYID or ENTRYNAME to:
- Check if the entry exists on the list (when ENTRYTYPE=ANY) before
proceeding with the request.
- Confirm that the entry exists on the list (when ENTRYTYPE=OLD)
before proceeding with the request.
- Confirm that the entry does not exist on the list (when ENTRYTYPE=NEW)
before proceeding with the request.
- With LOCBYCURSOR to designate an existing entry to be updated.
To Code: Specify the RS-type name or address (using
a register from 2 to 12) of a 4-byte field that contains the number
of the list.
- ,LISTPOS=HEAD
- ,LISTPOS=TAIL
- Use this input parameter to designate either:
- The position on the LISTNUM list where the new entry is placed
(if this request creates a new entry).
- The existing entry that is to be updated (if this request updates
an existing entry).
LISTPOS designates the position or entry at the HEAD or
the TAIL of a list or sublist: - If you specify ENTRYKEY to designate the position or entry and
the list contains a sublist of one or more entries with the same key
(or that satisfies the KEYREQTYPE criteria, if specified), then:
- LISTPOS=HEAD designates the position or entry at the head of the
sublist.
- LISTPOS=TAIL designates the position or entry at the tail of the
sublist.
- If you do not specify ENTRYKEY to designate the position or entry,
then:
- LISTPOS=HEAD designates the position or entry at the head of the
list.
- LISTPOS=TAIL designates the position or entry at the tail of the
list.
- ,LOCBYCURSOR
- Use this input parameter to designate an existing entry to be
updated. The designated entry is the entry which is identified by
the list cursor for a particular list (LISTNUM).
Be aware that
the list cursor could have been reset to zeros by a previous request
that, for instance, deleted or moved the entry to which the list cursor
points, or updated the list cursor after the last entry on the list
had been processed. See z/OS MVS Programming: Sysplex Services Guide for
more information about using the list cursor.
- ,LOCKCOMP=NO_LOCKCOMP
- ,LOCKCOMP=lockcomp
- This parameter has slightly different meanings based on the value
specified for the LOCKOPER parameter. Generally, this input parameter
specifies a connection identifier to be verified as the owner of the
lock specified by LOCKINDEX. This verification is a prerequisite to
the successful completion of the request.
When LOCKCOMP is specified, the completion of the request is conditional
on there being no contention for the lock. If contention exists, the
request will fail.
The connection identifier is available from the IXLCONN answer
area, mapped by IXLYCONA, in field CONACONID.
The effect of LOCKCOMP is based on the LOCKOPER value specified.
See the description under LOCKOPER to see how each request is affected
by this parameter.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 1-byte field that contains the connection identifier.
- ,LOCKDATA=NO_LOCKDATA
- ,LOCKDATA=lockdata
- Use this input parameter to specify information that is to be
passed to your notify exit when another user requests the LOCKINDEX
lock after you have obtained the lock using LOCKOPER=SET. This user-defined
information will be passed to your notify exit when the other user
issues a request specifying either one of the following:
- LOCKOPER=SET
- LOCKOPER=NOTHELD with LOCKMODE=UNCOND
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 information.
- ,LOCKINDEX=NO_LOCKINDEX
- ,LOCKINDEX=lockindex
- Use this input parameter to specify the index of the lock to be
operated on as specified by LOCKOPER. The lock indexes begin with
zero.
Note: You cannot code LOCKINDEX with MODE=ASYNCNORESPONSE.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a 4-byte field that contains the lock index.
- ,LOCKMODE=UNCOND
- ,LOCKMODE=COND
- Use this input parameter to specify how contention for the lock
specified by LOCKINDEX should be handled if your request causes lock
contention.
- UNCOND
- If the specified lock is held by another user, your request is
either:
- Suspended until the lock becomes available (if MODE=SYNCSUSPEND
is specified).
- Performed asynchronously with notification to you when the request
completes (if any MODE value other than SYNCSUSPEND is specified).
- COND
- The lock operation will be performed conditionally; that is, only
if there is no contention for the lock. If the specified lock is held
by another user, the request will be terminated with no change to
the structure, and return and reason codes describing the termination
are returned to the caller.
- ,LOCKOPER=SET
- ,LOCKOPER=RESET
- ,LOCKOPER=NOTHELD
- ,LOCKOPER=HELDBY
- Use this input parameter to specify the type of operation to be
performed on the lock specified by LOCKINDEX.
- SET
- Set the lock.
- When LOCKCOMP is not specified, your connection gets the lock,
providing no other connection holds the lock. If another connection
holds the lock, the request either continues once the lock is released
or fails, depending on the LOCKMODE value you specify.
- When LOCKCOMP is specified, if the connection specified by LOCKCOMP
holds the lock, the lock will be transferred to your connection.
- RESET
- Reset the lock.
- When LOCKCOMP is not specified, the lock will be released if it
is held by your connection.
- When LOCKCOMP is specified, the lock will be released if it is
held by the connection specified by LOCKCOMP.
- NOTHELD
- The request is performed only if the lock is not held by any connection.
This option also ensures that the lock remains free for the duration
of the request. If another connection holds the lock, your task is
suspended until the lock is released or your request fails, depending
on the LOCKMODE value you specify. See the LOCKMODE description for
how to handle possible lock contention.
- HELDBY
- Processing is determined by which connector is holding the lock.
- When LOCKCOMP is not specified, the request is performed only
if your connection holds the lock.
- When LOCKCOMP is specified, the request is performed only if the
lock is held by the connection specified by LOCKCOMP.
- ,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
- ,MODE=ASYNCNORESPONSE
- 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
- MODE=SYNCSUSPEND
- The request is suspended until it can complete synchronously.
To use this option, your program must be enabled for I/O and external
interrupts.
- MODE=SYNCECB
- The request processes synchronously if possible. If the request
processes asynchronously, the ECB specified by REQECB is posted when
the request completes.
- MODE=SYNCEXIT
- The request processes synchronously if possible. If the request
processes asynchronously, your complete exit is given control when
the request completes.
- MODE=SYNCTOKEN
- The request processes synchronously if possible. If the request
processes asynchronously, an asynchronous request token is returned
in the area specified by REQTOKEN on invocation of the request. 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.
- MODE=ASYNCECB
- The request processes asynchronously. The ECB specified by REQECB
is posted when the request completes.
- MODE=ASYNCEXIT
- The request processes asynchronously. Your complete exit is given
control when the request completes.
- MODE=ASYNCTOKEN
- The request processes asynchronously. An asynchronous request
token is returned in the area specified by REQTOKEN upon invocation
of the request. 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.
- MODE=ASYNCNORESPONSE
- The request processes asynchronously. No notification of request
completion is provided. The answer area (ANSAREA) fields will not
contain valid information when this mode is specified.
Note: You cannot code MODE=ASYNCNORESPONSE with LOCKINDEX, BUFFER,
or BUFLIST.
- ,NEWAUTH=NO_NEWAUTH
- ,NEWAUTH=newauth
- Use this input parameter to specify a list authority value for
the list specified by LISTNUM. If NEWAUTH is omitted, the list authority
for the designated list is unchanged.
When the structure is allocated, the authority value for each list
is initialized to binary zeros.
Note: The NEWAUTH parameter is valid only for list structures allocated
in a coupling facility with CFLEVEL=1 or higher, except on WRITE_LCONTROLS
requests.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of the 16-byte field that contains the list authority
value.
- ,NEWVERS=newvers
- Use this input parameter with VERSUPDATE=SET to specify a version
number to either replace the version number of the existing entry,
or initialize the version number of a new entry.
To Code:
Specify the RS-type name or address (using a register from 2 to 12)
of an 8-byte field that contains the entry version number.
- ,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 IXLLIST 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.
- ,UPDATECURSOR=NO
- ,UPDATECURSOR=YES
- Use this input parameter to specify whether the list cursor, for
the list specified by LISTNUM, is to be updated to point to another
entry on the list.
- NO
- The list cursor is not updated.
- YES
- The list cursor is updated according to the specification of the
CURSORUPDATE keyword.
The list cursor is set to binary zeros if
its new position would be before the first entry or after the last
entry in the list.
- ,VERSCOMP=NO_VERSCOMP
- ,VERSCOMP=verscomp
- Use this input parameter to specify a version number to be compared
to the version number of the existing entry to be updated. If this
request creates a new entry, the VERSCOMP specification is ignored.
The entry is updated only if its version number meets the condition
specified by the VERSCOMPTYPE parameter.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of an
8-byte field that contains the version number.
- ,VERSCOMPTYPE=EQUAL
- ,VERSCOMPTYPE=LESSOREQUAL
- Use this input parameter to specify how a list entry version number
comparison as specified by VERSCOMP is to be performed.
Note: The VERSCOMPTYPE parameter is valid only for list structures
allocated in a coupling facility with CFLEVEL=1 or higher.
- VERSCOMPTYPE=EQUAL
- The version number for the list entry must be equal to the value
specified for VERSCOMP.
- VERSCOMPTYPE=LESSOREQUAL
- The version number for the list 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 version number of
the existing entry will be updated, or, for those cases where a new
entry is created, initialized.
- VERSUPDATE=NONE
- The existing entry's version number is not updated. The new entry's
version number is initialized to binary zeros.
- VERSUPDATE=INC
- The existing entry's version number is increased by one. The new
entry's version number is initialized to binary zeros, except for
the low-order bit, which is set to one.
- VERSUPDATE=DEC
- The existing entry's version number is decreased by one. The new
entry's version number is initialized to all binary ones.
- VERSUPDATE=SET
- Both the existing and the new entry's version number is set to
the value specified by NEWVERS.
|