 |
The parameter descriptions are listed in alphabetical order. Default
values are underlined: - ,ELEMADDRMODE=31
- ,ELEMADDRMODE=64
-
Use this parameter to specify the precision format of the
addresses located within the message data element at the offsets specified
by the PARTPTROFF and NEXTPTROFF keywords. The default is ELEMADDRMODE=31.
Use
ELEMADDRMODE=31 to indicate that all of the addresses in message data
elements are of 31-bit addressing precision (single word - 4 bytes)
and reference only virtual storage below the 2-gigabyte virtual storage
bar.
Use ELEMADDRMODE=64 to indicate that all of the addresses
in message data elements are of 64-bit addressing precision (double
word - 8 bytes) and can reference virtual storage below or above the
2-gigabyte virtual storage bar.
- ,ELEMENT=element
- Use this input parameter to specify the first element of the table
or queue of message data elements. Message data elements contain either
buffers or pointers to buffers that are to receive parts of the message.
Specifying the PARTOFF parameter indicates that each element contains
a buffer. Specifying the PARTPTROFF parameter indicates that each
element contains a pointer to a buffer.
Elements must all
reside in the same space, either an address space or a data space.
Elements can be in the caller's primary address space, addressable
through a public entry on the DU-AL, or in a common area data space.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of the first element.
- ,ELEMFORM=TABLE
- ,ELEMFORM=QUEUE
- Use ELEMFORM=TABLE to indicate that the message data elements
are organized as a table.
Use ELEMFORM=QUEUE to indicate that
the message data elements are organized as a queue.
- ,ENDOFQUEUE=ZERO
- ,ENDOFQUEUE=endofqueue
- Use this input parameter to specify the address that marks the
end of the queue. When the pointer to the next element contains this
address, queue processing ends. You can use either ENDOFQUEUE or #MSGPARTS
to limit the amount of message data elements that are processed.
A partial delivery occurs if the number of message data elements is
insufficient to contain all the data. To receive more of the data,
continue to reissue IXCMSGIX until all data has been delivered.
Note: The
queue must have at least one element.
If you omit ENDOFQUEUE,
the default value for the end-of-queue address is 0 (you can code
this explicitly by specifying ENDOFQUEUE=ZERO).
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
containing the end-of-queue address.
- ,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.
- ,MOVECURSOR=YES
- ,MOVECURSOR=NO
- Use this optional parameter to indicate whether the read position
within the message data to be delivered should be advanced or not.
- ,MOVECURSOR=YES
- MOVECURSOR=YES indicates that you want the read position within
the message data being delivered advanced as data is returned to the
caller. When the read position reaches the end of the data to be returned,
XCF considers the message delivered, and the message token is invalidated.
- ,MOVECURSOR=NO
- MOVERCURSOR=NO indicates that you do not want the position within
the data to be delivered advanced as data is returned to the caller.
All data returned on a call specifying MOVECURSOR(NO) is eligible
for re-delivery on a subsequent IXCMSGIX Message-In service call within
the context of the message exit or notify exit or for a message saved
using the IXCMSGC message control service. XCF will return data starting
from the last established read position. The IXCMSGIX message-in
service will not invalidate a message token on a call specifying MOVECURSOR(NO)
even if all message data is returned.
- ,MSGBUF=msgbuf
- Use this output parameter to specify the buffer to receive the
incoming message. The size of the buffer must be greater than or equal
to the value of MEPLMLEN in IXCYMEPL (if processing in a message user
routine) or MNPLTRRESPMLEN in IXCYMNPL (if processing in a message
notify user routine). The storage key of the buffer specified by MSGBUF
must match the storage key specified with the MSGSTGKEY parameter.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a storage area to receive the message.
- MSGTOKEN=msgtoken
- Use the TOKEN keyword instead of the MSGTOKEN keyword. MSGTOKEN
is not supported for IXCMSGIX requests invoked from a message notify
user routine. MSGTOKEN is provided for compatibility with:
- Message user routines that are running on systems with releases
prior to OS/390® Release 3.
- Older applications that have been assembled with pre-OS/390 Release
2 code but that are running on an OS/390 Release
3 or later system.
Otherwise, use this input parameter to specify the message
token that your message user routine received from XCF in the MEPLMTOK
field of the MEPL (mapped by IXCYMEPL).
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a 32-bit
field that contains the message token.
- ,MSGSTGKEY=JOINKEY
- ,MSGSTGKEY=msgstgkey
- Use this input parameter to specify the storage key to be used
by XCF when storing the message into each receiving buffer. The storage
key of each receiving buffer must match the storage key specified
by MSGSTGKEY.
If you omit the MSGSTGKEY parameter, or if you specify
MSGSTGKEY=JOINKEY, XCF uses as the storage key the value of the PSW
key at the time you joined the XCF group (when IXCJOIN was issued).
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of an 8-bit field formatted as kkkkxxxx, where the
high-order four bits contain the storage key. The low-order four bits
are ignored.
- ,MULTIPART=NO
- ,MULTIPART=YES
- Use MULTIPART=NO to indicate that the message is to be received
into a single buffer.
Use MULTIPART=YES to indicate that the message
is to be received into one or more buffers.
- ,NEXTOFF=nextoff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element to obtain the address
of the next element. This value equals the size in bytes of an individual
message data element. It is used when the message data elements are
in table form.
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of a fullword containing the number
of bytes to be added.
- ,NEXTPTROFF=nextptroff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element, to locate within the
current element either a 31- or 64-bit precision pointer to the next
element. This value is used when the message data elements are in
queue form.
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of a fullword containing the number
of bytes.
- ,PARTALET=ZERO
- ,PARTALET=partalet
- Use this input parameter to specify a single ALET to be used to
qualify every buffer address. The ALET must be zero, a public entry
on your dispatchable unit access list (DU-AL), or an entry for a common
area data space.
If you omit PARTALET, PARTALETOFF, and PARTALETTBL,
the default is PARTALET with an ALET of 0 (if you would like to code
this explicitly, specify PARTALET=ZERO).
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
containing the ALET.
- ,PARTALETOFF=partaletoff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element, to locate within the
element the fullword field that contains the ALET to be used to qualify
the buffer address associated with that element. The ALET must be
zero, a public entry on your dispatchable unit access list (DU-AL),
or an entry for a common area data space.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
containing the number of bytes.
- ,PARTALETTBL=partalettbl
- Use this input parameter to specify a table in which each entry
is a fullword containing the ALET to qualify a buffer address in the
table or queue of message data elements. For instance, the 3rd entry
in PARTALETTBL must contain the ALET to qualify the buffer address
in the 3rd message data element. partalettbl must
begin on a fullword boundary. Each ALET must be zero,a public entry
on your dispatchable unit access list (DU-AL), or an entry for a common
area data space.
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of partalettbl.
- ,PARTLEN=partlen
- Use this input parameter to specify the length in bytes of each
buffer when all the buffers are the same length. All buffers must
be at least as long as PARTLEN.
To receive the entire message
in a message user routine, the total amount of storage for the message
(the value of PARTLEN multiplied by the number of elements) must be
greater than or equal to MEPLMLEN. For a message notify user routine
to receive the entire response, the total amount of storage must be
greater than or equal to MNPLTRRESPMLEN.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
containing the length in bytes of each buffer.
- ,PARTLENOFF=partlenoff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element, to locate within the
element the fullword field that contains the length in bytes of the
buffer associated with that element.
The value of the field indicated
by PARTLENOFF should contain a value at least as long (but may be
less than or equal to the length of the buffer) as the part of the
message you want to put in this buffer. If you specify a length of
zero for the message part, XCF does not use that buffer.
To
receive the entire message, the total amount of storage for the message
(the sum of the buffer lengths) must be greater than or equal to MEPLMLEN.
For a message notify user routine to receive an entire response, the
total amount of storage must be greater than or equal to MNPLTRRESPMLEN.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of a fullword containing the number of bytes.
- ,PARTLENTBL=partlentbl
- Use this input parameter to specify a table in which each entry
is a fullword containing the length of a corresponding buffer. For
instance, the 3rd entry in PARTLENTBL contains the length of the buffer
whose address is associated with the 3rd message data element in the
table or queue. If you specify the length of a buffer as zero, XCF
does not use that buffer.
The table specified by PARTLENTBL must
begin on a fullword boundary.
To receive the entire message,
the total amount of storage for the message (the sum of the buffer
lengths) must be greater than or equal to MEPLMLEN. For a message
notify user routine to receive the entire response, to total amount
of storage must be greater than or equal to MNPLTRRESPMLEN.
To
Code: Specify the RS-type name or address (using a register from
2 to 12) of partlentbl.
- ,PARTOFF=partoff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element, to obtain the address
within the element of the start of the buffer associated with it.
To Code: Specify the RS-type name or address (using a register
from 2 to 12) of a fullword containing the number of bytes.
- ,PARTPTROFF=partptroff
- Use this input parameter to specify the number of bytes to be
added to the address of the current element, to locate within the
element either a 31- or 64-bit precision pointer to the buffer associated
with it.
To Code: Specify the RS-type name or address (using
a register from 2 to 12) of a fullword containing the number of bytes.
- ,PLISTVER=IMPLIED_VERSION
- ,PLISTVER=MAX
- ,PLISTVER=plistver
- Use this input parameter to specify the version of the macro.
See Understanding IXCMSGIX Version Support for a description of the
options available with PLISTVER.
- ,RETCODE=retcode
- Use this output parameter to specify the location in which the
system is to copy the return code from GPR 15.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
to contain the return code.
- ,RSNCODE=rsncode
- Use this output parameter to specify the location in which the
system is to copy the reason code from GPR 0.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
to contain the reason code.
- ,STARTOFFSET=0
- ,STARTOFFSET=startoffset
- Use this optional input parameter to indicate the offset into
the message data from the current read position from which to begin
returning data. The value must not exceed the amount of available
user message data to be returned. The default is 0.
To Code: Specify
the RS-type name or address (using a register from 2 to 12) of a fullword
containing the ALET.
- TOKEN=token
- Use this input parameter to specify the location of the 16-character
field that contains a token that identifies the message whose message
data is to be delivered.
The token identifies one of the following:
- A message presented to a message user routine. On entry to the
routine, R1 contains the address of the message exit parameter list
(MEPL) that contains the token (MEPLMSGITOKEN).
- A response message presented to a message notify user routine.
On entry to the routine, R1 contains the address of the message notification
parameter list (MNPL) that contains the token (MNPLTRMSGITOKEN).
To Code: Specify the RS-type name or address
(using a register from 2 to 12) of the 16-character field containing
the token.
- ,#MSGPARTS=AS_NEEDED
- ,#MSGPARTS=msgparts
- Use this input parameter to specify the number of buffers (1 or
more) to be used to receive the message. The number of buffers specified
determines whether an entire message is received or only part of the
data. You can use #MSGPARTS to limit the amount of message data you
receive. To receive some but not all of the message or response, specify
#MSGPARTS to be less than the number of buffers that would be needed
to receive all the data. To receive an entire message or response,
you can omit the #MSGPARTS parameter, specify #MSGPARTS=AS_NEEDED,
or specify a number of buffers that is sufficient to contain all the
data.
To Code: Specify the RS-type name or address (using
a register from 2 to 12) of a fullword containing the number of buffers.
|
z/OS MVS Programming: Sysplex Services Reference
Copyright IBM Corporation 1990, 2014