|
Purpose This
macroinstruction allows an application to request that a buffer be
logically assigned to another owner (shared) in order to make multiple
owners of a buffer.
Usage This macroinstruction allows a buffer
to be concurrently shared between multiple users. A logical instance
of the buffer is created for each user. A new physical copy of the
buffer is not created. This macroinstruction can be used to allow
specific areas of the buffer to be allocated to different owners and
to allow multiple users to have read access to the same data. No serialization
is provided to prevent concurrent updates by users.
The ownership
of the new instance of the buffer is assigned to the requesting application's
ASID by default. Ownership of a new instance of the buffer can be
optionally qualified by specifying a TASKID on the macroinstruction.
The TASKID is a TCB address with the default being no task association.
Upon
completion of this macroinstruction, a new buffer token is returned
representing the new instance of the buffer. The buffer token is
the means by which this new instance of the buffer is known to CSM.
This token must be used with all other requests to CSM for the associated
buffer instance.
Multiple shared instances of a single buffer
can be created by passing a multiple entry buffer list with the same
buffer token in each entry.
Syntax
main diagram
>>-+------+--IVTCSM REQUEST--=--ASSIGN_BUFFER------------------->
'-name-'
>--| parameters-1 |--+------------------------+----------------->
'-,--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
>>-,--BUFLIST--=--buflist--,--BUFNUM--=--bufnum----------------->
.-,--BUFTYPE--=--SAME-----.
>--+-------------------------+--+----------------+-------------->
+-,--BUFTYPE--=--PAGEELIG-+ '-,--GAP--=--gap-'
'-,--BUFTYPE--=--FIXED----'
>--+--------------------------+--+------------------------+----->
'-,--ERRBFLST--=--errbflst-' '-,--OWNERID--=--ownerid-'
>--+----------------------+--+----------------------+----------->
'-,--TASKID--=--taskid-' '-,--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.
- ,BUFLIST=buflist
- A required input parameter of an area containing a list of buffer
entries. The number of entries in the list is provided by BUFNUM.
An entry in the buffer list is mapped by IVTBUFL. Some of the fields
defined in IVTBUFL are required as input and some are set by CSM as
output fields.
Note: The
buffer token representing the new buffer image is returned in the
BUFL_TOKEN field as output.
The following fields in IVTBUFL
are required input for this request.
The following 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.
- ,BUFNUM=bufnum
- A required input parameter, specifying the number of buffers to
be logically assigned.
To code, specify the RS-type address, or
address in register (2)-(12), of a fullword field.
- ,BUFTYPE=
- An optional parameter, specifying whether the buffer images are
guaranteed to be fixed, eligible to be made pageable or have the same
pageable state as the buffers represented by the input token. The
default is BUFTYPE=SAME.
- ,BUFTYPE=SAME
- Indicates that the pageable state of the buffer images is the
same as the buffers represented by the input token.
- ,BUFTYPE=PAGEELIG
- Indicates that the buffer images are eligible to be made pageable.
- ,BUFTYPE=FIXED
- Indicates that buffer images are guaranteed to be fixed.
- ,ERRBFLST=errbflst
- An optional output parameter, specifying the number of the last
buffer entry that was successfully processed when an error is detected
during processing of the macroinstruction.
To code, specify the
RS-type address, or address in register (2)-(12), of a fullword field.
- ,GAP=gap
- An optional input parameter, specifying the number of bytes used
to separate buffer entries. This parameter allows the buffer entries
to be in discontiguous storage. If GAP is not specified, buffer entries
are contiguous.
To code, specify the RS-type address, or address
in register (2)-(12), of a fullword field.
- ,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.
- ,OWNERID=ownerid
- An optional input parameter, specifying the owner to which the
buffer image is to be logically assigned. If not coded, the ASID of
the issuing application is assigned as the OWNERID.
To code, specify
the RS-type address, or address in register (2)-(12), of a halfword
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
- Code this if 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
- Code this if 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).
- ,TASKID=taskid
- An optional input parameter that is to contain the address of
a TCB. This further qualifies the ownership of a buffer to a specific
task. If TASKID is not specified, the buffer is not associated with
a task but is instead associated with the issuing application's ASID.
To code, specify the RS-type address, or address in register (2)-(12),
of a pointer 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. This can be achieved 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
- Buffer token specified is not valid.
- 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.
- 9
- Real storage unavailable to provide a fixed buffer, wait not requested.
- 15
- Assign buffer request failed because the state of the buffer is
guaranteed to be pageable.
- 20
- BUFTYPE value specified is not valid for this request.
- 26
- Assign buffer request failed because CSM reached the maximum number
of image buffers of the single CSM buffer.
- 8
- System error while processing the request. See the following reason
codes to determine the type of error encountered:
- Reason code
- Meaning
- 1
- Unable to obtain storage for request.
- 6
- An abend occurred while processing this request.
|