Output file attributes from TFT
Component: | BS2000 |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Function
The SHOW-FILE-LINK command enables the user to request information from the job-specific task file table (TFT) about the files and devices currently being used. For tape files, TST information can be requested (see the VOLUME operand). TFT entries can be created using the ADD-FILE-LINK command.
If the user specifies no operands in the SHOW-FILE-LINK command, he/she will receive on SYSOUT a list of the current TFT entries showing the file link names and the associated file names, sorted by the file link names.
With the operands FILE-NAME and LINK-NAME the output can be restricted to information on specific TFT entries; otherwise, the command will process the entire TFT.
The command supports structured output in S variables (see "Output in S variables").
Note
The information as to whether the creation and/or processing of large files is permitted in the TFT entry (see the EXCEED-32GB operand in the ADD-FILE-LINK command), can only be determined from the S variable output.
Format
SHOW-FILE-LINK | Alias: SHFL | ||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
LINK-NAME = *ALL / *BLANK(...) / <filename 1..8 without-gen with-wild(80)>
The file link name of the TFT entry to which the SHOW-FILE-LINK command relates. The information returned will be restricted to the TFT entry identified by LINK-NAME.
LINK-NAME = *ALL
All the entries created by the job currently running will be output.
LINK-NAME = *BLANK(...)
Outputs details of a TFT entry whose name consists of blanks (C’'BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK'’). Such an entry is created if neither the link name nor the file name is defined in the FCB macro call of a program and if no appropriate ADD-FILE-LINK command is issued before the program call. The file name in this entry is the symbolic name of the FCB macro call.
See “OPEN processing” in the “DMS Macros” manual [12].
NUMBER = 0 / <integer 0..255>
Specifies the TFT entry, whose link name consists of blanks, for which information is to be shown.
LINK-NAME = <filename 1..8 without-gen with-wild(80)>
The file link name of the TFT entry to which the SHOW-FILE-LINK command relates.
A wildcard sequence (of up to 8 characters) may be specified to ensure that only valid file link names are addressed.
FILE-NAME = *ALL / *DUMMY / <filename 1..54 with-wild(80)>
Only information on the TFT entry linked to FILE-NAME will be output. The file specified by FILE-NAME identifies a permanent or temporary file, or a file generation. File generations must be fully qualified and specified with the absolute generation number. For temporary files, the internal file name is shown in the SHOW-FILE-LINK output.
FILE-NAME = *ALL
All the entries created by the job currently running will be output.
FILE-NAME = *DUMMY
Only the information on TFT entries linked with DUMMY files will be output.
FILE-NAME = <filename 1..54 with-wild(80)>
Fully or partially qualified file name, optionally containing wildcards. Only information on the TFT entry linked to FILE-NAME will be output. A wildcard sequence may be specified to ensure that only valid file names are addressed.
INFORMATION = *NAMES-AND-FILES / *ALL / *PARAMETERS(...)
The scope of the information to be output (*NAMES-AND-FILES: file name and link name; *ALL: all information; *PARAMETERS: files with the specified attributes).
INFORMATION = *NAMES-AND-FILES
Only the file link names and associated file names will be output.
Output format
The header line is only output once for all selected TFT entries.
For files on public disks:
%-- LINK-NAME --------- FILE-NAME ---------------------------------------- % linkname pfadname
For files on private disks:
%-- LINK-NAME --------- FILE-NAME ---------------------------------------- %D linkname pfadname
For files on a Net-Storage volume:
%-- LINK-NAME --------- FILE-NAME ---------------------------------------- %N linkname pfadname
For files on tape:
%-- LINK-NAME --------- FILE-NAME ---------------------------------------- %T linkname pfadname
For files on a remote system (see the “RFA” manual [31]):
%-- LINK-NAME --------- FILE-NAME ---------------------------------------- %R linkname pfadname (wie im ADD-FILE-LINK angegeben)
INFORMATION = *ALL
In addition to the file link name and file name, all the information specified by *PARAMETERS will be output. For each selected TFT entry, a header line is output along with file link name and file name (see INFORMATION=*NAMES-AND-FILES).
INFORMATION = *PARAMETERS(...)
Outputs the file link name and file name. In addition, the following extracts can be selected from the complete information held in the entries: file status, file backup, file attributes, and device characteristics. For each selected TFT entry, a header line is output along with file link name and file name (see INFORMATION=*NAMES-AND-FILES).
STATUS = *NO / *YES
Specifies whether any information about the status of the file links is required.
STATUS = *NO
No information will be output about the status of the file links.
STATUS = *YES
Information will be output about the status of the file links (whether the file is being processed; whether the link name is locked; actions to be carried out when the lock is removed; how the file link was created; number of tape devices assigned). For information contained in the STATUS block, see "Meaning of the output fields".
PROTECTION = *NO / *YES
Specifies whether information concerning the file protection and expiration date is to be output.
PROTECTION = *NO
No information on the file protection and expiration date are to be output.
PROTECTION = *YES
Information on the file protection and retention period are to be output.
For information contained in the PROTECTION block, see "Meaning of the output fields".
FILE-CONTROL-BLOCK = *NO / *YES
Specifies whether information on file attributes defined by the ADD-FILE-LINK command is to be output.
FILE-CONTROL-BLOCK = *NO
No information on file attributes will be output.
FILE-CONTROL-BLOCK = *YES
The following information on file attributes is displayed. This information is subdivided into four information blocks:
GENERAL ATTRIBUTES with general attributes from the FCB
DISK FILE ATTRIBUTES with attributes for disk files
TAPE FILE ATTRIBUTES with attributes for tape files
ISAM FILE ATTRIBUTES with attributes for ISAM files
Each of the four information blocks begins with a header line.
The details contained in the individual information blocks of FILE-CONTROL-BLOCK are listed under "Meaning of the output fields".
VOLUME = *NO / *YES
Specifies whether information on device types and volumes required for the file is to be output.
VOLUME = *NO
No information on device types and volumes required for the file will be output.
VOLUME = *YES
Information on device types and volumes required for the file will be output.
For information contained in the VOLUME block, see “Meaning of the output fields” on "Meaning of the output fields".
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | 0 | CMD0001 | Command executed |
1 | 0 | CMD0001 | Interrupted by K2 key |
1 | CMD0202 | Syntactical or semantic error in command | |
32 | CMD2009 | Internal error during S variable generation | |
32 | DMS0584 | A state that does not allow the function to continue was reported during processing | |
32 | DMS05C7 | Unexpected internal error in DMS | |
64 | DMS05E1 | TFT not available or specified file not in TFT | |
64 | OPS0001 | SDF-P reporting space problems | |
64 | OPS0002 | Interrupt (e.g. by K2 key) during S variable generation | |
130 | DMS0594 | Not enough virtual memory available |
Meaning of the output fields
n: | numeric character |
a: | alphanumeric character |
Status of the file links
The information block begins with the header line “STATUS”.
Output field | Values | Description |
|---|---|---|
STATE | ACTIVE | File is being processed |
INACTIVE | File is not being processed | |
ORIGIN | FILE | TFT entry was created by an ADD-FILE-LINK command or a FILE macro |
OPEN | TFT entry was created with OPEN | |
LOCK-F-LI | YES | Only included in the output if the link name was locked with LOCK-FILE-LINK |
REM-F-LINK | YES/NO | Only included in the output if a locked link name is to be released with REMOVE-FILE-LINK |
RELE-DEV | YES/NO | Only included in the output if a locked link name is to be released with REMOVE-FILE-LINK ..., RELEASE-DEVICE=*YES*/NO |
UNL-R-TAPE | YES/NO | Only included in the output if a locked link name is to be released with REMOVE-FILE-LINK ..., UNLOAD-RELEASED-TAPE=*YES/*NO |
NUMBER OF TAPES CONTAINING DATA OF FILE | nnn | Only output for tape files. |
File protection and retention period
The information block begins with the header line “PROTECTION”.
Output field | Values | Description |
|---|---|---|
RET-PER | *BY-PROG | No retention period for the file exists Retention period in days. |
PROT-LEV | *BY-PROG | Protection level not specified |
HIGH | For standard labels, high protection level for label checking | |
LOW | For standard labels, low protection level for label checking | |
OVERW-PROT | Only output if PROT-LEV = *HIGH/*LOW | |
YES | File protected against overwriting | |
NO | No protection against overwriting | |
BYPASS | *BY-PROG | Label processing not specified |
NO | No label processing; tape position will not be changed | |
ABS(nnnnn) | No label processing; the tape will be positioned to the specified tape mark, counting from the beginning of the tape | |
FORW(nnnnn) | No label processing; the tape will be advanced by the specified number of tape marks | |
BACK(nnnnn) | No label processing; the tape will be wound back by the specified number of tape marks | |
DESTROY | *BY-CAT | Deletion to end of tape not specified |
YES | After EOF/EOV labels are written, the remaining data to the end of the tape will be deleted | |
NO | Deletion to end of tape not specified |
File attributes
The values *BY-CAT and *BY-PROG have been omitted in the following table. *BY-PROG may be assumed for all the output fields except F-CL-MSG; it indicates that no value was specified for the corresponding operand. The value *BY-CAT means that the appropriate attribute is taken from the catalog entry of the file (see* the relevant operands in the ADD-FILE-LINK command with operand value *BY-CATALOG). The use of values entered in the catalog can be defined for the following attributes:
ACC-METH, REC-FORM, REC-SIZE, BUF-LEN, BLOCK-OFF, KEY-POS, KEY-LEN, LOGIC-FLAG, VAL-FLAG, PROPA-VAL, CODE, F-SEQ, BLK-CONTR, IO(PERF), IO(USAGE)
More detailed explanations will be found in the descriptions of the corresponding operands for the ADD-FILE-LINK command.
The information supplied here is divided into four information blocks:
GENERAL ATTRIBUTES with general attributes from the FCB
DISK FILE ATTRIBUTES with attributes for disk files
TAPE FILE ATTRIBUTES with attributes for tape files
ISAM FILE ATTRIBUTES with attributes for ISAM files
The information block begins with the header line “FILE CONTROL BLOCK - GENERAL ATTRIBUTES”
Output field
Values
Description
ACC-METH
SAM
ISAM
BTAM
UPAMAccess methods (see the ACCESS-METHOD operand in the ADD-FILE-LINK command)
OPEN-MODE
INPUT
OUTPUT
EXTEND
REVERSE
UPDATE
OUTIN
INOUT
SINOUTOPEN modes (see the OPEN-MODE operand in the ADD-FILE-LINK command)
REC-FORM
FIXED
File consists of fixed-length records
VARIABLE
File consists of variable-length records
UNDEFINED
File consists of records of undefined length
REC-SIZE
nnnnn
Record length in bytes
BUF-LEN
(STD,n)
Standard blocking with blocking factor n
nnnnn
Block length in bytes
BLK-CONTR
NO
Data format includes no key
DATA
Data format includes no key, block control information is at the start of the block
DATA (2K)
For NK2-ISAM files only: data format without key; block control information at the start of each 2K block
DATA (4K)
For NK4-ISAM files only: data format without key; block control information at the start of each 4K block
PAMKEY
Data format includes a PAM key
F-CL-MSG
STD
Default setting
YES
Close message after CLOSE
NO
No close message after CLOSE
CLOSE-MODE
Specification for CLOSE mode:
INVALIDATE
Blocks still in the cache are invalidated
REWIND
Tape rewound to start of tape after CLOSE
REPOS
Tape repositioned to logical start of file after CLOSE
UNLOAD
Like REWIND, but tape is also unloaded and released
LEAVE
Tape repositioned to logical end of file after CLOSE
KEEP
Blocks still in the cache remain valid
Table 110: Output fields for file attributesThe information block begins with the header line “FILE CONTROL BLOCK - DISK FILE ATTRIBUTES”
Output field
Values
Description
SHARED-UPD
YES
The file can be concurrently processed by more than one job
NO
No concurrent processing
WEAK
For UPAM processing only: the file can be opened for writing by one job only; other jobs can open it for reading at the same time
WR-CHECK
YES
Read-after-write checking
NO
No read-after-write checking
IO(PERF)
STD
No special performance requirements
HIGH
The file should be processed via a cache
VERY-HIGH
The file should be processed via a cache, and the entire file should be retained in the cache if possible
USER-MAX
The file is processed with the highest permitted performance attribute that is entered in the user catalog
IO(USAGE)
RDWRT
The performance requirements given in IO(PERF) are for read and write operations
READ
The performance requirements given in IO(PERF) are for read operations only
WRITE
The performance requirements given in IO(PERF) are for write operations only
LOCK-ENV
HOST-SYS
The file cannot be opened for writing concurrently from different systems
XCS
The file can be opened for writing concurrently from different systems in an XCS network
Table 111: Output fields for disk file attributesThe information block begins with the header line “FILE CONTROL BLOCK - TAPE FILE ATTRIBUTES”
Output field
Values
Description
LABEL
NO
No label processing
STD Standard labels NON-STD
Tape file with nonstandard labels
DIN-R-NUM
n
Interchange level for DIN 66029, which regulates how the labels of the file are created
TAPE-MARK
YES
Tape marks will be written
CODE
EBCDIC
No code conversion required
ISO7
EBCDIC ↔ ISO7 conversion with international table
ISO7D
EBCDIC ↔ ISO7 conversion with German table
OWN
Code conversion using tables created by the use
EBCDIC-TR
YES
ISO7 or OWN codes will be converted to EBCDIC
NO
ISO7 code will be converted to 8 bit format with a leading zero
F-SEQ
nnnnn
Sequence number of file in file set
UNKNOWN Starting position of file unknown NEW New file at the end of the file set CP-AT-BLIM
YES
Checkpoint automatically written when block limit is reached
CP-AT-FEOV YES Checkpoint automatically written at every FEOV macro call BLOCK-LIM nnnnn Maximum nnnnnn data blocks per tape REST-USAGE
DUMMY
File will be treated as a DUMMY file when a restart is carried out
BLOCK-OFF
nnn
Length of buffer offset (see BLOCK-OFFSET operand in the ADD-FILE-LINK command)
BY-HDR2 Buffer offset determined by the HDR2 label for the file, or the default value TAPE-WRITE STREAM
DEV-BUFFER
Buffered output to tape cartridge
IMMEDIATE Immediate output to tape cartridge
YES Streaming mode I/O Table 112: Output fields for tape file attributesThe information block begins with the header line “FILE CONTROL BLOCK - ISAM FILE ATTRIBUTES”
Output field
Values
Description
KEY-POS
nnnnn
position of ISAM key
KEY-LEN
nnn
Length of the ISAM key in bytes.
POOL-LINK
aaaaaaaa
ISAM pool link name
LOGIC-FLAG
nnn
Length of a logical flag in the ISAM index, in bytes
VAL-FLAG
nnn
Length of a value flag in the ISAM index, in bytes
PROPA-VAL
MINIMUM
The lowest value of any value flag within a data or index block will be copied into the index entry for the next higher level
MAXIMUM
Analogous to above: the highest value is copied
DUP-KEY
YES
ISAM keys may be duplicated
NO
ISAM keys may not be duplicated
PAD-FACT
nnnnn
Block padding factor
READ-I-ADV
YES
If a second input/output area is defined in the program, read operations can be overlapped
NO
No overlapped processing
WR-IMMED
YES
Every updated block is written back to disk immediately
NO
No immediate writing back
POOL-SIZE
nnnnnnn
Size of the file-specific ISAM pool
Table 113: Output fields for (ISAM file) attributes
Device types and volumes
The information block begins with the header line “VOLUME”. The output fields T-SET-SHR, F-SET-ID, and T-SET-VSN are only shown for:
TFT entries that are linked to a tape set (see the command
ADD-FILE-LINK ...,SUPPORT=TAPE(...,VOLUME=*BY-TAPE-SET))TFT entries created with a CREATE-TAPE-SET command (TFT entry for tape files with the file name *DUMMY; the value of the T-SET-NAME output field is then identical with the link name)
The output fields NUM-OF-VOL and NUM-OF-DEV are only shown if the TFT entry contains private volumes or Net-Storage volumes.
Output field | Values | Description |
|---|---|---|
NUM-OF-VOL | nnn | Number of volumes for the file or the tape set |
NUM-OF-DEV | nnn | Number of reserved devices |
DEV-TYPE | aaaaa | Device type; for Net-Storage volumes the volume type NETSTOR |
*NONE | Device type not specified | |
T-SET-NAME | aaaa | Name of the tape set |
*NONE | TFT entry not linked to a tape set | |
T-SET-SHR | nnnnn | The number of TFT entries linked to the tape set |
F-SET-ID | aaaaaa | VSN of the first tape of the file or tape set |
VSN/DEV | aaaaaa/ | VSNs and device type codes of the volumes linked to the TFT entry (possibly several pairs of values; 3 pairs per output line) |
| *NONE | None specified | |
T-SET-VSN | (aaaaaa) | List of VSNs of the tape set; first current VSN in parentheses |
Output in S variables
The INFORMATION operand identifies the S variables which are to be created. The following specifications are possible for INFORMATION:
Notation used in command | Abbreviated form used in table |
|---|---|
INFORMATION = *ALL | 1 |
INFORMATION = *NAMES-AND-FILES | 2 |
INFORMATION = *PAR(FILE-CONTROL-BLOCK=YES) | 3 |
INFORMATION = *PAR(PROTECTION=YES) | 4 |
INFORMATION = *PAR(STATUS=YES) | 5 |
INFORMATION = *PAR(VOLUME=YES) | 6 |
Output information | Name of the S variable | T | Contents | Condition |
|---|---|---|---|---|
Access method for file rocessing | var(*LIST).ACCESS-METHOD | S | ’’ | 1,3 |
Current VSN of the tape set | var(*LIST).ACTUAL-TAPE-SET-VOL | S | ’’ | 1,6 |
Block control information | var(*LIST).BLOCK-CONTR-INFO | S | ’’ | 1,3 |
Maximum number of data blocks | var(*LIST).BLOCK-LIM | S | ’’ | 1,3 |
buffer offset | var(*LIST).BLOCK-OFFSET | S | ’’ | 1,3 |
Block length | var(*LIST).BUF-LEN | S | ’’ | 1,3 |
Label handling | var(*LIST).BYPASS-LABEL-CHECK | S | ’’ | 1,4 |
Checkpoint at block limit | var(*LIST).CHECKP-AT-BLIM | S | ’’ | 1,3 |
Checkpoint on FEOV macro call | var(*LIST).CHECKP-AT-FEOV | S | ’’ | 1,3 |
Close mode | var(*LIST).CLOSE-MODE | S | ’’ | 1,3 |
Code translation | var(*LIST).CODE | S | ’’ | 1,3 |
Erase to end of tape | var(*LIST).DESTROY-OLD | S | *BY-CAT | 1,4 |
Device type | var(*LIST).DEV-TYPE | S | ’’ | 1,6 |
DIN 66029 interchange level | var(*LIST).DIN-REVISION-NUM | S | ’’ | 1,3 |
ISAM key duplication | var(*LIST).DUP-KEY | S | ’’ | 1,3 |
EBCDIC code translation | var(*LIST).EBCDIC-TRANSL | S | ’’ | 1,3 |
Maximum file size | var(*LIST).EXC-32GB | '' | 1,3 | |
Close message after CLOSE | var(*LIST).F-CLOSE-MSG | S | *NO | 1,3 |
File name | var(*LIST).F-NAME | S | ’’ | 1,2,3,4,5,6 |
Sequence number of file in file set | var(*LIST).F-SEQ | S | ’’ | 1,3 |
VSN of the first tape in the tape set | var(*LIST).F-SET-ID | S | ’’ | 1,6 |
Chained input/output | var(*LIST).IO-CHAIN | S | ’’ | 1,3 |
Performance requirements for I/O operations | var(*LIST).IO-PERF | S | ’’ | 1,3 |
Operation(s) affected by the I/O performance requirements | var(*LIST).IO-USAGE | S | ’’ | 1,3 |
Length of ISAM key | var(*LIST).KEY-LEN | S | ’’ | 1,3 |
Position of the ISAM key in the record | var(*LIST).KEY-POS | S | ’’ | 1,3 |
Type of labels used when creating tape files | var(*LIST).LABEL-TYPE | S | ’’ | 1,3 |
File link name | var(*LIST).LINK | S | *BLANK | 1,2,3,4,5,6 |
Specification indicating whether the file can be opened for write access from two or more systems of an XCS network simultaneously | var(*LIST).LOCK-ENV | S | *HOST-SYS | 1,3 |
Lock on link name | var(*LIST).LOCK-F-LINK | S | *NO | 1,5 |
Length of the logical flag in the ISAM index | var(*LIST).LOGIC-FLAG | S | ’’ | 1,3 |
Number or reserved devices | var(*LIST).NUM-OF-DEV | S | ’’ | 1,6 |
Number of volumes | var(*LIST).NUM-OF-VOL | S | ’’ | 1,6 |
OPEN mode | var(*LIST).OPEN-MODE | S | ’’ | 1,3 |
Creation of the TFT entry | var(*LIST).ORIG | S | *FILE | 1,5 |
Overwrite protection | var(*LIST).OVERWRITE-PROT | S | ’’ | 1,4 |
Block padding factor | var(*LIST).PAD-FACT | S | ’’ | 1,3 |
Pool link name | var(*LIST).POOL-LINK | S | ’’ | 1,3 |
Size of the file-specific ISAM pool | var(*LIST).POOL-SIZE | S | ’’ | 1,3 |
Printer control characters for the file | var(*LIST).PRINT-CONTR | S | ’’ | 1,3 |
Treatment of the value flag within a data or index block (for K-ISAM files) | var(*LIST).PROPA-VAL | S | ’’ | 1,3 |
Label check protection level | var(*LIST).PROT-LEV | S | ’’ | 1,4 |
Overlapping reads | var(*LIST).READ-IN-ADV | S | ’’ | 1,3 |
File record format | var(*LIST).REC-FORM | S | ’’ | 1,3 |
File record length | var(*LIST).REC-SIZE | S | ’’ | 1,3 |
Locked device releasing with the REMOVE-FILE-LINK command | var(*LIST).REL-DEV | S | *NO | 1,5 |
Locked link name releasing with the REMOVE-FILE-LINK command | var(*LIST).REMOVE-F-LINK | S | *NO | 1,5 |
File handling on restarts | var(*LIST).RESTART-USAGE | S | ’’ | 1,3 |
File retention period | var(*LIST).RETENT-PERIOD | S | ’’ | 1,4 |
Shared update capability | var(*LIST).SHARE-UPDATE | S | ’’ | 1,3 |
Status of the file | *ACCESSIBLE | S | *NOT-ACTIVE | 1,5 |
Streaming mode I/O | var(*LIST).STREAM-MODE | S | ’’ | 1,3 |
File storage medium | var(*LIST).SUP | S | *PRIV-DISK | 1,2,3,4,5,6 |
Tape mark writing | var(*LIST).TAPE-MARK-WRITE | S | ’’ | 1,3 |
Name of the tape set | var(*LIST).TAPE-SET-NAME | S | ’’ | 1,6 |
The number of TFT entries linked to the tape set | var(*LIST).TAPE-SET-SHARE | S | ’’ | 1,6 |
VSN of the tape set | var(*LIST).TAPE-SET-VOL(*LIST) | S | ’’ | 1,6 |
Type of output to tape cartridge | var(*LIST).TAPE-WRITE | S | ’’ | 1,3 |
Unload released tapes | var(*LIST).UNLOAD-REL-TAPE | S | *NO | 1,5 |
Length of a value flag in the ISAM index | var(*LIST).VAL-FLAG-LEN | S | ’’ | 1,3 |
Number of tapes containing data from the file | var(*LIST).VOL-WITH-DATA | S | ’’ | 1,5 |
Device type (entry in the volume table) | var(*LIST).VT(*LIST).DEV | S | ’’ | 1,6 |
Volume sequence number (entry in the volume table) | var(*LIST).VT(*LIST).VOL | S | ’’ | 1,6 |
Read-after-write checking | var(*LIST).WRITE-CHECK | S | ’’ | 1,3 |
Updated block write-back | var(*LIST).WRITE-IMMED | S | ’’ | 1,3 |
Examples
For examples of the output of SHOW-FILE-LINK, see the ADD-FILE-LINK and CREATE-TAPE-SET commands.