Appendix A - Technical Notes
This appendix provides additional technical information about working with Java and zFS in ChangeMan ZMF.
CMNHUTIL - zFS File Utility
CMNHUTIL is a utility program for processing zFS files in batch. It was developed to overcome limitations on path names and file names in z/OS JCL and in dynamic allocation. CMNHUTIL performs these functions:
-
Defines a new zFS file
-
Copies a single zFS file
-
Copies multiple zFS files
-
Writes text to a zFS file
-
Renames a zFS file
-
Deletes a zFS file Delete a zFS directory
CMNHUTIL Input
-
SYSIN records that specify zFS paths, directories, and files and the functions to be performed
-
Input zFS paths, directories, and files specified in SYSIN records
Output
-
Output zFS paths, directories, and files specified in SYSIN records
-
SYSPRINT report of SYSIN input and processing results
Sample JCL
The following is a sample job fragment showing a CMNHUTIL step.
//WRJ2TMP EXEC PGM=CMNHUTIL, copy source files to work files
// REGION=0M
//SYSPRINT DD DISP=(,PASS),DSN=&&LIST23,
// UNIT=SYSDA,SPACE=(133,(1000,1000),RLSE)
//SYSIN DD DATA,DLM='++'
CREATEDIRECTORIES=Y
FILEPERMISSIONS=777
FILE=/u/sert/C001/tmp/s6/D63flQV0loG/cmnJVS/jhfjav40.java
define
CREATEDIRECTORIES=Y
FILEPERMISSIONS=777
FILE=/u/sert/C001/tmp/s6/D63flQV0loG/cmngen/jhfjav40.class
DEFINE
CREATEDIRECTORIES=Y
FILEPERMISSIONS=777
FILE=/u/sert/C001/tmp/s6/D63flQV0loG/cmnlst/jhfjav40.list
DEFINE
CREATEDIRECTORIES=Y
FILEPERMISSIONS=777
FILEIN=/cmntp/s6/base/ACTP/stgedev/#000050/JVS/jhfjav40.java
FILEOUT=/u/sert/C001/tmp/s6/D63flQV0loG/cmnJVS/jhfjav40.java
COPY
++
DD Statements
This table describes DD statements for CMNHUTIL.
| DDNAME | I/O | Purpose |
|---|---|---|
| SYSIN | Input | Records that specify zFS paths, directories, and files and the functions to be performed IMPORTANT: Code an explicit delimiter ++ for SYSIN inline data. /* is acceptable in zFS path names, and it will cause truncation if the default in-line data delimiter /* is assumed. //SYSIN DD DATA,DLM='++' |
| SYSPRINT | Output | Report of SYSIN input and processing results |
| CMNSDFIL | Output | sidefile records for JAR ILIC use |
PARM Options
There are no execution parameters input to utility program CMNHUTIL with a PARM= parameter in the EXEC statement.
SYSIN Parameters
SYSIN records specify zFS paths, directories, and files and the functions to be performed.
There are two types of SYSIN records:
-
Keywords - SYSIN keyword statements specify input and output zFS paths, directories, and files. Keyword records also provide parameters and additional information for the function to be performed.
-
Verbs - Verb records specify what action is to be taken on the zFS paths, directories, and files specified in SYSIN keyword records.
CMNHUTIL SYSIN Keywords
Keyword statements consist of a keyword and a value. Example:
FILEPERMISSIONS=775
If a keyword is relevant to an operation and it is omitted, the default value for that keyword is assumed.
This table describes CMNHUTIL SYSIN keywords.
| SYSIN Keyword | Description |
|---|---|
| COMPRESS | Specifies whether output file should be compressed Valid values: Y/N Default: N |
| CREATEDIRECTORYS | Specifies whether new directory structures should be created Valid values: Y/N Default: N |
| DIRIN | Specifies input directory Valid values: A valid zFS path name Default: None |
| DIROUT | Specifies output directory Valid values: A valid zFS path name Default: None |
| FILE | Specify file for single file operations Valid values: A valid zFS file name Default: None |
| FILEAPP | Specify single output file for append operations Valid values: A valid zFS file name Default: None |
| FILEIN | Specify a single input file Valid values: A valid zFS file name Default: None |
| FILEOUT | Specify a single output file Valid values: A valid zFS file name Default: None |
| FILEPERMISSIONS | Specifies file permissions for output files Valid values: Valid Unix file permission string Default: 755 |
| INPUTCOMPRESSED | Specifies whether input data file is compressed Valid values: Y/N Default: N |
| PRESERVEMODDATE | Specifies whether file modification date should be preserved on copy operations Valid values: Y/N Default: N |
| REPLACE | Specifies whether files should be replaced in copy operations Valid values: Y/N Default: Y |
| SIDEFILE | Writes sidefile records to CMNSDFIL Valid values: Y/N Default: N |
| SUBDIRS | Specifies whether subdirectories should be processed Valid values: Y/N Default: N |
| TEXTIN | Identifies text for SETTEXT operation Valid values: Any text Default: None |
SYSIN Verbs
This table describes CMNHUTIL SYSIN verbs.
| SYSIN Verb | Description |
|---|---|
| COPY | Copy a single file |
| COPYALL | Copy multiple files |
| DEFINE | Define a new file |
| DELETEFILE | Delete a file |
| RENAMEFILE | Rename a file |
| RMDIR | Delete a directory |
| SETTEXT | Write text to file |
...
Valid SYSIN Keyword and Verb Combinations
Not every keyword is relevant to every verb. This table shows valid combinations of keywords and verbs.
| COPY | DEFINE | DELETEFILE | RENAMEFILE | SETTEXT | COPYALL | RMDIR | |
|---|---|---|---|---|---|---|---|
| FILE | X | X | |||||
| FILEIN | X | X | |||||
| FILEOUT | X | X | X | ||||
| FILEAPP | X | X | |||||
| DIRIN | X | X | |||||
| DIROUT | X | ||||||
| FILEPERMISSIONS | X | X | X | X | |||
| CREATEDIRECTORYS | X | X | X | X | |||
| SIDEFILE | X | X | |||||
| TEXTIN | X | ||||||
| SUBDIRS | X | X | |||||
| COMPRESS | X | X | |||||
| INPUTCOMPRESSED | X | X | |||||
| PRESERVEMODDATE | X | X | |||||
| REPLACE | X | X |
SYSIN Record Syntax Rules
Follow these rules when coding SYSIN keyword statement and verb records.
-
A CMNHUTIL operation is defined by one or more keyword statements followed by a verb.
-
Each keyword statement or verb is coded on a separate SYSIN record.
-
Keyword statements longer than 79 characters are continued by placing a non-blank character in position 80 and continuing the statement in the next SYSIN record, starting in position 1.
-
SYSIN may contain multiple keyword statement / verb sets. Operations are performed serially and are initiated as a verb is read.
Return Codes and Error Messages
Utility CMNHUTIL provides two return codes:
-
Internal return code displayed in SYSPRINT for each operation (verb), in format
verb RC:nnn
where nnn is the decimal value a for Unix System Services errno.
Non-zero internal return codes in SYSPRINT are preceded by an error message that explains the condition.
For the definition of an errno, see "Return Codes (Errnos) Listed by Value" in the z/OS UNIX System Services Messages and Codes.
-
External program return code that indicates the overall success or failure of the program. This is the RC and COND CODE listed in the job listing.
CMNHUTIL considers the internal USS errno in setting the external program return code, but a non-zero USS errno may not be fatal to the execution of CMNHUTIL.
This table describes external return codes for utility CMNHUTIL.
| Return Code | Description |
|---|---|
| 00 | Successful execution |
| 04 | A non-zero internal return code that is not considered fatal to the CMNHUTIL function being executed, or other non-fatal CMNHUTIL conditions. |
| 08 | Invalid SYSIN verb or keyword, invalid verb / keyword combination; nonzero internal return code that is considered fatal to the CMNHUTIL function being executed. |
Reporting
This is an example of the CMNHUTIL report printed at the SYSPRINT DD statement.
********************************************************************************
* DDNAME: WRJ2TMP.SYSPRINT *
********************************************************************************
CMNHUTIL (8.1.0 20141010 14.25) Started...
Keyword processed: CREATEDIRECTORIES Y
Keyword processed: FILEPERMISSIONS 777
Keyword processed: FILE /u/sert/C001/tmp/s6/D63flQV0loG/cmnJVS/jhfjav40.java
Mkdir:
Mkdir:
define RC: 0000
Keyword processed: CREATEDIRECTORIES Y
Keyword processed: FILEPERMISSIONS 777
Keyword processed: FILE /u/sert/C001/tmp/s6/D63flQV0loG/cmngen/jhfjav40.class
Mkdir:
DEFINE RC: 0000
Keyword processed: CREATEDIRECTORIES Y
Keyword processed: FILEPERMISSIONS 777
Keyword processed: FILE /u/sert/C001/tmp/s6/D63flQV0loG/cmnlst/jhfjav40.list
Mkdir:
DEFINE RC: 0000
Keyword processed: CREATEDIRECTORIES Y
Keyword processed: FILEPERMISSIONS 777
Keyword processed: FILEIN /cmntp/s6/base/ACTP/stgedev/#000050/JVS/jhfjav40.java
Keyword processed: FILEOUT /u/sert/C001/tmp/s6/D63flQV0loG/cmnJVS/jhfjav40.java
File: /cmntp/s6/base/ACTP/stgedev/#000050/JVS/jhfjav40.java copied to: /u/sert/C001/tmp/s6/D63flQV0loG/cmnJVS/jhfjav40.ja
va
COPY RC: 0000
CMNHUTIL Examples:
-
Copy a single file
//CMNHUTIL EXEC PGM=CMNHUTIL //SYSPRINT DD SYSOUT=* //SYSIN DD DATA,DLM='++' FILEIN=/u/username/test.txt FILEOUT=/u/username/backup.txt COPY ++ -
Copy an entire directory
//CMNHUTIL EXEC PGM=CMNHUTIL //SYSPRINT DD SYSOUT=* //SYSIN DD DATA,DLM='++' DIRIN=/u/username/ DIROUT=/u/usernamebackup/ FILEPERMISSIONS=777 CREATEDIRECTORIES=Y SUBDIRS=Y COPYALL ++