DMSCOMM - Commit

Read syntax diagramSkip visual syntax diagram DMSCOMM , retcode , reascode ,workunitid,wuerror,length

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.

Note: Changes to minidisk files cannot be explicitly committed or rolled back. Changes are committed when the last file on the minidisk that is open for output is closed.

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

  1. 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.
  2. 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.
  3. 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.
  4. When working with a file with the INPLACE attribute, DMSCOMM makes some file updates available to concurrent readers. See DMSOPEN - Open for more information.
  5. 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.

  6. 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.
  7. Certain errors can cause the work unit to be rolled back. See the description in the Reason Codes table that follows for these errors.
  8. 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.
  9. 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.

Note: These reason codes can also be returned by other CSL routines. See usage note 9.

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:
  • A protected conversation is not in send, defer, or synchronization point state on a commit function
  • A protected conversation is in send state but did not finish sending a logical record (applies to basic conversation only) on an attempt to commit.
Reasons this could occur with SFS include:
  • A catalog is open (see DMSOPCAT).
  • Committing the work would exceed the user’s file space limit.
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.
RC=16
The COMMIT operation completed. One or more protected resources may have rolled back.
RC=20
The COMMIT operation failed. The work unit was rolled back, but one or more protected resources may have committed.
SEVERE ERROR 81052 Resource manager or operator intervention resulted in an inconsistent state among the resources.
RC=16
The COMMIT operation completed. One or more protected resources have rolled back.
RC=20
The COMMIT operation failed. When trying to roll back changes, one or more protected resources committed.