Define file name prefix
Component: | ACS |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Function
The SET-FILE-NAME-PREFIX command is used to define a prefix for file or job variable names. This allows the user to effectively switch to a “subcatalog” of the user ID within the task since ACS inserts the defined prefix before all file or job variable names which are specified by the user without a user ID in commands or macro calls. Prefix insertion is not performed if there is already an alias definition for the specified file or job variable name since alias substitutions are given precedence in such cases.
If a prefix already exists and was not defined with the PROTECTED attribute, the existing prefix is overwritten. The user can have the defined prefix displayed by means of the SHOW-FILE-NAME-PREFIX command.
Prefix insertion rules
No prefix is inserted if the file or job variable name contains a foreign user ID.
If the file or job variable name contains the user’s own user ID and no catalog ID, the prefix is inserted, but only if it consists of just a catalog ID. Furthermore, there must not be any RFA connection for the catalog ID.
File or job variable names with the user ID TSOS are excluded (i.e. not supplemented by the insertion of a prefix).
If the file or job variable name and the prefix contain a catalog ID, the prefix is not inserted.
If the file or job variable name contains a catalog ID but not a user ID, the prefix is inserted immediately after the catalog ID.
If the file or job variable name becomes too long after inserting the prefix, the file name is rejected as invalid.
If the file name already begins with the defined prefix, the prefix is inserted, but only if multiple insertions are permitted (see the DUPLICATE-PREFIX operand).
The file or job variable name must comply with naming conventions even if a prefix is added to it later.
Format
SET-FILE-NAME-PREFIX | Alias: STFNP |
PREFIX = *JOB-NAME / <partial-filename 2..53> / *NONE ,DUPLICATE-PREFIX = *YES / *NO ,ATTRIBUTES = *STD / *PROTECTED ,RANGE = *STD / *FILE / *JV / *BOTH | |
Operands
PREFIX = *JOB-NAME / <partial-filename 2..53> / *NONE
New prefix for file or job variable names (followed by a period).
PREFIX = *JOB-NAME
Defines the job name of the task (followed by a period) as the new prefix. If no job name was defined, this specification is equivalent to PREFIX=*NONE.
PREFIX = <partial-filename 2..53>
Explicit specification of the prefix. The specified prefix may contain both a user ID and a catalog ID. If a catalog ID is specified, there must not be any existing RFA connection for it.
PREFIX = *NONE
No prefix is to be inserted, but an existing prefix definition is to be removed.
DUPLICATE-PREFIX = *YES / *NO
Specifies whether the prefix is to be inserted even if the file name already begins with the same prefix.
ATTRIBUTES = *STD / *PROTECTED
Specifies whether the defined prefix is to be protected from being overwritten by a new definition. The default value is *STD, which means that the prefix can be overwritten by a new prefix definition.
RANGE = *STD / *FILE / *JV / *BOTH
Determines the range of the prefix definition. Insertion of the prefix can be defined for files and/or job variables.
RANGE = *STD
Default: The prefix is inserted with the ACS setting applicable for the task (ACS option STANDARD-RANGE).
RANGE = *FILE
The prefix is inserted only for files.
RANGE = *JV
The prefix is inserted only for job variables.
RANGE = *BOTH
The prefix is inserted both for files and for job variables.
Return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
|---|---|---|---|
0 | CMD0001 | Command executed normally | |
64 | ACS0016 | Prefix is protected | |
128 | ACS0018 | ACS is not available | |
130 | ACS0036 | Resource bottleneck |
Examples
Example 1: Defining a prefix, studying the effects of its insertion, and logging the insertion
/show-file-attr file. ————————————————————————————————— (1)
% 9 :2OS2:$USER1.FILE.1 % 9 :2OS2:$USER1.FILE.2 %:2OS2: PUBLIC: 2 FILES RES= 18 FRE= 4 REL= 0 PAGES
/show-file-attr paul. ———————————————————————————————— (2)
% 9 :2OS2:$USER1.PAUL.FILE.1 % 9 :2OS2:$USER1.PAUL.FILE.2 % 9 :2OS2:$USER1.PAUL.FILE.3 %:2OS2: PUBLIC: 3 FILES RES= 27 FRE= 8 REL= 3 PAGES
/set-file-name-prefix prefix=paul. ————————————————————————— (3)
% ACS0048 CURRENT FILE NAME PREFIX IS 'PAUL.'. PREFIX IS USED FOR FILES AND JOBVARIBLES.
/show-file-name-prefix ————————————————————————————— (4)
% ACS0048 CURRENT FILE NAME PREFIX IS 'PAUL.'. PREFIX IS USED FOR FILES AND JOBVARIBLES.
/show-file-attr file. —————————————————————————————— (5)
% 9 :2OS2:$USER1.PAUL.FILE.1 % 9 :2OS2:$USER1.PAUL.FILE.2 % 9 :2OS2:$USER1.PAUL.FILE.3 %:2OS2: PUBLIC: 3 FILES RES= 27 FRE= 8 REL= 3 PAGES
/print-doc file.1 ——————————————————————————————— (6)
% SCP0810 SPOOLOUT FOR FILE ':2OS2:$USER01.PAUL.FILE.1' ACCEPTED. TSN: ' 196D', SPOOLOUT-NAME: 'ULK', MONJV: '*NONE' % SCP1025 PRINT JOB ACCEPTED BY SERVER 'D020H027' WITH TSN '46UH'
/copy-file from=file.1,to=file.3 —————————————————————————————————— (7)
/show-file-attr file. ——————————————————————————————————— (8)
% 9 :2OS2:$USER1.PAUL.FILE.1 % 9 :2OS2:$USER1.PAUL.FILE.2 % 9 :2OS2:$USER1.PAUL.FILE.3 %:2OS2: PUBLIC: 3 FILES RES= 27 FRE= 6 REL= 0 PAGES
/show-file-attr $user1.file. —————————————————————————— (9)
% 9 :2OS2:$USER1.FILE.1 % 9 :2OS2:$USER1.FILE.2 %:2OS2: PUBLIC: 2 FILES RES= 18 FRE= 4 REL= 0 PAGES
/show-acs-opt ——————————————————————————————— (10)
% ALIAS CATALOG SYSTEM V20.0 % ============================= % % STATUS: INACTIVE % % LOGGING: ALIAS-SUBSTITUTION=STD, PREFIX-INSERTION=YES % SUCCESS-MSG OPTIONS: USER-FILE=YES, SYSTEM-FILE=YES % COMPLETE-ALIAS-NAMES=NOT-ALLOWED (USER-MODIF=NOT-ALLOWED) % ALIAS-USERID =ALLOWED (USER-MODIF=ALLOWED ) % STANDARD-RANGE=BOTH
/mod-acs-opt log=(prefix-insert=*yes) ————————————————————————————————— (11)
/show-file-attr file —————————————————————————————————— (12)
% ACS0000 FILE NAME 'FILE.' REPLACED BY 'PAUL.FILE.' % 9 :2OS2:$USER1.PAUL.FILE.1 % 9 :2OS2:$USER1.PAUL.FILE.2 % 9 :2OS2:$USER1.PAUL.FILE.3 %:2OS2: PUBLIC: 3 FILES RES= 27 FRE= 6 REL= 0 PAGES
/copy-file from=file.1,to=file.3 —————————————————————————————————— (13)
% ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3' % ACS0000 FILE NAME 'FILE.3' REPLACED BY 'PAUL.FILE.3'
/print-doc file.1 ————————————————————————————————————————————————— (14)
% ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % SCP0810 SPOOLOUT FOR FILE ':2OS2:$USER01.PAUL.FILE.1' ACCEPTED. TSN: ' 196N', SPOOLOUT-NAME: 'ULK', MONJV: '*NONE' % SCP1025 PRINT JOB ACCEPTED BY SERVER 'D020H027' WITH TSN '46UW'
(1) | Shows all catalog entries for files that have names beginning with FILE. |
(2) | Shows all catalog entries for files that have names beginning with PAUL.. |
(3) | The SET-FILE-NAME-PREFIX command sets the prefix insertion function for the prefix PAUL. |
(4) | The SHOW-FILE-NAME-PREFIX command indicates the defined prefix. |
(5) | The name FILE. specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed. Consequently, the catalog entries of all files that have names beginning with PAUL.FILE. are shown. |
(6) | The name FILE.1 specified in the PRINT-DOCUMENT command has the defined prefix inserted before the command is executed. The file named PAUL.FILE.1 is printed as a result. |
(7) | The names FILE.1 and FILE.3 which are specified in the COPY-FILE command have the defined prefix inserted before the command is executed. The contents of the file PAUL.FILE.1 are thus copied to the file PAUL.FILE.3. |
(8) | The name FILE. specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed. Consequently, the catalog entries of all files that have names beginning with PAUL.FILE. are shown. |
(9) | The insertion of a prefix is prevented by specifying the user USER1 before FILE.. The output of the SHOW-FILE-ATTRIBUTES now shows all files that have names beginning with FILE.. A file named FILE.3 was not created with COPY-FILE (see also step 8). |
(10) | The prefix insertion function can be disabled by specifying the catalog ID or the catalog and user IDs. |
(11) | Shows the current ACS settings for the task. |
(12) | The MODIFY-ACS-OPTIONS command is used to change the ACS settings. Prefix insertions are to be logged on SYSOUT. The name FILE. specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed. Consequently, the catalog entries of all files that have names beginning with PAUL.FILE. are shown. The insertion of the prefix is indicated by message ACS0000. |
(13) | The names FILE.1 and FILE.3 which are specified in the COPY-FILE command have the defined prefix inserted before the command is executed. The contents of the file PAUL.FILE.1 are thus copied to the file PAUL.FILE.3.The insertion of the prefix is indicated by message ACS0000. When the file is processed internally, several catalog accesses may be required. ACS inserts the prefix before the file name whenever the catalog is accessed, so message ACS0000 is output in each such case. |
(14) | The name FILE.1 specified in the PRINT-DOCUMENT command has the defined prefix inserted before the command is executed. The file named PAUL.FILE.1 is printed as a result. The insertion of the prefix is indicated by message ACS0000. |
Example 2: Preventing duplicate insertions and protecting defined prefixes
/set-f-name-pre paul.,attr=*protect ——————————————————————————————— (1)
% ACS0048 CURRENT FILE NAME PREFIX IS 'PAUL.'. PREFIX IS USED FOR FILES AND JOBVARIBLES.
/cre-file paul.test.1 —————————————————————————————————————— (2)
% ACS0000 FILE NAME 'PAUL.TEST.1' REPLACED BY 'PAUL.PAUL.TEST.1' % ACS0000 FILE NAME 'PAUL.TEST.1' REPLACED BY 'PAUL.PAUL.TEST.1'
/show-file-attr paul. ————————————————————————————————————— (3)
% ACS0000 FILE NAME 'PAUL.' REPLACED BY 'PAUL.PAUL.' % 3 :2OS2:$USER1.PAUL.PAUL.TEST.1 %:2OS2: PUBLIC: 1 FILE RES= 3 FRE= 3 REL= 3 PAGES
/show-file-attr *<1,2> ———————————————————————————————————— (4)
% ACS0000 FILE NAME '*<1,2>' REPLACED BY 'PAUL.*<1,2>' % 3 :2OS2:$USER1.PAUL.PAUL.TEST.1 %:2OS2: PUBLIC: 1 FILE RES= 3 FRE= 3 REL= 3 PAGES
/set-f-name-pre paul.,duplicate=no,attr=protect —————————————————————— (5)
% ACS0048 CURRENT FILE NAME PREFIX IS 'PAUL.'. PREFIX IS USED FOR FILES AND JOBVARIBLES.
/cre-file paul.test.1 ——————————————————————————————————— (6)
/show-file-attr test. —————————————————————————————————— (7)
% ACS0000 FILE NAME 'TEST.' REPLACED BY 'PAUL.TEST.' % 3 :2OS2:$USER1.PAUL.TEST.1 %:2OS2: PUBLIC: 1 FILE RES= 3 FRE= 3 REL= 3 PAGES
/set-file-name-pre ————————————————————————————————————— (8)
% ACS0016 CURRENT FILE NAME PREFIX PROTECTED. COMMAND REJECTED
/set-file-name-pre paul. ———————————————————————————————————— (9)
% ACS0048 CURRENT FILE NAME PREFIX IS 'PAUL.'. PREFIX IS USED FOR FILES AND JOBVARIBLES.
/set-file-name-pre ———————————————————————————————————— (10)
% ACS0019 CURRENT FILE NAME PREFIX IS 'ULK.'
/cre-file test.1 —————————————————————————————————————— (11)
% ACS0000 FILE NAME 'TEST.1' REPLACED BY 'ULK.TEST.1' % ACS0000 FILE NAME 'TEST.1' REPLACED BY 'ULK.TEST.1'
/show-file-attr test. ———————————————————————————————————— (12)
% ACS0000 FILE NAME 'TEST.' REPLACED BY 'ULK.TEST.' % 3 :2OS2:$USER1.ULK.TEST.1 %:2OS2: PUBLIC: 1 FILE RES= 3 FRE= 3 REL= 3 PAGES
/set-file-name-pre *none ——————————————————————————————————— (13)
% ACS0019 CURRENT FILE NAME PREFIX IS '*NONE'
/cre-file test.1 —————————————————————————————————————————————— (14)
/show-file-attr test.1 —————————————————————————————————————————————— (15)
% 3 :2OS2:$USER1.TEST.1 %:2OS2: PUBLIC: 1 FILE RES= 3 FRE= 3 REL= 3 PAGES
/show-file-attr **test.1 ——————————————————————————————————— (16)
% 3 :2OS2:$USER1.ULK.TEST.1 % 3 :2OS2:$USER1.PAUL.PAUL.TEST.1 % 3 :2OS2:$USER1.PAUL.TEST.1 % 3 :2OS2:$USER1.TEST.1 %:2OS2: PUBLIC: 4 FILES RES= 12 FRE= 12 REL= 12 PAGES
In this example, all prefix insertions are reported (see example 1, step 11).
(1) | The SET-FILE-NAME-PREFIX command is used to define the prefix insertion function for the prefix PAUL.. The definition is protected against overwriting by means of the PROTECTED attribute. |
(2) | The name PAUL.TEST.1 specified in the CREATE-FILE command has the defined prefix inserted before the command is executed, so a catalog entry for the file PAUL.PAUL.TEST.1 is created. This approach is defined implicitly in the SET-FILE-NAME-PREFIX command (by the default value |
(3) | The name PAUL. specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed. Consequently, the catalog entries of all files that have names beginning with PAUL.PAUL. are shown. |
(4) | The wildcard sequence *<1,2> that is specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed. As a result, the catalog entries of all files that have names beginning with PAUL. and ending with the number 1 or 2 are shown. The rest of the name may be made up of any characters (even the null string). See also message ACS0000. |
(5) | The command SET-FILE-NAME-PREFIX defines prefix insertion for the prefix PAUL. (the previous prefix). The prefix definition is protected against overwriting by the PROTECTED attribute, and duplicate insertions are prevented with |
(6) | The name PAUL.FILE. specified in the CREATE-FILE command does not receive the defined prefix, since it already begins with the same prefix (see also Point 2). A catalog entry for the file PAUL.TEST.1 is created. |
(7) | The name TEST. specified in the SHOW-FILE-ATTRIBUTES command has the defined prefix inserted before the command is executed, so the catalog entries for all files that have names beginning with PAUL.TEST. are shown. The user could also specify PAUL.TEST. to achieve the same result, since the prefix would already be present in that case and would therefore not be inserted. |
(8) | The command SET-FILE-NAME-PREFIX is issued without operands. This would have normally defined the job name of the task as the new prefix (default value); however, since the prefix has the PROTECTED attribute (to prevent inadvertent changes), no other prefix can be defined in this case. |
(9) | The command SET-FILE-NAME-PREFIX is issued for the existing prefix PAUL. without any further operands. The settings for DUPLICATE-PREFIX and ATTRIBUTES are restored to default values, i.e. the prefix is no longer protected against changes. |
(10) | The SET-FILE-NAME-PREFIX command is issued without operands, so the job name of the task is defined as the prefix. The new prefix is ULK. (see message ACS0000). |
(11) | The name TEST.1 specified in the CREATE-FILE command receives the defined prefix before the command is executed. A catalog entry is created for the file ULK.TEST.1. |
(12) | The name TEST. specified in the CREATE-FILE command receives the defined prefix before the command is executed, so the catalog entries for all files that have names beginning with ULK.TEST. are shown. |
(13) | The SET-FILE-NAME-PREFIX command with the PREFIX=*NONE specification turns off the prefix insertion function. |
(14) | The CREATE-FILE command for the name TEST.1 creates a catalog entry for the file TEST.1. |
(15) | The SHOW-FILE-ATTRIBUTES command for the file name TEST.1 shows the catalog entry that was created. |
(16) | The SHOW-FILE-ATTRIBUTES command shows the catalog entries of all files that have names beginning with any arbitrary string (including the null string) and ending with TEST.1. |
Example 3: Preventing prefix insertion for a file name
/show-file-name-prefix ————————————————————————————————————— (1)
% ACS0019 CURRENT FILE NAME PREFIX IS 'PAUL.'
/add-alias-cat alias=file.1,file=*same ——————————————————————————————— (2)
% ACS0020 ALIAS CATALOG ACTIVATED
/show-alias —————————————————————————————————————————— (3)
% ALIAS FILE NAME -> FILE NAME %UB : FILE.1 -> *SAME % ACS0037 NUMBER OF ALIAS CATALOG ENTRIES: 1 (FOR SYSTEM: 0, FOR USER: 1)
/print-doc file.1 ———————————————————————————————————————— (4)
% SCP0810 SPOOLOUT FOR FILE ':2OS2:$USER1.FILE.1' ACCEPTED. TSN: '1Q14', SPO OLOUT-NAME: 'ULK', MONJV: '*NONE'
/hold-alias —————————————————————————————————————————— (5)
% ACS0007 /HOLD-ALIAS-SUBSTITUTION PROCESSED
/print-doc file.1 ———————————————————————————————————————— (6)
% ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % ACS0000 FILE NAME 'FILE.1' REPLACED BY 'PAUL.FILE.1' % SCP0810 SPOOLOUT FOR FILE ':2OS2:$USER01.PAUL.FILE.1' ACCEPTED. TSN: ' 197A', SPOOLOUT-NAME: 'ULK', MONJV: '*NONE' % SCP1025 PRINT JOB ACCEPTED BY SERVER 'D020H027' WITH TSN '46VE'
/resume-alias ————————————————————————————————————————— (7)
% ACS0008 /RESUME-ALIAS-SUBSTITUTION PROCESSED % ACS0009 ALIAS CATALOG OPERATION CONTINUES
In this example, all prefix insertions are reported (see example 1, step 11).
(1) | The command SHOW-FILE-NAME-PREFIX shows that PAUL. is defined as the prefix. |
(2) | The command ADD-ALIAS-CATALOG starts the ACS substitution function and creates the first entry in the task-local alias catalog with the alias FILE.1 for a file with the same actual file name (FILE-NAME=*SAME). This entry ensures that the name FILE.1 is neither replaced nor supplemented by the defined prefix. |
(3) | Output of the entries in the alias catalog. |
(4) | The file FILE.1 is specified in the PRINT-DOCUMENT command and printed as a result. |
(5) | The command HOLD-ALIAS-SUBSTITUTION halts the ACS substitution function. |
(6) | When FILE.1 is now specified in the PRINT-DOCUMENT command, the file PAUL.FILE.1 is printed. The prefix was inserted before executing the command in this case, since the ACS substitution function has been halted, and the alias definition for FILE.1 is ignored. |
(7) | The command RESUME-ALIAS-SUBSTITUTION resumes the ACS substitution function, so the alias definition now has precedence over the insertion of a prefix. |