TESTCB—Test a field of an access method control block

Only one keyword can be specified each time you issue TESTCB.

The format of the TESTCB macro used to test a field in an access method control block is:

[label]

TESTCB

ACB=address
[,ERET=address]
[,OBJECT=DATA|INDEX]
,{ATRB=([ESDS][,KSDS][,LDS][,REPL]
[,RRDS][,SPAN][,SSWD][,VRRDS][,WCK])|
ATRB=COMPRESS|
ATRB=UNQ|
ATRB=XADDR|
MACRF=([ADR][,AIX][,CFX][,CNV][,DDN]
[,DFR][,DIR][,DSN][,GSR][,ICI][,IN]
[,KEY][,LEW][,LSR][,NCI][,NDF][,NFX][,NIS]
[,NLW][,NRM][NRS][,NSR][,NUB][,OUT][,RLS][,RST]
[,SEQ][,SIS][,SKP][,UBF])|
OFLAGS=OPEN|
OPENOBJ={PATH|BASE|AIX}|
ACBLEN=abs expression|
AVSPAC=abs expression|
BSTRNO=abs expression|
BUFND=abs expression|
BUFNI=abs expression|
BUFNO=abs expression|
BUFSP=abs expression|
CINV=abs expression|
DDNAME=character string|
ENDRBA=abs expression|
ERROR=abs expression|
EXLST=address|
FS=abs expression|
KEYLEN=abs expression|
LRECL=abs expression|
MAREA=address|
MLEN=abs expression|
NCIS=abs expression|
NDELR=abs expression|
NEXCP=abs expression|
NEXT=abs expression|
NINSR=abs expression|
NIXL=abs expression|
NLOGR=abs expression|
NRETR=abs expression|
NSSS=abs expression|
NUPDR=abs expression|
PASSWD=address|
RKP=abs expression|
SHRPOOL=abs expression|
STMST=address|
STRNO=abs expression}

The subparameters of the TESTCB macro can be expressed as absolute numeric expressions, as character strings, as codes, as expressions that generate valid relocatable A-type address constants, in register notation, as S-type address constants, and as indirect S-type address constants. Subparameters with GENCB, MODCB, SHOWCB, and TESTCB, further defines these operand expressions.

ACB=address

specifies the address of the access method control block whose information you want to test. Omit it only if you are testing the length of an access method control block (ACBLEN=number). (All VSAM access method control blocks have the same length.)

ERET=address

specifies the address of a routine to which VSAM gives control if an error occurs and VSAM is unable to test for the specified condition. For example, testing AVSPAC in an access method control block for an unopened data set would fail. VSAM indicates in register 15 whether it could do the test and, if not, indicates in register 0 the reason it could not. (The reasons are discussed under Control block manipulation macro return and reason codes.) A failure trying to execute TESTCB indicates a basic logical problem in the processing program, so the error routine would probably issue an ABEND. If it lets the program continue, it must branch to the continuation point itself, and not return to VSAM.

OBJECT={DATA|INDEX}

specifies whether to test a field for data or for index.

ATRB=([ESDS][,KSDS][,LDS]

[,REPL]

[,RRDS]

[,SPAN]

[,SSWD]

[,VRRDS]

[,WCK])

specifies, for an open data set, the attribute to be tested for, as follows:

ESDS: specifies entry-sequenced data set.
KSDS: specifies key-sequenced data set.
LDS: specifies linear data set.
When specified, LDS must be the only parameter indicated by ATRB. All other parameters are ignored and a binary test performed indicating whether the data set is a linear data set (return code 0) or not (return code 1).
REPL: specifies that some portion of the index is replicated.
RRDS: specifies relative record data set.
SPAN: specifies that the data set contains spanned records.
SSWD: specifies that the sequence set is adjacent to the data.
VRRDS: specifies variable-length relative record data set.
WCK: specifies that the write operations for the data set are being verified.

ATRB=COMPRESS

specifies if the data set is in compressed format.

ATRB=UNQ

specifies, for an open alternate index or path, that the alternate index requires unique keys. The test for ATRB=UNQ must be made with a separate TESTCB macro. VSAM examines the path control blocks for the UNQ attribute. VSAM also examines the base cluster's control blocks for the other attributes. If other attributes are tested for, VSAM examines the base cluster's control blocks for all attributes. The test for ATRB=UNQ would give inaccurate results when applied to the base cluster's control blocks.

ATRB=XADDR

specifies if the data set is in extended addressability format.

MACRF=([ADR][,AIX][,CFX]

[,CNV] [,DDN]

[,DFR] [,DIR]

[,DSN] [,GSR]

[,ICI][,IN]

[,KEY][,LEW]

[,LSR][,NCI]

[,NDF][,NFX]

[,NIS][,NLW]

[,NRM][,NRS]

[,NSR][,NUB]

[,OUT][,RLS][,RST]

[,SEQ][,SIS]

[,SKP][,UBF]

specifies that a test is made to determine, at any time, what subparameter or combination of subparameters is being used for processing.

OFLAGS=OPEN

specifies that a test is made to determine, after open, whether the data set identified by the control block was opened.

OPENOBJ=PATH|BASE|AIX

specifies that a test is made to determine, after open, whether an opened object is a path, a base cluster, or an alternate index.

Note: When OPENOBJ is used with an ACB opened for an alternate index, both OPENOBJ=AIX and OPENOBJ=BASE return TRUE (PSW condition code = 0). When OPENOBJ is used with an ACB opened for a path, only OPENOBJ=PATH returns TRUE.

The remaining parameters represent fields in an access method control block that can be compared with the value specified. These fields are the same as those that can be displayed by using the SHOWCB macro and are described in Table 1.

If you omit a routine to handle error conditions, you can examine register 15 following TESTCB by using a branch table, for example, but do not alter the PSW condition code that VSAM set to indicate the result of a test until you have tested it.

Important: If you issue a TESTCB for a non-VSAM and non-VTAM ACB, the results will be unpredictable.