SHOWCB

Access Control Block Format

See also Exit List Format and Request Parameter List Format.

Option A

Notes:

• ¹ The first option does not require a comma before it, but every option thereafter must have a comma preceding it.

Purpose (ACB)

An access method control block (ACB) defines certain characteristics of a file that you intend to process through VSE/VSAM. When the file is opened, other characteristics of the file that you defined through the DLBL command are merged with the ACB to complete the picture.

The contents of each field (except the ACBLEN field) is determined by the corresponding parameter in the ACB macro, the GENCB macro, or the DLBL command. See ACB and GENCB. For more information on the DLBL command, see DLBL. Also, see Using VSAM.

This discussion of the SHOWCB macro deals only with those matters that involve GCS.

Parameters (ACB)

ACB

Specifies the address of the ACB containing the fields you want displayed.

All ACBs are the same length. So, if you only want the ACBLEN field displayed, you need give no ACB address.

If you entered the ACB macro with a label attached to it, then you can write this parameter as that label.

AREA

Specifies the address of a work area that you have provided in virtual storage to accept the ACB fields to be displayed.

The contents of the fields are displayed in this area in the order which you list them in the SHOWCB macro.

This work area must begin on a fullword boundary.

LENGTH

Specifies the length, in bytes, of the work area that you have provided in virtual storage to hold the ACB fields to be displayed.

Check the following field parameters listed to determine the necessary length for this work area. If the area is not large enough to accept all the fields you specify, then you will receive an error code.

OBJECT

Indicates the scope of your request.

DATA

Indicates that the fields you specify pertain to the data contained in the file. This is the case by default.

INDEX

Indicates that the fields you specify pertain to the index.

FIELDS

Indicates which fields in the ACB you want displayed.

Some of the ACB fields can be displayed at any time. Others can be displayed only after the file in question has been opened. As with a key-sequenced file opened for keyed access, the fields can pertain to either the data or the index.

The number following each field name specifies the number of fullwords needed in the work area to accept the field.

The following fields can be displayed at any time:

 

ACBLEN (1)

The length of the access method control block in question.

BUFND (1)

The number of I/O buffers used for data.

BUFNI (1)

The number of I/O buffers used for the index.

BUFSP (1)

The amount of space allocated for I/O buffers.

DDNAME (2)

The logical name of the file associated with the ACB in question.

ERROR (1)

The code returned after opening or closing the file associated with the ACB in question.

EXLST (1)

The address of the list of exit routine addresses. If none was specified, then this field contains 0.

MAREA (1)

The address of the message area. If none was specified, then this field contains 0.

MLEN (1)

The length of the message area. If none was specified, then this field contains 0.

PASSWD (1)

The address of the field containing the password to the file associated with the ACB in question. The first byte of the field contains the binary length of the password.

STRNO (1)

The number of requests for which the position in the file is to be remembered.

The following fields can be displayed only after the file is open:

 

AVSPAC (1)

The amount of available space, in bytes, in the data component or index component.

BUFNO (1)

The number of I/O buffers actually in use by the data component or index component.

CINV (1)

The control interval size for the data component or index component.

FS (1)

The number of free control intervals per control area in the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

KEYLEN (1)

Either the full length of the prime key field or the alternate key field in each logical record. Which it is depends on whether you access the base cluster through a path.

LRECL (1)

The length of the records in the data component or the index component. For the former, with variable-length records, this is the maximum length of any record. For the latter, this is the control interval length minus seven.

NCIS (1)

The number of control intervals that have been split in the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NDELR (1)

The number of records that have been deleted from the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NEXCP (1)

The number of EXCP macros that have been issued to obtain access to the data component or index component.

NEXT (1)

The number of extents currently allocated to the data component or the index component.

NINSR (1)

The number of records that have been inserted into the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NIXL (1)

The number of levels in the index component. If you specified the OBJECT=DATA parameter, then this field contains 0.

NLOGR (1)

The number of records in the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NRETR (1)

The number of records that have ever been retrieved from the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NSSS (1)

The number of control areas that have been split in the data component. If you specified the OBJECT=INDEX parameter, then this field contains 0.

NUPDR (1)

The number of records in the data component that have ever been updated. If you specified the OBJECT=INDEX parameter, then this field contains 0.

RKP (1)

The displacement of either the prime key field or alternate key field from the beginning of a data record. Which it is depends on whether you access the base cluster through a path. The same value is displayed whether the object is index or data.

STMST (2)

The system time stamp, which specifies the time and date on which the data component or index component was closed. Bit 51 is equivalent to one microsecond and bits 52 through 63 are unused.

STRMAX (1)

Specifies the maximum number of request which were concurrently active because the resource pool was built. The ACB specified must be associated with a resource pool, that is the parameter MACRF=(LSR) must have been specified for the ACB.

Usage (ACB)

1. Each time you enter the SHOWCB macro, you must provide the system with a 72-byte save area. Before you enter the instruction, place the address of this save area in register 13.

Completion Codes, Return Codes, and ABEND Codes (ACB)

When this macro completes execution, it passes to the caller a completion code in register 15.

When register 15 contains 4, then register 0 contains one of the following return codes.

Exit List Format

Purpose (EXLST)

During VSAM processing, unusual conditions sometimes occur. If you wish, you can supply one or more exit routines to handle such conditions. See EXLST or GENCB. You can then associate them with one or more access method control blocks (ACBs) that define the characteristics of the VSAM files you plan to process. See ACB or MODCB.

This discussion of the SHOWCB macro deals only with those matters that involve GCS.

Use the SHOWCB macro to display certain fields of an exit list. This display appears in a virtual storage work area that you set aside for this purpose.

Parameters (EXLST)

EXLST

Specifies the address of the exit list whose fields you want to display.

If you omit this parameter and specify the EXLLEN parameter, then the EXLLEN field will display the maximum allowable length of any exit list.

If you used the EXLST macro to generate the exit list, and you applied a label to that instruction, then you can write this parameter as that label.

AREA

Specifies the address of a work area in virtual storage you have set aside for the display of the exit list fields.

This area must begin on a fullword boundary. The fields are displayed in the order which you specify them in the SHOWCB macro.

LENGTH

Specifies the length, in bytes, of a work area in virtual storage you have set aside for the display of the exit list fields.

Each exit list field requires one fullword. Therefore, allow 4 bytes for each field you specify in the FIELD parameter. If the work area is not large enough to accept all the fields you specify, then you will receive an error code.

FIELDS

Indicates the scope of your request.

EODAD

Indicates that the address of the END-OF-FILE routine will be displayed.

EXLLEN

Specifies one of two things:

• If the EXLST parameter is specified, then the length of the exit list will be displayed.
• If the EXLST parameter is not specified, then the maximum allowable length of any exit list will be displayed.

JRNAD

Specifies that the address of the journaling routine will be displayed.

LERAD

Specifies that the address of the logical error analysis routine will be displayed.

SYNAD

Specifies that the address of the physical error analysis routine will be displayed.

Usage (EXLST)

1. Use the SHOWCB macro to display a certain field in an exit list only if that field exists.

   GCS will display the fields in the order which you request them.

2. Each time you enter the SHOWCB macro, you must provide the system with a 72-byte save area. Before you enter the macro, place the address of this save area in register 13.
3. See Using VSAM.

Completion Codes, Return Codes, and ABEND Codes (EXLST)

When this macro completes execution, it passes to the caller a completion code in register 15.

When register 15 contains 4, then register 0 contains one of the following return codes.

Request Parameter List Format

Option A

Purpose (RPL)

All VSAM functions require that you set up a request parameter list (RPL) that describes the characteristics of your request. These VSAM functions are associated with the following macros: CHECK, ENDREQ, ERASE, GET, POINT, and PUT. See CHECK, ENDREQ, ERASE, GET, POINT, or PUT. Also, see Using VSAM.

You create a request parameter list through the RPL or GENCB macros. See RPL or GENCB.

This discussion of the SHOWCB macro deals only with those matters that involve GCS.

Use the SHOWCB macro to display certain fields of a request parameter list. This display appears in a work area that you have set aside for this purpose.

Parameters (RPL)

RPL

Specifies the address of the request parameter list whose fields you want to display.

Because all RPLs are the same length, you can omit this parameter if the only field you are interested in displaying is the RPLLEN field.

If you used the RPL macro to create this request parameter list, and you applied a label to that instruction, then you can write this parameter as that label.

AREA

Specifies the address of a work area in virtual storage you have set aside to accommodate the RPL fields you want to display.

This work area must begin on a fullword boundary. The fields are displayed in this work area in the order which you list them in the SHOWCB macro.

LENGTH

Specifies the length, in bytes, of the work area in virtual storage you have set aside to accept the RPL fields you want to display.

Each RPL field requires one fullword. Therefore, allow 4 bytes for each field you specify in the FIELDS parameter.

FIELDS

Indicates which fields you want to display.

ACB

The address of the access method control block that relates the RPL to the file you are processing.

AIXPC

The number of alternate index pointers.

AREA

The address of the work area that your program uses to process the file records. Access to this file is defined by the RPL.

AREALEN

The length of the work area whose address is specified in the AREA field.

ARG

If you are using search arguments to process your file, the address of the field containing that search argument.

ECB

The address of the event control block associated with the RPL in question. It is in this ECB that the completion of the request associated with the RPL is posted.

FDBK

The address of the feedback field that will contain the return code from the request associated with this RPL.

For asynchronous requests, you must enter the CHECK macro to place the return code in this field. See CHECK. The significance of this return code depends on the contents of register 15, which indicates whether the request was successful or unsuccessful because of logical or physical error.

FTNCD

The code that describes the function which a logical or physical error occurred.

KEYLEN

If you are using a generic key as a search argument, the length of that argument.

NXTRPL

The address of the next request parameter list in the chain, if one exists.

RBA

The relative byte address of the most recently processed record in the file.

RECLEN

The length of the file record, access to which is defined by the request parameter list.

RPLLEN

The length, in bytes, of any request parameter list.

TRANSID

Specifies that you want to have the TRANSID displayed in your work area when RPL= is specified.

Usage (RPL)

1. Each time you enter the SHOWCB macro, you must provide the system with a 72-byte save area. Before you enter the instruction, place the address of this save area in register 13.
2. Display of TRANSID requires one fullword in your work area.

Completion Codes, Return Codes, and ABEND Codes (RPL)

When this macro completes execution, it passes to the caller a completion code in register 15.

When register 15 contains 4, then register 0 contains one of the following return codes.