DMSCOMM - Commit
Context
Coordinated Resource Recovery: SFS
Call Format
The format for calling a CSL routine is language dependent. DMSCOMM is called only through DMSCSL. The routine name is the first parameter in DMSCSL’s parameter list:
- DMSCOMM
- (input, CHAR, 8) can be passed as a literal or in a variable.
DMSCOMM
must be padded with blanks to eight characters.
For more information and examples of the call formats, see Calling VMLIB CSL Routines.
Purpose
Use the DMSCOMM routine to commit (keep) the changes made to the protected resources on a work unit.
DMSCOMM notifies CMS and the resource managers that your application has reached an internal point of consistency and that all protected resources should have their updates made permanent and available to other users of the resources. All changes to protected resources (SFS and non-SFS) are committed when this routine is called. The Coordinated Resource Recovery (CRR) facility provided by CMS makes it possible to commit multiple protected resources. For more information on CRR, see the z/VM: CMS Application Development Guide.
Changes made to BFS files are not protected. That is, they do not participate in CRR and are committed independently of other resources, including SFS, on the work unit.
Parameters
- retcode
- (output, INT, 4) is a variable for the return code from DMSCOMM.
- reascode
- (output, INT, 4) is a variable for the reason code from DMSCOMM.
- workunitid
- (input, INT, 4) is a variable for specifying the work unit associated with the DMSCOMM routine. If you want to specify an optional parameter following the workunitid parameter without specifying what work unit to commit, specify a value of 0 for the workunitid parameter. When you do this, the current default work unit is committed.
- wuerror
- (output, CHAR, length) is a variable used to specify an area for returning extended error information for the file pools involved in the commit. If it is specified, it must be followed by a length field. See wuerror under Common Parameters for more information.
- length
- (input, INT, 4) is a variable containing the length of the preceding character parameter (wuerror). Specifying 0 has the same effect as omitting the wuerror parameter. To use the wuerror parameter, specify a length of 12 plus 136 bytes for each group of extended error information that may be passed back. Specifying a nonzero length less than 12 is incorrect and causes an error reason code to be returned.
Usage Notes
- If DMSCOMM is called and there is a return code of 8, the status of all resources involved remains the same as it was before the commit was issued, so the application can either reissue DMSCOMM or issue DMSROLLB to roll back the work unit. This is also true if the COMMIT parameter is specified on a different CSL routine.
- If your application uses high-level language statements or OS simulation in an assembler program to update data controlled by a resource that participates in CRR, be sure to empty the buffers (for example, close the files) before trying to commit. This may be required because some high-level languages and assembler programs use OS/MVS queued sequential access method (QSAM) for output files. For example, if a program uses OS/MVS QSAM with blocked records for an SFS output file, some of the most recently written output records may not be committed if the program tries to commit without first closing the QSAM file. These records will subsequently be committed when the program closes the file and either commits the work unit or allows end-of-command processing to commit the work unit. Using only CSL routines, FS macros, or the EXECIO command to write to SFS files avoids this situation.
- If a file or directory is open for a work unit and DMSCOMM is issued, the file remains open and
all changes are committed (see Usage Note 2 for exceptions).
Current read and write pointers are not changed. There are, however, some situations that can
prevent a commit:
- Files that have been modified using the DMSWRBLK (Write Blocks) routine remain open on the work unit.
- Catalogs (opened by the DMSOPCAT (Open Catalog) routine) remain open.
- When working with a file with the INPLACE attribute, DMSCOMM makes some file updates available to concurrent readers. See DMSOPEN - Open for more information.
- DMSCOMM commits all protected resources. If your application accesses other resources that do
not participate in CRR, it must commit those resources using the commit interface of those
resources.
Changes made to BFS files are not protected. That is, they do not participate in CRR and are committed independently of other resources, including SFS, on the work unit.
- The setting of the synchronization point options dictates whether CMS will wait for CRR resynchronization to complete before returning to the application. See DMSSSPTO - Set Synchronization Point Options for more information.
- Certain errors can cause the work unit to be rolled back. See the description in the
Reason Codes
table that follows for these errors. - You can use DMSGETSP - Get Synchronization Point Errors to get more detailed information about errors or warnings that occurred during the commit. If you are using a protected conversation, error data may be created even for return code 0. To get this error information, use DMSPCAER - Protected Conversation Adapter Errors.
- DMSCOMM’s error reason codes can also be returned by other SFS-related CSL routines
when they complete their operation successfully but cannot commit the work unit. In this case, the
reason code is 50500, and if the wuerror parameter was used when the
routine was called, one of DMSCOMM’s reason codes is returned in the
error_reascode_info field of one of the FPERROR entries (see DMSWUERR - Work Unit Error Data Deblocker) for more information.
In addition to the reason codes for DMSCOMM, the error_reascode_info field can contain 50500, to indicate that the user has exceeded his file space.
Return Codes and Reason Codes
For lists of the possible return codes from DMSCOMM, see Return Codes.
The following table lists the special reason codes returned by DMSCOMM.
WARNING means the request was processed and there were some exceptional conditions, or the desired state already exists. ERROR indicates that the request failed. SEVERE ERROR means that the state of different resources may be inconsistent. Warnings cause return code 4, errors cause return code 8 or 12, and severe errors cause return code 16 or 20.
DMSCOMM can also return the common CSL reason codes, which are codes that can occur with most file system management and related routines. For a list of the common reason codes, see Common Reason Codes.
Severity | Reason Code | Description |
---|---|---|
WARNING | 51060 | The user reached or exceeded the SFS file space threshold for one or more file spaces. |
WARNING | 76070 | Changes to non-recoverable files have been lost. This code appears only as part of the work unit error information that is provided when you specify the wuerror parameter, or when you request SFS error data using the DMSGETSP (Get Synchronization Point Errors) or DMSGETER (Get My Errors) CSL routines. |
WARNING | 81054 | Resynchronization is in progress on one or more protected resources and their consistency state is unknown. In other words, if the resynchronization is successful, all protected resources will be committed and if it is not successful, changes to all protected resources will be rolled back. |
WARNING | 81055 | All protected resources have been committed. However, the availability of a resource has changed. For example, an open file may have been closed. |
ERROR | 35000 | The work unit was rolled back. System limits were exceeded when attempting to commit. CMS cannot commit more than approximately 230 resources on a work unit. |
ERROR | 54500 | The CRR recovery server log limits were exceeded. The work unit was rolled back. |
ERROR | 79058 | A synchronization point is already in progress for the work unit. This request was ignored. |
ERROR | 79061 | A resource is not in a state that can be committed. This request was ignored,
the work unit was not rolled back or committed, and all protected resources were left in the same
state they were prior to the call to DMSCOMM. Reasons this could occur in a protected conversation
include:
|
ERROR | 81053 | The work unit was rolled back; all protected resources have been restored to their prior mutually consistent state. A resource manager (such as SFS) or a conversation partner detected a problem and initiated a rollback. |
ERROR | 81054 | The COMMIT operation failed. A resynchronization operation is in progress to finish rolling back one or more protected resources. Their consistency state is unknown. If the resynchronization is successful, all resources will be rolled back. |
ERROR | 81056 | The CRR recovery server is not available. The work unit was rolled back; all protected resources have been restored to their prior mutually consistent state. |
ERROR | 81059 | The work unit was rolled back due to an application error: Two or more protected conversation partners initiated a commit at the same time. |
ERROR | 90415 | Invalid length specified for the wuerror parameter. A nonzero length must be at least 12 bytes. |
ERROR | 90540 | Invalid work unit ID. The work unit was not rolled back or committed. All protected resources are in the same state they were prior to the call to DMSCOMM. |
ERROR | 95600 | The work unit was not committed. This could occur because an open file was modified with Write Blocks or a file in the directory is open and the file pool server does not have the Commit Without Close enhancement. This is an SFS-specific reason code. |
ERROR | 96100 | Insufficient virtual storage. The work unit was not rolled back or committed. All protected resources are in the same state they were prior to the call to DMSCOMM. This request was ignored. |
SEVERE ERROR | 81051 | A protocol violation may have provoked an inconsistent state among the
resources.
|
SEVERE ERROR | 81052 | Resource manager or operator intervention resulted in an inconsistent state
among the resources.
|