 |
Purpose Use this macroinstruction to copy data to or from
a CSM buffer or a user data area.
Usage This macroinstruction assists the
application by isolating it from possible storage key differences
between that of the requester and that of the CSM buffer. It also
assists users of CSM data space buffers by isolating the requester
from the addressing method used to access a data space.
This
macroinstruction allows multiple source buffers to be copied to or
from one or multiple target buffers. The source buffers are copied
to the target buffers using the source and target buffer lengths to
pack data or span data across the target buffers as required.
If
the cumulative length of the source buffers is greater than the cumulative
length of the target buffers, the source data is truncated. The application
can specify a character on the PADCHAR input parameter to pad the
target buffers when the cumulative length of the source buffers is
less than the cumulative length of the target buffers.
CSM
accepts a source buffer list and a target buffer list as input. This
is the same buffer list that is mapped by the IVTBUFL DSECT that is
described on page CSM buffer list entry (IVTBUFL). The number of entries in each
list are not required to be equal. Within each list, entries might
or might not represent a CSM buffer. The BUFL_SOURCE field in the
entry indicates whether the entry represents a CSM buffer. For entries
representing CSM buffers, the address that is the source or target
of the copy is supplied by the requester and is not required to be
the actual start address of the CSM buffer. CSM validates that the
specified address and length corresponds to a storage area that is
within the bounds of the CSM buffer. This validation is based on the
size of the buffer as determined at the time the buffer pool was created.
The
application can use the COPY_DATA request to copy data to or from
a non-CSM data space using the ALET provided in the buffer list entry.
The ALET must be valid for the address space for which it is being
used.
Syntax 
main diagram
>>-+------+--IVTCSM REQUEST--=--COPY_DATA--| parameters-1 |----->
'-name-'
>--+------------------------+--+------------------------+------->
'-,--RETCODE--=--retcode-' '-,--RSNCODE--=--rsncode-'
.-,--PLISTVER--=--IMPLIED_VERSION-.
>--+---------------------------------+-------------------------->
+-,--PLISTVER--=--MAX-------------+
'-,--PLISTVER--=--0---------------'
.-,--MF--=--S--------------------------------------.
>--+--------------------------------------------------+--------><
| .-,--0D---. |
+-,--MF--=--(--L--,--list addr--+---------+--)-----+
| '-,--attr-' |
| .-,--COMPLETE-. |
+-,--MF--=--(--E--,--list addr--+-------------+--)-+
| '-,--NOCHECK--' |
| .-,--COMPLETE-. |
'-,--MF--=--(--M--,--list addr--+-------------+--)-'
'-,--NOCHECK--'
parameters-1
.-,--PAD--=--NO--------------------------.
>>-+----------------------------------------+------------------->
'-,--PAD--=--YES--,--PADCHAR--=--padchar-'
>--+------------------------+--+----------------------+--------->
'-,--SRCERRL--=--srcerrl-' '-,--SRCGAP--=--srcgap-'
>--,--SRCLIST--=--srclist--,--SRCNUM--=--srcnum----------------->
>--+--------------------------+--+------------------------+----->
'-,--TARGERRL--=--targerrl-' '-,--TARGGAP--=--targgap-'
>--,--TARGLIST--=--targlist--,--TARGNUM--=--targnum------------->
>--+----------------------+--+------------------------+--------><
'-,--THREAD--=--thread-' '-,--UTILRTN--=--utilrtn-'
Parameters - name
- An optional symbol, starting in column 1, that is the name on
the IVTCSM macro invocation. The name must conform to the rules for
an ordinary assembler language symbol.
- ,MF=
- An optional input parameter that specifies the macro form.
- MF=S
- Specifies the standard form of the macro, which builds an inline
parameter list and generates the macro invocation to transfer control
to the service. MF=S is the default.
- MF=L
- Specifies 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.
- MF=E
- Specifies 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 of the macro stores the parameters
into the storage area defined by the list form, and generates the
macro invocation to transfer control to the service.
- MF=M
- Use together with the list and execute forms of the macro for
service routines that need to provide different options according
to user-provided input. Use the list form to define a storage area;
use the modify form to set the appropriate options; then use the execute
form to call the service.
- ,list addr
- The name of a storage area to contain the parameters. For MF=S,
MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
- ,attr
- An optional input string 1 - 60 characters in length that you
use to force boundary alignment of the parameter list. Use a value
of 0F to force the parameter list to a word boundary, or 0D to force
the parameter list to a doubleword boundary. If you do not code attr,
the system provides a value of 0D.
- ,COMPLETE
- Specifies that the system is to check for required parameters
and supply defaults for omitted optional parameters.
- ,NOCHECK
- Specifies that the system is not to check for required parameters
and is not to supply defaults for omitted optional parameters.
Guidelines:
Use the modify and execute
forms of IVTCSM in the following order: - Use IVTCSM ...MF=(M,list-addr,COMPLETE) specifying appropriate
parameters, including all required ones.
- Use IVTCSM ...MF=(M,list-addr,NOCHECK), specifying the parameters
that you want to change.
- Use IVTCSM ...MF=(E,list-addr,NOCHECK), to execute the macro.
- ,PAD=
- An optional parameter that indicates if padding is to be performed.
The default is PAD=NO.
- ,PAD=NO
- Indicates that padding is not performed.
- ,PAD=YES
- Indicates that padding is to be performed using the value specified
by PADCHAR.
- ,PADCHAR=padchar
- When PAD=YES is specified, a required input parameter, specifying
the character to use as pad if the cumulative target length is greater
than the cumulative source length. If PAD=YES is not specified, then
no padding is performed.
To code, specify the RS-type address,
or address in register (2)-(12), of a 1-character field.
- ,PLISTVER=
- An optional input parameter that specifies the version of the
macro. PLISTVER determines which parameter list the system generates.
PLISTVER is an optional input parameter on all forms of the macro,
including the list form. When using PLISTVER, specify it on all macro
forms used for a request and with the same value on all of the macro
forms.
The values are:
- IMPLIED_VERSION
- The lowest version that allows all parameters specified on the
request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION
is the default.
- MAX
- Specify when you want the parameter list to be the largest size
currently possible. This size might increase from release to release
and affect the amount of storage that your program needs. If you can
tolerate the size change, you should always specify PLISTVER=MAX on
the list form of the macro. Specifying MAX ensures that the list-form
parameter list is always long enough to hold all the parameters you
might specify on the execute form; in this way, MAX ensures that the
parameter list does not overwrite nearby storage.
- 0
- Specify when you use the currently available parameters.
To code, specify one of the following values: - IMPLIED_VERSION
- MAX
- A decimal value of 0
- ,RETCODE=retcode
- An optional output parameter into which the return code is to
be copied from GPR 15.
To code, specify the RS-type address of
a fullword field, or register (2)-(12).
- ,RSNCODE=rsncode
- An optional output parameter into which the reason code is to
be copied from GPR 0.
To code, specify the RS-type address of
a fullword field, or register (2)-(12).
- ,SRCERRL=srcerrl
- An optional output parameter, specifying the number of the last
buffer entry that was successfully processed in the SRCLIST.
To
code, specify the RS-type address, or address in register (2)-(12),
of a fullword field.
- ,SRCGAP=srcgap
- An optional input parameter, specifying the number of bytes used
to separate buffer entries in SRCLIST. This parameter allows the buffer
entries to be in discontiguous storage. If this parameter is not specified,
buffer entries are in contiguous storage.
To code, specify the
RS-type address, or address in register (2)-(12), of a fullword field.
- ,SRCLIST=srclist
- A required input parameter of an area containing a list of information
about the buffers from which the data is to be copied. Each entry
in the list describes a buffer and is mapped by IVTBUFL. The number
of entries is equal to the number of buffers specified by SRCNUM.
The buffer entry can represent a CSM buffer or a user data area.
The
following fields in IVTBUFL are required as input for this request.
- BUFL_VERSION
- BUFL_SOURCE
- BUFL_TOKEN (Required only if data is being copied from a CSM buffer.)
- BUFL_ALET ( Required only if required to access the data in a
user data space.)
- BUFL_ADDR
- BUFL_SIZE
To code, specify the RS-type address, or address in
register (2)-(12), of a field.
- ,SRCNUM=srcnum
- A required input parameter, specifying the number of source buffers
for the copy.
To code, specify the RS-type address, or address
in register (2)-(12), of a fullword field.
- ,TARGERRL=targerrl
- An optional output parameter, specifying the number of the last
buffer entry that was successfully processed in the TARGLIST. To code,
specify the RS-type address, or address in register (2)-(12), of a
fullword field.
- ,TARGGAP=targgap
- An optional input parameter, specifying the number of bytes used
to separate buffer entries in TARGLIST. This parameter allows the
buffer entries to be in discontiguous storage. If this parameter is
not specified, buffer entries are in contiguous storage.
To code,
specify the RS-type address, or address in register (2)-(12), of a
fullword field.
- ,TARGLIST=targlist
- A required input parameter of an area containing a list of information
about the buffers that are the target of the copy operation. Each
entry in the list is a buffer entry mapped by IVTBUFL. The buffer
entry can represent a CSM buffer or a user data area.
The following
fields in IVTBUFL are required as input for this request. - BUFL_VERSION
- BUFL_SOURCE
- BUFL_TOKEN (Required only if data is being copied into a CSM buffer.)
- BUFL_ALET (Required only if required to copy data into a user
data space.)
- BUFL_ADDR
- BUFL_SIZE
No fields in IVTBUFL are returned as output, by CSM, for this
request. To code, specify the RS-type address, or address
in register (2)-(12), of a field.
- ,TARGNUM=targnum
- A required input parameter, specifying the number of target buffers
for the copy.
To code, specify the RS-type address, or address
in register (2)-(12), of a fullword field.
- ,THREAD=thread
- An optional input parameter, specifying a unique identifier that
is placed in the CSM trace entry to correlate trace records with the
application that is requesting the buffers. It is the CSM user's responsibility
to ensure that this value is different from the THREAD value specified
by other users of the CSM. One way this can be achieved is by specifying
an ECSA control block for THREAD.
To code, specify the RS-type
address, or address in register (2)-(12), of a 4-character field.
- ,UTILRTN=utilrtn
- An optional input parameter that is issued from a utility routine.
Specify the utility routine caller's address to be placed in the CSM
trace entry. If this parameter is omitted, only the address of the
CSM request issuer is placed in the CSM trace entry. This parameter
is relevant only to the tracing process. It should be specified only
if the CSM user requires identification of the caller of a utility
routine in the CSM trace entry.
To code, specify the RS-type address,
or address in register (2)-(12), of a fullword field.
Return codes The following codes can be
returned to the application on this macroinstruction: - Return code
- Meaning
- 0
- Request completed successfully.
- 4
- Request did not complete successfully. See the following reason
codes to determine the type of error encountered.
- Reason code
- Meaning
- 2
- Requested function not supported at the present time, service
has not been initialized.
- 7
- Invalid buffer token specified.
- 8
- Instance ID in the input buffer token does not match that of the
buffer, possible attempt to use a buffer that has been freed.
- 12
- Address and length specified on a copy data request for a source
buffer descriptor is outside the bounds of the CSM buffer represented
by the specified pool token.
- 13
- Address and length specified on a copy data request for a target
buffer descriptor is outside the bounds of the CSM buffer represented
by the specified pool token.
- 14
- Copy operation resulted in truncation of source data due to insufficient
buffer space provided by the target buffer list.
- 18
- BUFL_SOURCE value is not valid for an entry in the Source buffer
list (SRCLIST).
- 19
- BUFL_SOURCE value is not valid for an entry in the Target buffer
list (TRGLIST).
- 20
- BUFTYPE value specified is not valid for this request.
- 21
- BUFSOURC value specified is not valid for this request.
- 22
- Source and target buffers overlap, no data has been copied.
|
z/OS Communications Server: CSM Guide
Copyright IBM Corporation 1990, 2014