DMS error codes

Error codes contain information about errors affecting programs or jobs, enabling the user to determine the type and origin of the error and the appropriate remedial action. The error codes used in DMS offer the following advantages:

• the abbreviated format permits many different error conditions to be encoded

• the type of encoding permits identification of the component which was the source of the error

• in the case of recoverable errors, the program can implement appropriate analysis measures and thus avoid abnormal termination.

DMS errors in program execution

In the following management macro calls, the error code is (with subcodes) placed in the standard header:

• CATAL with VERSION=3

• COMPFIL

• COPFILE

• DECFILE

• DROPTFT

• ENCFILE

• ERASE with VERSION=3

• FILE with VERSION=3

• FSTAT with VERSION=3/4

• LFFSNAP

• LJFSNAP

• MAILFIL

• RDTFT with VERSION=3

• RELTFT

• RFFSNAP

• RJFSNAP

In the following management macro calls, the error code is (without subcodes) placed in the two low-order bytes of register 15:

• CATAL with VERSION<3

• CHNGE

• COPY

• ERASE with VERSION<3

• FILE with VERSION<3

• FSTAT with VERSION<3

• IMPORT

• RDTFT without VERSION and with VERSION=2

• REL

For data management macros (service macros and access methods), error codes are placed in field ID1ECB of the TU FCB (displacement X'98').

If a DMS error occurs during program execution, an error code is placed in the file control block. If the program does not contain a routine for handling such errors, the program is terminated with an error message on SYSOUT in interactive mode or on SYSLST in batch mode.

Coding methods

w x y z

The error code is a four-digit hexadecimal whose second digit identifies the component that noted the error. The digits w, y and z indicate the error which has occurred.

Error code value table for the components:

x	Component
2	Privileged PAM (PPAM)
3	Catalog administrator (CMS)
4	Data storage administrator (ALLOC)
5 and 6	DMS commands / Assembler macros
7	Privileged tape access method (PTAM)
9	UPAM
A	ISAM
B	SAM
C	BTAM
D	OPEN
E	CLOSE

When components are in the sequence 2₁₆-E₁₆ this means that a component with a higher number can call a component with a lower number and not vice versa).

If an error occurs in a called component, the error code is passed to the calling component (and modified in the process).

Example for the generation and modification of error codes

• single-stage (error in the calling component): a user calls UPAM and the file is not open: UPAM places error code 0994 in the FCB and branches via $GOTO to USERERR.

• two-stage (error in the called component): a user calls UPAM, which in turn calls PPAM. PPAM detects an I/O error: in this case, PPAM passes error code 0227 to UPAM in register 15. UPAM modifies this error code to 0927, places it in the FCB, and branches via $GOTO to ERRADR.  

List of DMS error codes

IDEMS macro

The explanations of the error codes are given below in list form. This list can be output, either completely or partially, with the aid of the IDEMS macro.

Operation	Operands	Comments
IDEMS	[ALL=Y]	All error codes are generated
	[,PAM=Y]	Only PPAM codes
	[,CATAL=Y]	Only CMS codes
	[,ALLOC=Y]	Only ALLOC codes
	[,CMDMAC=Y]	Only codes for DMS commands/macros, part 1
	[,CMDNMAC=Y]	Only codes for DMS commands/macros, part 2
	[,NPAM=Y]	Only UPAM codes
	[,ISAM=Y]	Only ISAM codes
	[,SAM=Y]	Only SAM codes
	[,BTAM=Y]	Only BTAM codes
	[,OPEN=Y]	Only codes for OPEN processing
	[,CLOSE=Y]	Only codes for CLOSE processing
	[,P=letter]	Prefix for the symbolic names of the DMS messages; Default value: I “P=” generates no prefix letter.

System message prefix

When system messages are output, the error code is prefixed by the message class “DMS” (0D33 -> DMS0D33). The command or standard statement HELP-MSG-INFORMATION enables a message text and further information on the cause of the error and how it is dealt with to be output in English or German.

Exceptions

• ISAM: the error code for ISAM is always 0AAz (where 0 <= z <= F), even for the system messages.

  Example 
  If PPAM detects an error after an ISAM call, error code '0AA9' is always placed in the FCB. The entry in the IDEMS list for this code is “SYSTEM ERROR, HARDWARE”. ISAM issues this message for all errors detected in PPAM.

• OPEN: when ISAM files are opened, errors which cannot be analyzed via the error code may occur.
  Example
  When an ISAM file is opened in INPUT mode, the “first PAM page” is read. this page always contains the control block (NK-ISAM) or the highest-level index block (K-ISAM). 
  After an I/O error, the following occurs:
  

  Figure 11: Error sequence after an input/output error

  
  

  Note 
  This error has a diffesrent meaning in the IDEMS macro, but stands for an I/O error here.

• CLOSE: in order to complete all outstanding I/O operations, the CLOSE routine calls the access method for the file.

Error analysis aids

The following aids are available for analyzing error codes:

• Look for the meaning in the IDEMS list.

• If file management macros are used in the program, check the error code (in the standard header or in register 15). If the error code≠0, the program should be terminated or the contents of the error code should be thoroughly analyzed.