Parameter Descriptions
- REQUEST=DELETE_MULT
- Use this input parameter to delete multiple entries from the list structure.
- ,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.
When the request completes, the answer area contains the number of deleted entries (field LAADELCNT).
If the request completes prematurely, a restart token (field LAARESTOKEN) or extended restart token (field LAAEXTRESTOKEN) is returned that may be specified on a subsequent DELETE_MULT request. (See the RESTOKEN and EXTRESTOKEN parameter descriptions.)
To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of ANSLEN) to contain the information related to 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 (by using a register 2 - 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 (by using a register 2 - 12 2 to ) of the 16-byte field that contains the list authority value.
- ,AUTHCOMPTYPE=EQUAL
- ,AUTHCOMPTYPE=LESSOREQUAL
- Use this input parameter specify how the list audit 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. - ,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 that is mapped by IXLYCONA.
To Code: Specify the RS-type name or address (by using a register 2 - 12) of a 16-byte field that contains the connect token.
- ,EXTRESTOKEN=NO_EXTRESTOKEN
- ,EXTRESTOKEN=extrestoken
- Use this input parameter to specify an extended restart token
that can be used to resume processing of a DELETE_MULT request that
completed prematurely. The extended restart token is returned in the
answer area (field LAAEXTRESTOKEN), and should be specified on the
next DELETE_MULT request to resume processing. If the request does not complete prematurely, the extended restart token will not be provided.Note:
- Specifying an extended restart token of all zeros causes list services to treat all of the entries as unprocessed.
- Do not specify an extended restart token other than the one returned in the answer area or one set to all zeros, because results will be unpredictable.
Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token. Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token (RESTOKEN).
To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the extended restart token.
- ,KEYCOMP=NO_KEYCOMP
- ,KEYCOMP=keycomp
- Use this input parameter to specify a value to be compared to the entry key of each list entry
in the designated list.
If the list entry that is to be processed does not have an entry key value that is equal to the specified KEYCOMP value, the entry is not processed. Processing continues with the next entry.
Note: The KEYCOMP 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 (by using a register 2 - 12 2 to ) of the 16-byte field that contains the value to be compared the entry key of the designated list entry.
- ,LISTNUM=NO_LISTNUM
- ,LISTNUM=listnum
- Use this input parameter to specify the number of the list on
which the entries to be deleted must reside. Specifying a list number
restricts delete processing to entries that reside on the designated
list.
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.
- ,LOCKCOMP=NO_LOCKCOMP
- ,LOCKCOMP=lockcomp
- This parameter has slightly different meanings based on the value that is 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 fails .
The connection identifier is available from the IXLCONN answer area, which is mapped which is 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 (by using a register 2 - 12) of a 1-byte field that contains the connection identifier.
- ,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 (by using a register 2 - 12) of a 4-byte field that contains the lock index.
- ,LOCKMODE=COND
- Use this input parameter specify that the lock operation for the lock specified by LOCKINDEe performed conditionally; that is, only if there is no contention for the lock. If the specified lock is held by another user, the request is terminated with no change to the structure, and return and reason codes describing the termination are returned to the caller.
- ,LOCKOPER=NOTHELD
- ,LOCKOPER=HELDBY
- Use this input parameter to specify the type of operation to be
performed on the lock specified by LOCKINDEX.
- LOCKOPER=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.
- LOCKOPER=HELDBY
-
- 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 that is specified by LOCKCOMP.
- ,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
- ,MODE=ASYNCNORESPONSE
- 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
- 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. - ,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 (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.
- ,RESTOKEN=NO_RESTOKEN
- ,RESTOKEN=restoken
- Use this input parameter to specify a restart token that can be
used to resume processing of a DELETE_MULT request that completed
prematurely because it exceeded the coupling facility model-dependent
time-out criteria. The restart token is returned in the answer area
(field LAARESTOKEN), and should be specified on the next DELETE_MULT
request to resume processing with the next entry to be deleted. If the request does not exceed the model-dependent time-out criteria, the returned token will not be provided.Note:
- Specifying an extended restart token of all zeros causes list services to treat all of the entries as unprocessed.
- Do not specify an extended restart token other than the one returned in the answer area or one set to all zeros, because results will be unpredictable.
Requestors that specify or default to IXLCONN ALLOWAUTO=NO must use the standard restart token. Requestors that specify IXLCONN ALLOWAUTO=YES must use the extended restart token (EXTRESTOKEN).
To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the restart token.
- ,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.
- ,VERSCOMP=NO_VERSCOMP
- ,VERSCOMP=verscomp
- Use this input parameter to specify a version number to be compared
to the version number of each entry to be deleted. Only those entries
with a version that meets the condition specified by the VERSCOMPTYPE
parameter will be deleted.
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 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.