Macro type: type S (C form/D form/E form/L form/M form); see "Macro types"
The COPFILE macro copies files, file generations and file generation groups in blocks from disk to disk, from disk to tape and from tape to disk without modifying them. Consequently it cannot normally be used to modify file attributes. The only exception concerns the block control attribute, which can be modified during copying in certain cases (see "File link names" and the description of the operand "BLKCTRL").
If the output (or target) file is not yet cataloged, it is automatically created on a public volume (as with a FILE with default values for the specified output file) when COPFILE is executed.
If the target file is to be on a different Speichertyp (Public-Storage oder Net-Storage) oder volume (private disk, Net-Storage or tape), it must be set up using FILE (operands DEVICE, VOLUME) before the COPFILE macro is called.
If the target file is a disk file which has not yet been cataloged, the primary and secondary allocations are taken from the original disk file.
If the target file is a disk file, its primary and secondary allocations are not modified unless they are smaller than those of the original file.
If the original file is on tape, a default value is used for the target file.
Note
The COPFILE macro is the earlier COPY macro extended by the use of wildcards in pathname1 (selection) and pathname2 (construction). The additional operands CHECK and LIST have also been provided. The function of the earlier COPY is still supported. The format of the COPY macro is therefore still included in the appendix (see "Formats of replaced macros"). Its operands, however, are the same as those of the COPFILE macro and are therefore only described here.
File generation groups
A file generation group can be copied into another file generation group only if one of the following conditions is fulfilled:
The group entries for the two file generation groups match (i.e. the values for GEN, FIRST, LASTGN and BASE are the same). In the file generation group into which DMS is to write the copy, the generations from FIRST to LASTGN must already be cataloged and have storage space allocated.
The value for GEN is the same for both file generation groups, and the file generation group into which DMS is to write the copy contains no generations (i.e. FIRST, LASTGN and BASE have the value zero).
The file generation group to be copied may not contain tape file generations (COPFILE does not support copying of tapes).
A file generation group can be copied into a single file or file generation only if the following conditions are satisfied:
The file generation group consists of SAM file generations with identical attributes (e.g. the same record and block lengths, the same record format, the same block control attribute).
The file generation to which the copy is to be made does not belong to the file generation group to be copied.
A single file or file generation can only be copied into a file generation group if the following condition is fulfilled:
The file or file generation must possess the same CODED-CHARACTER-SET as the file generation group.
Files on private disks
If a file on private disk only has an entry in the system catalog but no F1 label, the catalog entry is deleted. If the file is the input file, COPFILE is rejected.
A COPFILE call for an ISAM file on private disk with index and data sections on different disks is rejected.
Tape files
Internally, COPFILE uses the UPAM access method, which does not support continuation tape processing. This means that it is possible to copy several files to the same tape (FILE macro, FSEQ operand), but not files that extend over more than one tape.
K tape files (BLKCTRL=PAMKEY) must have standard block format (BLKSIZE=(STD,n)) if they are to be processed by the COPFILE macro.
NK tape files (BLKCTRL=DATA/NO) can be processed by COPFILE if their BLKSIZE value is a multiple of 2048 bytes.
If NK files are copied to tape, the BLKCTRL information is lost when the catalog entry is deleted. If the file is to be copied back again, the COPFILE macro must be preceded by a FILE macro with the operands LINK and STATE=FOREIGN and with the correct value for the BLKCTRL operand, i.e. either NO or DATA, to match the actual data format of the file.
If a K file (BLKCTRL=PAMKEY) is inadvertently copied in this manner into an NK file (BLKCTRL=DATA), the resulting disk file cannot be read, because the first 16 bytes of each logical block, which contain data when BLKCTRL=PAMKEY applies, are overwritten with management information.
Foreign files on tape: if an uncataloged tape file is to be copied, a TFT entry with the file link name valid for COPFILE must be created before copying in order to define the file attributes (see "File link names").
FILE pathname1,LINK=DMCOPY11,STATE=FOREIGN,BLKCTRL=...
File link names
Internally, COPFILE uses the file link names DMCOPY11 (for the original file pathname1) and DMCOPY22 (for the target file pathname2). On completion of processing, the file link names are implicitly released (implicit REL macro).
The option of selecting an original and a target file for COPFILE processing by means of a FILE macro with appropriate file link names can be used, for example, in order to modify the file's block control attribute during copying. Specifying the BLKCTRL operand in the FILE macro together with BLKCTRL=*IGNORE/*CHECK in the COPFILE macro enables the definition of different BLKCTRL attributes for original and target file in the course of copying (see the description of the operand "BLKCTRL").
When there are wildcards in the file name, an existing TFT entry (DMCOPY11/DMCOPY22) only becomes effective when the first file to be processed is copied.
Remote file access (see also the “RFA” manual [6])
Copying from one remote system to another, with input and output on different systems, is supported by a higher-level execution routine. In this case, the local system acts only as an intermediate station for data transfer. A SET-RFA-CONNECTION command must be issued for each of the remote systems before copying is started.
If a remote file is copied to a local file with the PROTECT=*SAME operand, the passwords are not copied with the file.
SM pubsets
If the target file does not yet exist, an attempt is made to create it on a suitable volume set using the source file attributes for selecting the volume set (performance, availability).
File encryption
Normally no crypto password is required to copy an encrypted file. COPFILE transfers the contents of an encrypted file without decrypting the file, and the target file is assigned the same encryption attributes as the source file, in particular the crypto password.
The exceptions here are copy operations which require file decryption:
An encrypted file is to be copied to tape or private disk.
An encrypted file is to be copied to a file generation.
A shared update was declared via the TFT entry DMCOPY11 or DMCOPY22.
Macro format
Operation | Operands |
|
|
Operand descriptions
BLKCTRL
Specifies whether the target file (or the TFT entry DMCOPY22) may have a different BLKCTRL attribute than the source file pathname1.
TFT entry or target file (with null operands in the TFT) must have the same BLKCTRL attribute as the source file.
Default value: | pathname1 and the TFT entry for DMSCOPY22 must have the same BLKCTRL attribute. |
= *IGNORE
Even if the BLKCTRL attributes of pathname1 and the TFT entry for DMCOPY22 do not match, pathname1 can be copied to pathname2 in the following cases:
BLKCTRL attribute of the file pathname 1 | BLKCTRL attribute of the file pathname 2 |
PAMKEY | DATA (disk files only) |
PAMKEY | NO |
DATA (disk files only) | PAMKEY |
NO | PAMKEY |
Note
It is the user's responsibility to ensure that no data is lost in the course of copying. This danger exists when copying a file with BLKCTRL=PAMKEY to a file with BLKCTRL=DATA or BLKCTRL=NO: in both cases, the information in the user section of the PAM key is lost. Furthermore, if the target file has the attribute BLKCTRL=DATA, the first 12 bytes of each logical block (in the case of ISAM files, the first 16 bytes) are overwritten by the block control field.
= *CHECK
Even if the BLKCTRL attributes of pathname1 and the TFT entry for DMCOPY22 do not match, it is possible to copy pathname1 to pathname2 whenever this can be done without losing any user information in the user section of the PAM key. If the user part of the PAM key does not contain any user information (this is checked here), pathname1 can be copied to pathname2 when the following BLKCTRL attributes apply; otherwise, the command is rejected.
BLKCTRL attribute of the file pathname 1 | BLKCTRL attribute of the file pathname 2 |
PAMKEY | DATA (disk files only) |
PAMKEY | NO |
CHDATE
Specifies whether the target file will be given the same change date (CHANGE-DATE) as the source file.
= *STD
Only for PROTECT=*STD or *SAME:
The change date of the target file is updated.
The specification PROTECT=*SAME-AND-CHANGE-DATE is still supported for reasons of compatibility and causes the source file’s change date to be transferred to the target file.
= *SAME
The source file’s change date is transferred to the target file. The specification CHDATE=*SAME also applies in the following cases:
The target file is located under a foreign user ID.
The target file is a file generation.
CHECK
Only for wildcard entries:
Defines the conditions in interactive mode under which a user dialog is to be started if multiple files are selected using wildcards.
If the dialog is started, the user can decide whether or not processing is to be executed on the displayed file(s). He can also call up help text on the reply options and define a new value for CHECK and/or LIST when processing is resumed.
The value 'NO' always applies in batch mode.
The operand has no effect if pathname1 contains no wildcards or is not partially qualified.
= *MULTIPLE
A check dialog is only started if multiple files are selected.
If the catalog and/or user ID contain wildcards, a check dialog is executed for each catalog and/or user ID.
CHECK=*ERROR is also implied.
= *NO
All selected files are processed without a check dialog, i.e. without any possible user intervention.
= *ERROR
An error check dialog is started if an error occurs during processing of a selected file name. A file set check dialog is started if the selection entry selects more files than can be processed in available memory. CHECK=*ERROR is also always implied for all entries where CHECK!=*NO.
= *SINGLE
A check dialog is executed for each selected file name. CHECK=*ERROR is also implied.
= *CATALOG
The user must decide in a check dialog for each catalog whether the files selected in them are to be processed.
CHECK=*ERROR is also implied.
= *USERID
Reserved for system administrators:
The system administrator must decide in a check dialog for each user ID and each catalog whether the selected files are to be processed.
CHECK=*ERROR is also implied.
IGNORE
For the system administrator only:
Allows the system administrator to ignore file protection for the source and/or target file.This operand has no effect on files located on a remote computer (RFA). If a TSOS restriction exists for a file under a foreign user ID then the ACCESS protection attribute is ignored.
= *SOURCE
The protection attributes READ-PASSWORD and EXEC-PASSWORD of the source file are ignored when copying (also applies to BASIC-ACL and GUARDS protection).
= *TARGET
The protection attributes ACCESS and EXPIRATION-DATE and the READ-/WRITE-/ EXEC-PASSWORD attributes of the target file are ignored when copying (also applies to BASIC-ACL and GUARDS protection).
LIST
Defines whether a log is to be written to SYSOUT for all file names selected with wildcards after their processing.
The operand has no effect if pathname1 contains no wildcards or is not partially qualified.
= *NO
No log is kept.
= *SYSOUT
Each processed file and any errors that occur are logged in a report.
= *ERRORS_TO_SYSOUT
Only those files whose processing led to errors are logged in a report.
MACID
Only evaluated in conjunction with MF=C; defines the second through fourth characters of the field names and equates which are generated during macro execution in the data area.
Default: | MACID = MAC |
= macid
“macid” is a three-character string which defines the second through fourth characters of the generated field names and equates.
MF
The forms of the MF operand are described in detail in the appendix ("Macro types").
PARAM
Defines the address of the operand list and is only evaluated in conjunction with MF=E (see also "Macro types").
= addr
The symbolic address (the name) of the operand list.
= (r)
The number of the register containing the address of the operand list. This register must be loaded with the appropriate address value before calling the macro.
PATHNM1 =
Pathname of the original file
= <c-string 1..80: filename 1..54 with-wild(80) without-gen>
pathname1 (enclosed in single quotes)
= <var: char: 80: filename 1..54 with-wild(80) without-gen>
Name of a variable that contains pathname1
Pathname1 means [:catid1:][$userid1.]filename1
catid 1
Catalog ID of the original file; default value: the catalog ID belonging to the user ID.
userid 1
User ID of the original file; default value: the user ID specified in the SET-LOGON-PARAMETERS/LOGON command.
filename 1
Name of the original file, file generation or file generation group.
Read permission must exist for the original file.
If pathname1 is an FGG, pathname2 must also be an FGG, unless the FGG pathname1 consists of SAM file generations with the same attributes with respect to record format, record length, block size, and block control information. In this case, it is possible to copy into a single file or into a file generation, but this file generation must not belong to the FGG which is to be copied.
Wildcard use
Selection criteria for the files to be copied. The nonprivileged user may only use wildcards in the catalog ID and file name.
PATHNM2
Pathname of the output/target file.
= <c-string 1..80: filename 1..54 with-wild(80) without-gen>
pathname2 (enclosed in single quotes)
= <var: char: 80: filename 1..54 with-wild(80) without-gen>
Name of a variable that contains pathname2
pathname2 means [:catid2:][$userid2.]filename2
catid 2
Catalog ID of the output file; default value: the catalog ID belonging to the user ID.
userid 2
User ID of the output file; default value: the user ID specified in the SET-LOGON-PARAMATERS or LOGON command.
filename 2
Fully qualified name of the output file, file generation or file generation group.
pathname1 and pathname2 must not be identical.
If pathname2 is not yet cataloged, only the user's own user ID may be specified, i.e. the user ID of the SET-LOGON-PARAMETERS/LOGON command or a user ID of which the user is co-owner.
If pathname2 is already cataloged, write access must be permitted.
The COPFILE macro call is rejected if pathname2 is read-only (e.g. ACCESS=READ or EXDATE > current date) or if the secondary allocation for disk file pathname2 is 0 and the primary allocation is too small to accommodate the file to be copied.
If pathname2 is cataloged under a foreign user ID, this user ID must also be specified.
If pathname2 is a file generation group, pathname1 must also be a file generation group.
Wildcard use
Construction entry for the files to be copied to as a result of the selection criteria (pathname1).
SM pubsets
If the output/target file is not yet cataloged, an attempt is made to create it on a suitable volume set using the attributes of the original file.
PREFIX
Only evaluated in conjunction with MF=C or MF=D; this defines the first character of field names and equates which are generated in the data area with macro execution.
Default: | PREFIX = D |
= pre
A single-character prefix with which field names and equates generated by the assembler are to begin.
PROTECT
Defines whether the copy pathname2 receives the same file backup and protection attributes as pathname1.
As far as is possible and permitted, the encryption attributes are taken over into the target file when copying takes place regardless of the PROTECT specifications (see also "File encryption").
= *STD
If pathname2 is not yet cataloged, the new file is set up with the default attributes (see operand defaults in the CATAL macro, "CATAL - Process catalog entry", e.g. SHARE=NO, ACCESS=WRITE for disk files etc.).
= *SAME
The copy pathname2 receives the same file backup and file protection attributes as pathname1 (identical values for ACCESS, BACKUP, DELDATE, DESTROY, LARGE, MANCLAS, MIGRATE (FORBIDDEN is set to INHIBIT), NUM-OF-BACKUP-VERS, OPNBACK, RETPD, SHARE and the same passwords). The following are not transferred: AUDIT, AVAIL, PREFORM, S0MIGR, STOCLAS, VOLSET and WORKFIL.
The entry PROTECT=*SAME is ignored if pathname2 is cataloged under a foreign user ID or is a file generation (its file attributes are then defined in the group entry).
If a temporary file is copied into a permanent file, only the attribute BACKUP=E is taken over for the specification PROTECT=*SAME. The new file is ignored for ARCHIVE save runs. If the new file is to be saved automatically with ARCHIVE, the BACKUP value must be changed by means of CATAL.
When pathname1 is protected by a BASIC-ACL entry (see the “Introductory Guide to DMS” [1]), or GUARDS entry, the following points apply to copying with PROTECT=*SAME:
If the target file was created on a public disk, the access rights of BASIC-ACL or GUARDS are copied.
If the target file pathname2 is created on a private disk, and if pathname1 is protected by BASIC-ACL, the protection attributes from the BASIC-ACL are used for pathname2. If a GUARDS entry has been created for pathname1, pathname2 is assigned the default protection attributes SHARE=NO and ACCESS=WRITE.
If the target file pathname2 is created on a magnetic tape, it is assigned the default protection attributes SHARE=YES and ACCESS=WRITE, regardless of the protection attributes defined for pathname1 by the BASIC-ACL or GUARDS.
If the source file pathname1 is not cataloged under the user ID under which COPFILE was called, pathname2 is assigned default protection attributes, regardless of the protection attributes defined by the BASIC-ACL or GUARDS for pathname1. These default protection attributes are USER-ACCESS=OWNER-ONLY and ACCESS=WRITE for disk files, USER-ACCESS=ALL-USERS and ACCESS=WRITE for tape files.
When copying to tape, the retention period (EXDATE) can only accept values up to a difference of 32767 (for larger values the maximum value is assumed).
= *SAME-AND-CHANGE-DATE
This specification has the same effect as PROTECT=*SAME. In addition, the source file’s change date (CHANGE-DATE) is transferred to the target file.
The specification PROTECT=*SAME-AND-CHANGE-DATE is only still supported for reasons of compatibility. The CHDATE=*SAME operand should be used to transfer the change date of the source file.
REPLACE
The user can specify whether an existing output file pathname2 is to be overwritten.If pathname2 is a tape file or if it is empty, the operand is ignored and the “old” file is overwritten without output of a message.
= *YES
“pathname2” is overwritten without output of a message.
= *NO
“pathname2” is not overwritten. The call is rejected with the error code X'051A'.
Return codes
The error code is only returned in the standard header and no longer in general-purpose register 15 as with the COPY macro. If the parameter area is not accessible or shorter than the length of the standard header or if a setup error occurs, program termination is initiated via STXIT. The error codes are described in the DMAIDEM/DCOIDEM macros.
Standard header: ccbbaaaa
The following code relating to execution of the COPFILE macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | No error | |
X'01' | X'00' | X'0000' | Only in conjunction with check dialogs: the job was completely or partially withdrawn in interactive mode, i.e. at least one check dialog was answered with *NO. |
X'02' | X'00' | X'0000' | Only in conjunction with CHECK!=NO: an error has occurred, but continuation of the function was requested in an error dialog |
X'40' | X'0501' | Requested catalog not available | |
X'82' | X'0502' | Requested catalog in the rest state | |
X'40' | X'0503' | Incorrect information in the MRSCAT | |
X'82' | X'0504' | Error in catalog management system | |
X'40' | X'0505' | Computer communication error (MRS) | |
X'80' | X'0506' | Operation canceled because of master change | |
X'40' | X'0510' | Error while calling an internal function | |
X'40' | X'0512' | Requested catalog unknown | |
X'40' | X'051A' | File already exists | |
X'40' | X'051B' | User ID not known in specified pubset | |
X'40' | X'051C' | No access right to specified pubset | |
X'40' | X'051D' | LOGON password different on specified pubset | |
X'20' | X'0530' | Error in storage space request | |
X'20' | X'0531' | Unexpected catalog access error | |
X'40' | X'0533' | File not found | |
X'82' | X'0534' | Private volume cannot be allocated | |
X'40' | X'0535' | No access right to the file catalog entry (only in conjunction with CCS or NETCSS assignment on foreign user ID) | |
X'20' | X'053B' | System error during file access | |
X'82' | X'053C' | Catalog file of the pubset is full | |
X'40' | X'053D' | Catalog or F1 label block is destroyed | |
X'40' | X'053E' | File on private volume already cataloged | |
X'82' | X'053F' | File reserved by another task | |
X'01' | X'0576' | Contradictory operand combination or reserved fields of the parameter area used | |
X'20' | X'0577' | Internal error during access to job environment | |
X'82' | X'0594' | Not enough virtual memory available. This return code can also occur in particular in conjunction with a selection specification (wildcard) if too many files are selected | |
X'01' | X'0599' | Operand is not supported in the RFA-BS version | |
X'01' | X'05A7' | First file name incorrect | |
X'01' | X'05A9' | Second file name incorrect | |
X'20' | X'05C7' | Internal error in DMS | |
X'01' | X'05EE' | File name too long | |
X'01' | X'05F0' | Foreign user ID not permitted for file2 | |
X'01' | X'05F1' | Copying to the specified file not possible | |
X'01' | X'05F2' | Illegal specification of *DUMMY | |
X'40' | X'05F3' | First or second file protected | |
X'01' | X'05F4' | First and second file name are identical | |
X'20' | X'05F5' | Some blocks could not be copied | |
X'01' | X'05F6' | File cannot be copied | |
X'40' | X'05F9' | Incompatible attributes of source and target file | |
X'40' | X'05FC' | Specified user ID not in home pubset | |
X'40' | X'0610' | The function execution sent a return code for at least one of the selected file names | |
X'01' | X'0611' | Incorrect constructor specification (PATHNM2 operand in conjunction with wildcards) | |
X'40' | X'0666' | The file is write-protected by GUARDS (only in conjunction with CCS assignment on foreign user ID) | |
X'40' | X'0698' | File generation groups do not have the same attributes | |
X'40' | X'06B5' | File is not properly closed | |
X'40' | X'06B6' | Attributes of the file are not compatible with the file generation group | |
X'40' | X'06C4' | File generation group not yet cataloged | |
X'01' X'40' X'01' | X'06C7' X'06CC' X'06D7' | Invalid generation number specified only with selection specification (wildcard): no file matches the selection specification Generation group cannot be copied to an individual generation of this group | |
X'01' | X'06D8' | Generations of the specified group have different file characteristics | |
X'01' | X'06DE' | File or generation cannot be copied to a group | |
X'01' | X'06FD' | Parameter area invalid or not accessible | |
X'40' | X'06FF' | BCAM connection aborted | |
X'01' | X'FFFF' | Wrong function number in parameter area header | |
X'03' | X'FFFF' | Wrong version number in parameter area header |