Completion of an unsuccessful send

Certain macroinstruction error completions occur prior to VTAM® actually accepting the CSM storage or the send request. For these cases, the CSM storage is still considered owned by the application. VTAM does not invoke CSM to return the buffers. The application's buffer return exit routine, if specified, is not scheduled. The application is responsible for the eventual return of the storage to CSM using the IVTCSM REQUEST=FREE_BUFFER macroinstruction.

If VTAM indicates that it has accepted any of the CSM storage, that CSM storage is considered owned by VTAM. In this case, the handling of the CSM storage is the same as the case where the send is successful. VTAM eventually invokes CSM to return the buffers. The application's buffer return exit routine, if specified, is scheduled.

VTAM indicates whether it has accepted a CSM buffer so that the application can determine whether it is responsible for freeing the buffer. The application is responsible for checking these indicators. This indication is provided by two different methods, depending on the nature of the failure:

If the error is in the category where only a register return code is provided to the application, the application is responsible for returning the CSM buffers. Typically, this type of error is returned when an RPL is not considered valid for setting status. For example, VTAM may find the RPL to already be in use.
These errors, with accompanying return codes, are:
- Logic error due to not valid RPL
  - General Return Code=4
  - Recovery Action Return Code=X'18'
- Logic error due to not valid RPL extension
  - General Return Code=4
  - Recovery Action Return Code=X'1C'
- Logic error due to RPL in wrong state
  - General Return Code=4
  - Recovery Action Return Code=X'20'
For more information on these errors, see Handling errors.
If an RPL is available to VTAM, VTAM sets the RPLXSRV flag if all of the buffers are accepted from the application. If this flag is not set, it is possible that some of the buffers have been accepted and further analysis of each buffer list entry is required.

Each buffer list entry contains a flag, BLXEN_OWNACC, which indicates whether the buffer in the list has been accepted by VTAM. If the buffer is not accepted, it is possible that VTAM has accepted part of the data. A count field in each list entry, BLXEN_RLENA, can be used by the application to determine whether the buffer in the list has been partially or completely accepted, or completely unaccepted. VTAM sets the count field as data is accepted. The application is responsible for ensuring that the initial value of the count field is 0. If the count field is equal to the application-supplied length field, VTAM has accepted all of the data. If the two fields are not equal, the application is responsible for freeing the CSM storage. The value for BLXEN_RLENA, when added to the start of the storage area, provides the address of the data area that the application can validly access. Any data prior to the address could be in use in a channel program and should not be accessed.

The following list describes the application's responsibilities for freeing storage depending on how much data in the buffer list entry is accepted.

None of the data in the buffer list entry is accepted (BLXEN_OWNACC = B'0' & BLXEN_RLENA = 0)
The application is responsible for freeing the CSM storage. All of the storage is available for reuse.
All of the data in the buffer list entry is accepted (BLXEN_OWNACC = B'1')
VTAM is responsible for freeing the CSM storage. None of the storage can be reused by the application until its buffer return exit routine, if specified, is executed.
Part of the data in the buffer list entry is accepted (BLXEN_OWNACC = B'0' & BLXEN_RLEN ¬= BLXEN_RLENA)
The application is responsible for freeing the CSM storage using the original CSM token. VTAM is also responsible for freeing the portion of the CSM storage it has accepted. VTAM represents the accepted storage with the CSM tokens it obtained using IVTCSM REQUEST=ASSIGN_BUFFER. Only the storage not accepted by VTAM can be reused by the application. This reusable storage address is calculated by adding the accepted count, BLXEN_RLENA, to the original storage address. There is no way to reuse the portion of the CSM storage accepted by VTAM without using the IVTCSM REQUEST=FREE_BUFFER macroinstruction. If the application is using a buffer return exit routine, it is not scheduled until all CSM tokens associated with the storage are freed, including the original token, using the IVTCSM REQUEST=FREE_BUFFER macroinstruction. If a CSM buffer is partially accepted by VTAM and partially owned by the application, there are at least two CSM tokens associated with the CSM storage. Each token must be returned to CSM regardless of which address space is the CSM owner before the buffer return exit routine is scheduled and the entire buffer is available for reuse. If a CSM buffer return exit is not specified, the entire CSM buffer can never be recovered by the application under the original token because issuance of the IVTCSM REQUEST=FREE_BUFFER returns the storage directly to the CSM pool rather than to the application.

Note: In the previous discussion, there are conditions where the storage is considered reusable. This includes alterations of contents only when the sending application is the originator of the storage. All applications except the original requester must treat any CSM storage as read-only. See Application responsibilities for using HPDT for more information.

Storage not accepted by VTAM could potentially be marked eligible to be pagefreed by CSM upon send completion. Eligible to be pagefreed is a status maintained by CSM. The actual system state of a buffer with this status can be either fixed or pageable. The application should examine ISTBLXEN to determine the pageable state of the buffers returned by CSM. If the BLXEN_PAGEELIG flag is set on, then the storage is marked as eligible to be pagefreed by CSM. The application is responsible for fixing the buffers (IVTCSM REQUEST=FIX_BUFFER macroinstruction) if subsequent use of the storage requires fixed buffers.