IBM Tivoli NetView for z/OS, Version 6.2

Composite return codes

Most of the NetView® commands, command lists, and HLL service routines generate return codes upon completion. There are two types of return codes: simple and composite. A simple return code is a constant value that requires no computation. A composite return code is a calculated value that consists of a known (constant) value and one or more unknown values.

The return code section at the end of each HLL command and service routine provides a chart of the following:

The return code represented in terms of constants and unknown values (if applicable)
The return code represented in terms of resolved constants and unknown values (if applicable)
A description of why the return code was issued

Several of the descriptions refer you to a NetView macro. Each of these macros is referenced in the IBM Tivoli NetView for z/OS Programming: Assembler book.

Do the following to resolve the unknown values of a composite return code:

Start with this equation:
```
HLBRC = Composite return code equation
```
Resolve all known values. The first and most obvious known value is that of HLBRC. All other known values are represented as constants in DSIPCNM (see PL/I Control Blocks and Include Files) and DSICCNM (see C language control blocks and include files). In the case where there is more than one unknown value to resolve (X and Y), the remaining calculated value is split into a major and minor return code.

The following examples show how to calculate unknown values of a composite return code.

Example 1

Upon completion of a call to CNMNAMS, HLBRC=4004. A return code value in the 4000 range implies that the composite return code equation is CNM_BAD_PUSH + X. (See CNMNAMS (CNMNAMESTR): Named Storage.)

The known values are resolved as follows:

      HLBRC = CNM_BAD_PUSH + X
       4004 = 4000 + X
4004 - 4000 = X
          4 = X

The unknown value X is equal to 4. The CNMNAMS return code indicates that the return code was generated by the DSIPUSH macro. The DSIPUSH macro, detailed in the IBM Tivoli NetView for z/OS Programming: Assembler book, indicates that the return code is caused by insufficient storage.

Example 2

Upon completion of a call to CNMCMD, HLBRC=-3108. A return code value in the -3000 range implies that the composite return code equation is X - CNM_BAD_EXCMS. (See CNMCMD (CNMCOMMAND): Invoke NetView commands.)

The known values are resolved as follows:

       HLBRC = X - CNM_BAD_EXCMS
       -3108 = X - 3000
-3108 + 3000 = X
        -108 = X

The unknown value of X is equal to -108. The CNMCMD return code indicates that the return code was generated by the DSICES macro. Refer to the description of this macro in IBM Tivoli NetView for z/OS Programming: Assembler.

The value of -108 in the previous example implies that X = SWBEXCNF - Y. The known values are resolved as follows:

       -108 = SWBEXCNF - Y
       -108 = -100 - Y
 -108 + 100 = -Y
-(-108+100) = Y
          8 = Y

The unknown value Y is equal to 8. This DSICES return code designates that an immediate command was located and that the address is returned.

Example 3

Upon completion of a call to CNMCNMI, HLBRC=21600. A return code value greater than 20000 for CNMCNMI implies that the composite return code equation is CNM_BAD_ZCSMS + (X * 100) + Y.

The known values are resolved as follows:

        HLBRC = CNM_BAD_ZCSMS + (X * 100 ) + Y
        21600 = 20000 + (X * 100) + Y
21600 - 20000 = (X * 100 ) + Y
         1600 = (X * 100) + Y

     =>  1600 / 100
         MAJOR_RC is the quotient  => 16
         MINOR_RC is the remainder => 0

The unknown values X and Y are equal to 16 and 0 respectively. The CNMCNMI return code indicates that the return code was generated by the DSIZCSMS macro. The DSIZCSMS macro in IBM Tivoli NetView for z/OS Programming: Assembler indicates that the return code is present because the call to CNMCNMI was not sent from a DST.

These return codes can also be seen in the initial return code value, 21600:

16 00 => 16 = MAJOR_RC
         00 = MINOR_RC

Example 4

Upon completion of a call to the CNMCNMI service routine, HLBRC=20408. A return code value in the 20000 range implies that the composite return code equation is CNM_BAD_ZCSMS + (X * 100) + Y.

The known values are resolved as follows:

        HLBRC = CNM_BAD_ZCSMS + (X * 100 ) + Y
        20408 = 20000 + (X * 100) + Y
20408 - 20000 = (X * 100 ) + Y
          408 = (X * 100) + Y

      =>  408 / 100
          MAJOR_RC is the quotient  => 4
          MINOR_RC is the remainder => 8

These return codes can also be seen in the initial return code value, 20408:

4 08 =>  4 = MAJOR_RC
         8 = MINOR_RC

The unknown values X and Y are equal to 4 and 8 respectively. The CNMCNMI return code indicates that the return code was actually generated by the DSIZCSMS macro. The DSIZCSMS macro return code (refer to IBM Tivoli NetView for z/OS Programming: Assembler) indicates that the function cannot be performed because the DSRB control block is not valid.

Example 5

Upon completion of a call to CNMKIO, HLBRC=28692. Only two composite return codes are issued from CNMKIO. Because the return code value is not in the 2000 range, the value of 28692 implies that the composite return code equation is (CNM_BAD_ZVSMS + X) * 256 + Y or (100 + X) * 256 + Y

This equation is difficult to resolve without knowing either X or Y. Use these equations to determine the major and minor return codes:

MAJOR_RC = (HLBRC / 256) - 100
         = (28692 / 256) - 100   (keep only the quotient)
         = 112 - 100
         = 12

MINOR_RC = HLBRC - ((CNM_BAD_ZVSMS + MAJOR_RC) * 256)
         = 28692 - ((100 + 12) * 256)
         = 28692 - (112 * 256)
         = 28692 - 28672
         = 20

The return code section of CNMKIO indicates that the return code was actually generated by the DSIZVSMS macro. This code indicates that the VSAM function was not complete because the request was not valid or because an I/O scheduling error occurred. Refer to IBM Tivoli NetView for z/OS Programming: Assembler for more information.

Feedback