Macro type: type S (E form/L form/D form/C form); see "Macro types"
By means of the RDTFT macro, the user can fetch information from the task file table (TFT) and output it to a user area. If desired, he can also request information from the TST entry associated with the TFT entry.
Format
Operation | Operands |
|
|
| |
|
Operand descriptions
outaddr
Symbolic address of the output area to which the information from the TFT is to be transferred. This address must be specified if MF=L is specified or if no entry is made for the MF operand.
length
Length of the user area
Minimum length: 11 bytes; exception with NUMONLY=YES: 4 bytes
Default value: | 140 bytes for SHORT, PARMOD=24/31; |
FILE = pathname
Specifies the file(s) on which information is to be supplied
with: <c-string 1..80: filename 1..54 with-wild(80)>
Designates the file or file generation from whose TFT entry information is to be supplied.Wildcards can be used to replace strings in “catid”, “userid” and “filename”; however, the total string length for “pathname” must not exceed 80 characters. Empty file names and the file name “*DUMMY” are not selected when wildcards are used.
If “pathname” is a file generation, the absolute generation number must be specified.
The internal file name is output for temporary files.
“pathname” means [:catid:][$userid.]filename
catid
Catalog ID; default value: the catalog ID assigned to the user ID.
userid
User ID; default value: the user's own ID.
filename
Fully or partially qualified file name.
LINK = name
File link name of the TFT entry from which information is to be passed to the output area (if appropriate, together with information from the associated TST entry).
Wildcards may be used to replace strings in “name”, in which case the following applies:
The total string length must not exceed 80 characters.
With the exception of the wildcards, the entire string may only contain characters from the permitted value range of the command interface.
If wildcards are specified, only those TFT entries that have file link names which were constructed from characters in the permitted value range for the command interface will be selected.
LINKWC
Only as of VERSION=2:
Defines whether placeholders in the link name are to be interpreted as normal characters or as wildcards.
= NO
Placeholders are treated as normal characters.
= YES
Placeholders are interpreted as wildcards.
LONG
The complete TFT entry is placed in the user area, followed by the associated TSTentry including the device list.
MF
The forms of the MF operand are described in detail in the appendix ("Macro types"). In all macros differentiated by MF operands (MF=L/E/D/C), the version operand must contain the same value.
If MF is not specified, you get the S form; however, the explicit specification MF=S is only possible for PARMOD=24.
NUMONLY
Only as of VERSION=3:
Defines whether only the number of selected TFT entries is to be written to the output area.
= NO
The number of selected TFT entries is not transferred to the output area.
= YES
The selected TFT entries are counted and the result written into the first four bytes of the output area. Nothing further is output. The minimum size of the output area is four bytes.
PARMOD
Specifies the generation mode for the macro. If PARMOD and VERSION are specified simultaneously, the PARMOD operand is ignored and an MNOTE message is generated.
Default value: | 31, if VERSION is specified, |
= 24
The macro is generated with the expansion for the 24-bit interface. The object code can be executed only in 24-bit addressing mode.
= 31
The macro is generated such that it is independent of the addressing mode.
PLIST
Generates a list with symbolic addresses for the input or output area, depending on the VERSION and PARMOD operands.
= INPUT
Generates a list for the input area.
= OUTPUT
Generates a list for the output area.
PREFIX
Evaluated only in conjunction with MF=C or MF=D; defines the first character of each field name and equate generated in the data area when the macro is expanded.
Default value: | PREFIX = I |
= pre
The first character of the generated names is replaced by “pre”;
for the input area: 1-2 characters, first character a letter;
for the output area: 1 letter.
= *
No prefix is generated.
SHORT
The static part of the task file table (TFT) entry is transferred to the user area, followed by the static part of the associated TST entry (without the device list); see the LONG operand, below.
VERSION
Controls the generation of the operand list, SVC and output area. If PARMOD and VERSION are specified simultaneously, the PARMOD operand is ignored and an MNOTE message is generated.
The return code is stored exclusively in the parameter list standard header. The RDTFT function also supplies the new output list (see "Programming notes").If a PARMOD value is specified simultaneously, it is ignored.
Default value: | generation of the operand list is controlled by the PARMOD operand. |
= 2
Creates the operand list valid as of BS2000 V9.5. The return code is stored in the standard header and in register 15.
= 3
Specifies the macro version: the operand list for the macro version valid as of BS2000/OSD-BC V3.0 is generated.
Programming notes
Input area
If the VERSION operand is omitted, the old operand list is generated, depending on the value of the PARMOD operand. A Dsect can be generated for this area by means of the DMARD macro or via the operands MF=D,PLIST=INPUT.
If VERSION=2/3 is specified, the operand list includes the standard header and the field which contains the length of the output area is defined as an address constant (4 bytes). A Dsect for this area is generated using the operands VERSION=2/3, MF=D, PLIST= INPUT.
Output area
The RDTFT macro returns one of two lists, depending on whether or not the operand LINK=name is specified:
without LINK=name, or if “name” includes wildcards and the operand LINKWC=YES is specified, only a list of the file link names and the file names linked to them is transferred to the output area.
The list is in chronological order, i.e. in the order in which the TFT entries were created. Each link name/file name pair is preceded by one byte which contains the length of these two fields + 1.
The list is terminated by one byte containing the value X'00', and the byte after this shows whether or not all requested information has been transferred to the output area.X'00' All file link names and the related file names have been transferred to the user area. X'01' One or more file link names, with their related file names, could not be placed in the user area, since it was already full. If NUMONLY=YES is specified, the number of selected TFT entries is output to the first four bytes of the output area. Nothing further is output.
with LINK=name, the TFT and TST information for the specified file link name is placed in the output area, provided “name” does not contain wildcards.
The output area then consists of a fixed part and a variable part. The fixed part contains information from the TFT and TST. The variable part is created only if the LONG operand is specified; it contains further information from the TFT and, possibly, TST volume information.
Field length (bytes) with VERSION Field length (bytes) without VERSION Contents 2 2 Length of output area without variable part 8 8 File link name 54 54 Path name 116 76 Static part of TFT entry and associated TST entry variable variable TFT and TST volume information (if LONG is specified) If the VERSION operand is omitted, the output list has the old format shown in the table above. A Dsect for this output list can be generated by means of the DMADR macro or via the operands MF=D, PLIST=OUTPUT of the RDTFT macro.
If the operand VERSION=2/3 is specified, the new format of the output list is generated. This has a few more fields than the old format. In addition to the information in the previous output list, the new one provides above all information on BLKCTRL, POOLLNK, TAPEWR, CLOSMSG, CLOSE, IOPERF, IOUSAGE, EXC32GBand DESTOC (see the FILE macro, "FILE - Define file attributes / control file processing"). Moreover, the device type is output in printable form (e.g. “D3439-10”). For output with LONG, the TFT volume information was extended.
A Dsect for this output list can be generated via the operands VERSION=2/3, MF=D, PLIST=OUTPUT.With PARMOD=31 or VERSION=2/3, the path name is always displayed in full; in all other cases it is output in the form in which it was placed in the TFT entry using FILE or OPEN, i.e. without a catalog ID or user ID if these were omitted. However, it is possible to specify, for the entire system, that the catalog ID and user ID are always to be output.
If the TFT entry is not linked to a TST entry, the appropriate part of the output area is filled with binary zeros (X'00').
Return codes
The error code is returned in the parameter area standard header. Error code 0 means that no errors occurred. The other error codes are described in the DMAIDEM or DCOIDEM macro.
Program termination with STXIT connection can be initiated in the following cases:
parameter address incorrect (e.g. shorter than the standard header)
parameter address not aligned on a word boundary
UNIT or FUNCTION in header incorrect
header is write-protected
If the version value is incorrect, the code is returned in the header and in register 15. If the header is not writable, the program is terminated with STXIT connection. The subcodes are only given values as of VERSION=3.
Standard header: ccbbaaaa
The following code relating to execution of the RDTFT macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'01' | X'059D' | Invalid link name | |
X'01' | X'05AB' | Invalid range or length | |
X'40' | X'05E1' | Link name not found | |
X'01' | X'06CB' | Output area too small | |
X'01' | X'06FD' | Invalid parameter list range | |
X'03' | X'FFFF' | Invalid version |
Example
BEGIN START
.
.
RDTFT MF=(E,EXTENT),VERSION=3 RDTFT-SVC
.
.
EXTENT RDTFT OUTPUT,,SHORT,LINK=JOHN,MF=L,VERSION=3 OPERAND LIST
.
.
OUTPUT DS XL180 OUTPUT AREA
.
INDSK RDTFT MF=D,PLIST=INPUT,VERSION=3 DSECT INPUT OPERAND LIST
.
OUTDSK RDTFT MF=D,PLIST=OUTPUT,VERSION=3 DSECT OUTPUT OPERAND LIST
.
.
END