Macro type: type S (E form/L form/D form/C form/M form) (see "Macro types")
The COMPFIL macro, like the COMPARE-DISK-FILES command, compares two disk files block by block (UPAM) or record by record (SAM, ISAM) and informs the user of the result of the comparison.
Temporary or work files can also be compared. The files can reside on public volumes, Net-Storage or private disks.
The files to be compared must be identical with respect to the following properties:
Access method (FILE-STRUCTURE or FCBTYPE)
Block format (BLOCK-CONTROL-INFO)
When BLKCTRL=*IGNORE, different block formats are also permissible.Coded character set (CODED-CHARACTER-SET, EXTENDED_HOST_CODE)
For SAM files:
RECORD-SIZE (RECSIZE) when RECORD-FORM=F (RECFORM=F)
For ISAM files:
RECORD-SIZE (RECSIZE) when RECORD-FORM=F (RECFORM=F)
Structure of the ISAM key (KEY-LEN, KEY-POS, LOG-LEN and VAL-FL-LEN)
Structure of the secondary key (KEY-LEN, KEY-POS, DUPKEY) for NK-ISAM
For UPAM files:
BUFFER-LENGTH (BLKSIZE)
HIGHEST-USED-PAGE (LPP)
Files with the following properties cannot be compared:
empty files
opened files
locked files (e.g. SECURE lock)
REPAIR-NEEDED label set
NO-DMS-ACCESS label set
Entire file generation groups cannot be compared, although individual file generations can.
PLAM libraries can be compared block by block. The members they contain cannot be compared.
The TPCOMP2 utility routine is available to compare tape files, see the “Utility Routines” manual [14].
Privileged functions
Systems support (TSOS privilege) can compare files of all user IDs. Wildcards are not permissible in the user ID here.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
PATHNM1
Selects the first file to be compared.
=<c-string 1..54: filename 1..54>
Name of the first file.
=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the name of the first file is stored.
PATHNM2
Selects the second file which is to be compared.
=<c-string 1..54: filename 1..54>
Name of the second file.
=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the name of the second file is stored.
BLKCTRL=*IGNORE / *INCLUDE
Specifies whether the files’ block format is included in the comparison (*INCLUDE) or ignored (*IGNORE).
PAMINFO=*INCLUDE / *IGNORE
Specifies whether the user information in the PAM key of UPAM files is included in the comparison (*INCLUDE) with BLOCK-CONTROL-INFO=*PAMKEY or ignored (*IGNORE).
OUTAREA=(<address>,<length>)
Determines the address and length of the output area in which the information concerning the file comparison is to be stored.
<address>=NULL / <var: pointer>
Specifies the address of the output area.
<length>=0 / <integer 0..32767>
Specifies the length of the output area.
<length>=<var: int:4>)
Only possible with MF=M:
Symbolic address of a memory area of 4 bytes in which the length of the output area is stored.
CALLER
Control operand; for MF=E and MF=M only:
Specifies whether an SVC or a direct call is to be generated when the function is called.
= USER
The function call is generated via SVC 144.
= SYSTEM
Control operand; for callers from TPR only:
A direct call is generated with BASR. The DSL conventions apply for the interface. When TU programs are linked, the entry generated cannot be satisfied.
EQUATES
Control operand; for MF=C and MF=D only:
Specifies whether equates are also to be generated for the values in the fields of the parameter or output area when the parameter or output area is expanded.
= *YES
Equates are also generated for the values in the fields of the parameter or output area when the parameter or output area is expanded.
= *NO
No equates are generated for the values in the fields of the parameter or output area when the parameter or output area is expanded.
XPAND
Control operand; for MF=C and MF=D only:
Determines which structure is to be expanded (generated). Specifications for this operand are ignored for other MF values.
= PARAM
The layout of the parameter list is expanded.
= OUTPUT
The layout of the output area is expanded.
Programming notes
All RESERVED fields of the parameter area must have been deleted with binary zeros.
The caller is responsible for the consistency of the parameter area whenever modifications are made to the parameter area without the help of GCs.
For all changes at parameter level that are not called with macros, the caller is responsible for the consistency of the parameter area.
The caller is responsible for deleting the output area.
In the event of a nonprivileged call (function status TU), register 1 points to the parameter area. In the event of a privileged call (function status TPR), the register assignment complies with the DSL convention.
Return codes
The return code is returned in the standard header of the parameter area. The parameter area may then not be located in the read-only area, otherwise the program terminates.
The following return codes are generated by COMPFIL:
X'cc' | X'bb' | X'aaaa' | Explanation |
X'00' | X'00' | X'0630' | No error. The files are identical. |
X'00' | X'00' | X'0631' | No error. The files are not identical. |
X'00' | X'40' | X'0501' | File catalog not available |
X'00' | X'40' | X'0505' | Error in host communication |
X'00' | X'40' | X'0512' | File catalog not found |
X'00' | X'40' | X'051B' | User ID not on the pubset |
X'00' | X'20' | X'0531' | Unexpected error during file catalog access |
X'00' | X'01' | X'0554' | Format of file name invalid |
X'00' | X'01' | X'0576' | Incorrect operand combination or UNUSED fields not deleted |
X'00' | X'82' | X'0594' | Insufficient virtual memory available |
X'00' | X'20' | X'05AB' | Address of output area incorrect or not specified |
X'00' | X'20' | X'05C7' | Internal error in DMS |
X'00' | X'40' | X'05F4' | Specified file names are identical |
X'00' | X'40' | X'05FC' | User ID not in home pubset |
X'00' | X'01' | X'0624' | Invalid file name |
X'00' | X'40' | X'0636' | File attributes are incompatible |
X'02' | X'00' | X'06CB' | Output information not completely transferred |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table in chapter "Standard header".
Layout of the parameter area
The parameter area must be aligned on a word boundary. It begins with a standard header which COMPFIL initializes as follows:
Function Unit Number | 22 |
Function Number | 33 |
Interface Version Number | 1 |
Return Code | -1 |
Macro expansion with MF=D and XPAND=PARAM and default values for EQUATES, PREFIX and MACID:
COMPFIL MF=D,XPAND=PARAM DMAVGLPL DSECT , DMAVHDR DS 0A DMAVFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER DMAVIFID DS 0A 0 INTERFACE IDENTIFIER DMAVFCTU DS AL2 0 FUNCTION UNIT NUMBER DMAVFCT DS AL1 2 FUNCTION NUMBER DMAVFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER DMAVRET DS 0A 4 GENERAL RETURN CODE DMAVSRET DS 0AL2 4 SUB RETURN CODE DMAVSR2 DS AL1 4 SUB RETURN CODE 2 DMAVSR1 DS AL1 5 SUB RETURN CODE 1 DMAVMRET DS 0AL2 6 MAIN RETURN CODE DMAVMR2 DS AL1 6 MAIN RETURN CODE 2 DMAVMR1 DS AL1 7 MAIN RETURN CODE 1 DMAVFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMAVPNAM1 DS CL54 Pathname1 DMAVPNAM2 DS CL54 Pathname2 DMAVBCTRL DS FL1 blockctrl operand * values of operand blckctrl_info DMAVBLKIG EQU 0 ignore DMAVBLKIN EQU 1 include * DMAVPINFO DS FL1 paminfo operand * values of operand paminfo DMAVPIIG EQU 0 ignore DMAVPIIN EQU 1 include * DMAVRES1 DS XL6 RESERVED DMAVARAD DS A Outarea=(<addr>,...) DMAVARLN DS F Outarea=(...,<length>) DMAV# EQU *-DMAVHDR
Layout of the output area
The output area must be aligned on a word boundary.
Macro resolution with MF=D and EXPAND=OUTPUT, as well as default values for EQUATES, PREFIX and MACID:
COMPFIL MF=D,XPAND=OUTPUT
DMAVOUTP DSECT ,
* Compfile Output
DMAVMSGNR DS F MESSAGENUMBER
*
DMAVMSGINF DS 0XL80 MESSAGEINFO
DMAVMSG_DETAILS DS 0XL80 MESSAGEDETAILS
DMAVPNAM DS CL80 PATHNAME
ORG DMAVMSG_DETAILS
*
DMAVCMPINF DS 0XL12 COMPAREINFO
DMAVPAGNR DS F PAGENUMBER
DMAVRECNR DS F RECORDNUMBER
DMAVBYTENR DS F BYTENUMBER
DMAVABSRECNR DS F ABSOLUT RECORDNUMBER FOR SAM
* FILES
DMAVERRNR DS FL1 ATTRIBUT ERROR
* type of file attribut error
DMAVBKCTR EQU 1 blk-contr
DMAVFISTR EQU 2 file-struc
DMAVFITYP EQU 3 file-type
DMAVHIUSP EQU 4 high-us-pa
DMAVRECFR EQU 5 rec-form
DMAVRECSZ EQU 6 rec-size
DMAVKEYPO EQU 7 key-pos
DMAVKEYLN EQU 8 key-len
DMAVVALLN EQU 9 val-len
DMAVLOGLN EQU 10 log-len
DMAVALTIX EQU 11 alternate-index
DMAVLBP EQU 12 last-byte-pointer
DMAVBKSZ EQU 13 block-size
DMAVPKUI EQU 14 pamkey-user-info
DMAVLASTP EQU 14 last-position
DMAVABSRECNR63 DS 0XL8 ABSOLUT RECORDNUMBER FOR SAM
* FILES big counter
DMAVABSRECNRH DS F high cnt
DMAVABSRECNRL DS F low cnt
*
*
ORG DMAVMSG_DETAILS+80
*
DMAVUNUS DS XL8 UNUSED
DMAVOUTPUT# EQU *-DMAVMSGNR
The following cases are distinguished when the COMPFIL information is output to the user’s output area:
No output was possible
No output area was made available by the caller or the output area was write-protected. In the standard header of the output area the user receives the return code X'05AB' following validation of the output area or of the address. If the output area was too small to transfer the output information, the caller receives the return code X'06CB'.Error when accessing one or both of the files to be compared
The first file in which an access error occurs is output in the DMAVPNAM field in the format :<cat-id>:$<user-id>.<filename>. In addition, message number X'0681', indicating a general file access error, is output in the DMAVMSGNR field. The precise reason for this access error can be found in the return code placed in the parameter area’s standard header.The comparison of the two files is not possible because of the incompatibility of their file attributes
Message number X'0636' is output in the standard header of the parameter area and in the DMAVMSGNR field of the output area. In addition, the DMAVERRNR field indicates which file attribute led to the comparison aborting.The same name was specified for both files
The same return code is displayed in the standard header of the parameter area and in the DMAVMSGNR field of the output area.The two files are identical
Return code X'0630' is displayed in the standard header of the parameter area. The DMAVMSGNR field of the output area contains X'0000'.The two files are not identical
Return code X'0631' is displayed in the standard header of the parameter area. Depending on the access method, the following correlation exists between MESSAGENUMBER in the DMAVMSGNR field and the COMPARINFO in the DMAVPAGNR (PAGENUMBER), DMAVRECNR (RECORDNUMBER), DMAVBYTENR (BYTENUMBER) and DMAVABSRECNR (ABSOLUT RECORD NUMBER FOR SAM FILES) fields.Access
methodMESSAGE
NUMBERPAGE
NUMBERRECORD
NUMBERBYTE
NUMBERABSOLUTE
RECORD
NUMBERMeaning
SAM
X'0632'
<p>
<r>
<a>
1
ISAM
X'0633'
<r>
2
UPAM
X'0634'
<p>
<b>
3
UPAM
X'0635'
<p>
4
1 The two SAM files differ as of record <a>. That is record <r> within the 2k data block <p>.
2 The two SAM files differ as of record <r>.
3 The two UPAM files differ as of data byte <b> within the 2k data block <p>.
4 The two UPAM files differ in the user information in the PAM key of the 2K data block <p>, but their contents are identical (specification PAMINFO=*INCLUDE).
Sample calling sequence
MVC COMPMFC(DMAV#),COMPMFL COMPFIL MF=M,OUTAREA=(A(COMPOAC),OUTLEN),PARAM=COMPMFC, - PATHNM1=':X:SAM.1',PATHNM2=':X:SAM.2' COMPFIL MF=E,PARAM=COMPMFC . . COMPMFC COMPFIL MF=C,XPAND=PARAM COMPOAC COMPFIL MF=C,XPAND=OUTPUT COMPMFL COMPFIL MF=L,PATHNM1='AAA',PATHNM2='BBB' OUTLEN DC A(DMAVOUTPUT#)