Macro type: type S (E Form/M Form/L Form/C Form/D Form) (see "Macro types")
The DECFILE macro converts an encrypted file into an unencrypted file (see the ENCFILE macro on "ENCFILE - Convert unencrypted file into encrypted filen").
After DECFILE has run all encryption attributes (procedure and check string for crypto password) are deleted in the catalog entry.
File generations
DECFILE cannot be used for individual file generations but only for complete file generation groups. Within a file generation group, all generations with the exception of tape generations have the same encryption attributes as the group entry.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
PATHNAM
Specifies the file which is to be decrypted. The file’s crypto password must be contained in the crypto password table of the calling task.
=<c-string 1..54: filename 1..54>
Path name of the file.
=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the file’s path name is stored.
EQUATES
Specifies whether equates are also to be generated for the values of the parameter area fields when the parameter area is expanded.
= YES
Equates are also generated for the values of the parameter area fields when the parameter area is expanded.
= NO
No equates are generated for the values of the parameter area fields when the parameter area is expanded.
Example
: MVC DECFMFC(YMAD#),DECFMFL DECFILE MF=M,PREFIX=Y,PATHNAM='UMSATZ.3.QUARTAL.2004' DECFILE MF=E,PARAM=DECFMFC : DECFMFC DECFILE MF=C,PREFIX=Y DECFMFL DECFILE MF=L :
Programming notes
All RESERVED fields of the parameter area have to be deleted with binary zeros.
For all changes at parameter level that are not called with macros, the caller is responsible for the consistency of the parameter area.
For non-privileged calls (function state TU), register 1 points to the parameter area.
For the names listed in the parameter area, no conversion from small to capital letters is performed during the function execution. With the macro expansion, however, a conversion from small to capital letters is possible, depending on the compiler settings.
Notes on function execution
File locks and file protection attributes which forbid write access to the catalog entry or the content of a file thus also prevent conversion of the file using DECFILE.
Conversion of a file with DECFILE requires the calling task to have ownership rights for the file. Conversion therefore takes place when:
the file is under the user ID of the calling task.
the calling task is running under a user ID with TSOS privilege.
the user ID of the calling task is co-owner of the file and the file is not temporary.
Additional functions for tasks with TSOS privilege: If the calling task has TSOS privilege, the following additional functions are possible:
Temporary files which do not belong to the calling task but to another task can also be specified.
Temporary files can also be specified on a pubset other than the default pubset of the user ID. (These are not deleted automatically when the calling task terminates.)
Conversion of the encrypted file is logged with SAT.The AUDIT attribute output here is taken from the catalog entry of the file to be converted (see the CREATE-FILE command, AUDIT operand, in the “Commands” manual [3]).
RFA: DECFILE is rejected if the file to be converted can only be accessed via RFA.
Help file: When converting with DECFILE a help file is created and then automatically deleted when the function has been completed. The converted file content is written to the help file. The help file needs as much disk storage space as the file to be converted.The file name of the help file has the following format:
S.DMS.<tsn>.<date><time>.CRYPTO
Return codes
The return code is returned in the standard header of the parameter list. The standard header may not be located in the read-only area, otherwise the program is terminated.
Standard header: ccbbaaaa
The following code relating to execution of the DECFILE macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Explanation |
X'00' | X'00' | X'0000' | No error |
X'01' | X'0554' | Format of the file name not permitted | |
X'01' | X'0576' | a) Incorrect operand combination | |
X'20' | X'0578' | Internal error when checking the access rights | |
X'82' | X'0594' | Not enough virtual memory available | |
X'20' | X'05C7' | Internal error in DMS | |
X'01' | X'05CB' | Incorrect/inadmissible first file name | |
X'40' | X'05CF' | Password not in password table | |
X'40' | X'05FD' | File is write-protected | |
X'40' | X'0609' | Action not permitted for system file | |
X'40' | X'0666' | File protection prevents access | |
X'01' | X'00' | X'066B' | File is already decrypted |
X'00' | X'00' | X'066E' | Use help file |
X'01' | X'FFFF' | Wrong function number in standard header | |
X'03' | X'FFFF' | Wrong version number in standard header |