DMSGETER - CRR Get My Errors
Context
Coordinated Resource Recovery (CRR) Participation
Call Format
The format for calling a CSL routine is language dependent. DMSGETER is called only through DMSCSL. The routine name is the first parameter in DMSCSL’s parameter list:
- DMSGETER
- (input, CHAR, 8) can be passed as a literal or in a variable.
For more information and examples of the call formats, see Calling VMLIB CSL Routines.
Purpose
Use the DMSGETER routine to retrieve, one at a time, error blocks for warnings and errors that a resource adapter has detected since the start of the last commit or backout for the work unit.
Parameters
- retcode
- (output, INT, 4) is a variable for the return code from DMSGETER.
- reascode
- (output, INT, 4) is a variable for the reason code from DMSGETER.
- error_data_buffer
- (output, CHAR, length1) is a variable for the retrieved error block data.
- length1
- (input, INT, 4) is a variable for specifying the length (in bytes) of the error_data_buffer variable. The length1 variable defines the maximum amount of data that can be moved. Only the portion of the error block data that fits will be moved into the buffer.
- actual_error_data_length
- (output, INT, 4) is a variable for the actual length of the error data passed back by the resource adapter's exit routine. This field is not set unless the return code from DMSGETER is 0 or 4.
- error_block_counter
- (input/output, INT, 4) is a variable for an incremental value that permits the adapter to
retrieve all pertinent error blocks by calling DMSGETER repeatedly. The input value on the first
call must be 0.
As output (when data is passed back), the value of this parameter identifies the last error block processed. Subsequent calls must return the value unchanged. The value is valid until the next sync point.
- workunitid
- (input, INT, 4) is a variable for the ID of the work unit for which an error block is desired. If the work unit ID is 0 or not specified, the current CMS default work unit is assumed.
- exit_name
- (input, CHAR, 0–8) is a variable for the name of the resource adapter's exit routine, as
specified in the registration (DMSREG) routine.
Only the portion of the name specified in this parameter is used to locate a match in the registry.
- length2
- (input, INT, 4) is a variable for specifying the length of the
exit_name variable.
If the exit_name parameter has been set to 0 (null), the length2 parameter must also be 0. Specifying 0 has the same effect as omitting the exit_name parameter.
- resource_component_id
- (input, CHAR, 9) is a variable for the component identification for the resource whose error blocks are being retrieved. If used as a search argument, this ID must match the ID specified in the registration (DMSREG) routine. A blank in the first byte means this parameter is not to be used as a search argument.
- adapter_token
- (output, CHAR, 4) is a variable that identifies the resource associated with the error block. This value was supplied by the resource adapter in the registration (DMSREG) routine.
Usage Notes
- For guidance information on using the DMSGETER routine in the context of getting a resource manager to participate in CRR, see z/VM: CMS Application Development Guide.
- DMSGETER should be called repeatedly to retrieve all error blocks until the routine returns a return code of 4 and a reason code of 44040 (all data returned).
- Getting an error block is nondestructive. Two programs (such as the application and the resource adapter) could get the errors for the same work unit, component, and exit name at the same time but not interfere with each other.
- Combinations of the workunitid parameter, exit_name parameter, and resource_component_id parameter can be used to set search criteria for error blocks. All the specified search arguments must be met before an error block is returned to the caller.
- The adapter_token parameter is intended for use by the resource manager's routine that passes back resource-specific error information, and should enable the resource adapter to identify the resource that had the error. Only the resource adapter keeps resource identification data, not the SPM.
- Error data is preserved until the start of the next synchronization point or until the work unit ends. A call to DMSUNREG to unregister the resource does not delete its error data.
Return Codes and Reason Codes
For lists of the possible return codes from DMSGETER, see Return Codes.
The following table lists the special reason codes returned by DMSGETER. WARNING means the request was processed, but a warning condition was encountered; ERROR means the request failed. Warnings cause return code 4, and errors cause return code 8.
DMSGETER 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 | 44040 | All data has previously been returned. The error data buffer is unchanged. |
WARNING | 90271 | All available information would not fit into the error data buffer. As much data as would fit into the buffer has been placed there. Check the actual_error_data_length parameter to find out the actual length of the data in the error block. To retrieve all the available data, make the buffer equal to the returned length, set the error_block_counter parameter to 0, and call DMSGETER again. |
WARNING | 90278 | No error blocks were found. Either there were no sync point warnings or errors for the work unit, or the participant that received the warnings or errors did not create any error blocks. |
ERROR | 90118 | Invalid error_block_counter parameter. The caller changed the counter, or a sync point occurred since the call to DMSGETER that created the counter. |
ERROR | 90210 | Extraneous characters in input parameter. |
ERROR | 90277 | No matching registered resource was found for the input parameters you specified. |
ERROR | 90300 | Invalid input parameter. |
ERROR | 90485 | Invalid buffer length specified. |
ERROR | 90540 | Invalid workunitid parameter. |