|
Purpose Use
this macroinstruction to allow an application to return one or more
buffers to a storage pool. It is also used to logically return a buffer
that has been assigned to multiple owners. The buffer is returned
to CSM when the owner of the last buffer image returns it to CSM and
a buffer return exit routine was not specified during the initial
allocation of the buffer.
Usage An application can specify the address
of a buffer return exit routine that is to receive control when the
IVTCSM REQUEST=FREE_BUFFER macroinstruction is issued. See Buffer return exit routine for more information. An application
might optionally specify that the buffer return exit address specified
when the buffer was obtained is to be overridden, allowing a buffer
to be freed back to CSM that was obtained specifying a free routine
address. This option is requested by specifying FREETO=CSM; it must
be invoked in this manner only by the requester of the buffer that
specified a free routine on the GET_BUFFER request. If others use
this option, the buffer is not returned to the original owner of the
buffer.
The application can optionally specify that the buffer
obtained is to be cleared when it is returned to the pool on a FREE_BUFFER
request. This allows secure data to be cleared after use.
All
IVTCSM REQUEST=GET_BUFFER|ASSIGN_BUFFER macroinstructions must have
a corresponding FREE_BUFFER request before the buffer is considered
available for reallocation by CSM, or before a buffer return exit
routine is invoked for a buffer obtained specifying a buffer return
exit routine. This is necessary to ensure that all users have finished
using the buffer.
Syntax
main diagram
>>-+------+--IVTCSM REQUEST--=--FREE_BUFFER--| 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
>>-,--BUFLIST--=--buflist--,--BUFNUM--=--bufnum----------------->
.-,--CLEAR--=--NO--.
>--+------------------+--+--------------------------+----------->
'-,--CLEAR--=--YES-' '-,--ERRBFLST--=--errbflst-'
.-,--FREETO--=--USER-.
>--+--------------------+--+----------------+------------------->
'-,--FREETO--=--CSM--' '-,--GAP--=--gap-'
.-,--SKIPBUF--=--NO--.
>--+--------------------+--+----------------------+------------->
'-,--SKIPBUF--=--YES-' '-,--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 specified by BUFNUM.
An entry in the list is mapped by IVTBUFL.
The following fields
in IVTBUFL are required as input for this request: - BUFL_VERSION
- BUFL_SOURCE (Required only when SKIPBUF=YES is specified.)
- BUFL_TOKEN
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.
- ,BUFNUM=bufnum
- A required input parameter, specifying the number of buffer entries
in the list.
To code, specify the RS-type address, or address
in register (2)-(12), of a fullword field.
- ,CLEAR=
- An optional parameter, specifying whether the buffer is to be
cleared when returned to storage pool. The default is CLEAR=NO.
- ,CLEAR=NO
- Specifies that the buffer is not cleared when returned to the
storage pool. If the buffer was originally allocated with a CLEAR
value of YES, then CLEAR=NO is ignored by CSM, and the buffer is cleared
when returned to the storage pool.
- ,CLEAR=YES
- Specifies that the buffer is to be cleared. Specifying CLEAR=YES
does not cause a buffer to be cleared that is returned by a user-specified
free routine. However, if CLEAR=YES is specified, the buffer is cleared
in the event that it is returned to the storage pool.
- ,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.
- ,FREETO=
- An optional parameter, allowing the FREERTN parameter on the IVTCSM
REQUEST=GET_BUFFER macroinstruction to be overridden. The default
is FREETO=USER.
- ,FREETO=USER
- Specifies that the buffer is to be returned to the free routine
specified on the GET_BUFFER request.
- ,FREETO=CSM
- Specifies that the free routine address provided when the buffer
was obtained is to be overridden and the buffer is to be returned
to the storage pool. This option should be used only by the original
owner of the buffer.
- ,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 not 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.
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 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.
Use MF=M 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.
- ,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 value 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, IBM® recommends
that you 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 value 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).
- ,SKIPBUF=
- An optional parameter, specifying whether all entries in the buffer
list should be processed. The default is SKIPBUF=NO.
- ,SKIPBUF=NO
- Specifies that all the entries in the buffer list are processed.
No entries are skipped. The BUFL_SOURCE value is not examined.
- ,SKIPBUF=YES
- Specifies that the only entries in the buffer list that have a
BUFL_SOURCE value indicating the user's non-CSM storage (BUFL_UDSPACE
or BUFL_USTOR) are skipped.
- ,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
- Pool 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.
- 8
- System error while processing the request.
- Reason code
- Meaning
- 1
- Unable to obtain storage for request.
- 6
- An abend occurred while processing this request.
|