Display contents of file
Component: | SHOW-FILE |
Functional area: | File processing |
Domain: | FILE |
Privileges: | STD-PROCESSING |
Function
The SHOW-FILE command displays the contents of a file on the terminal without requiring the user to load an editor program. The following file types are supported:
SAM file
ISAM file
PAM file
PLAM library element with the following record types:
records of the B format are contained in elements of the type C (executable program), L (LLM) and H (compiler information file). The record length is always a multiple n of 2048 bytes (1 <= n <= 128).
records of the A format can occur in any element type. The record length is variable.
If an element contains both record types, only the records of the B format are displayed.
After the command has been entered, the specified file or library element is opened and the first section is displayed on the terminal. The program then expects further statements from the user, e.g. scrolling in the file (vertical/horizontal), searching for a character string, modification of the output format, reading in of another element from the specified library, termination of file output.
This command may be used only in interactive mode.
With the help of XHCS, SHOW-FILE can also display files if the terminal does not support the data character set (e.g. Unicode). For details, see section "Character sets". If the XHCS subsystem is not active, SHOW-FILE terminates and message SHO0021 is issued.
Format
SHOW-FILE | Alias: SHF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
FILE-NAME = *LIBRARY-ELEMENT(...) / <filename 1..54>
Name of the file to be output.
FILE-NAME = *LIBRARY-ELEMENT(...)
Indicates the PLAM library element to be output.
LIBRARY = <filename 1..54>
Name of the PLAM library containing the element to be output.
ELEMENT = <composed-name 1..64 with-under>(...)
Name of the element to be output. Further elements of the same library can be output with the OPEN statement without calling the command again (see "OPEN").
VERSION = *HIGHEST-EXISTING / <composed-name 1..24 with-under>
Version number of the element (max. 24 characters).
VERSION = *HIGHEST-EXISTING
The element with the highest version and variant number is opened.
TYPE = <alphanum-name 1..8>
Designation of the element type.
OUTPUT-FORMAT =
Determines the output format.
OUTPUT-FORMAT = *STD
SAM and ISAM files, in addition to library elements, which contain exclusively A records, are displayed in a character-oriented text format, the character format (OUTPUT-FORMAT=*CHARACTER).
Library elements which contain records of the format B and PAM files are displayed in dump format (OUTPUT-FORMAT=*DUMP), but tape files with nonstandard blocks are not supported.
OUTPUT-FORMAT = *CHARACTER
Library elements which contain B records are displayed in dump format after message SHO0313 has been issued.
The data is output in a character-oriented text format, the character format. The data is output as characters. The substitute character specified is output in place of nonprintable characters (see SUBSTITUTE-CHARACTER in the output of the SHOW-TERMINAL-OPTIONS command).
When the characters are displayed, the bytes in the specified data character set which are read from the file are interpreted and displayed in the specified communication character set. Interpretation begins with the character which is logically the first in each record (depending on the specified OFFSET).
The position count begins with the first character with the not displayable or not defined attribute; characters which cannot be converted to the communication character set are replaced by the specified substitute character. In this context, the null character is regarded as displayable (in accordance with the XHCS attribute but contrary to the Unicode convention).
In the case of UTFE or UTF8, byte sequences which are illegal in the data character set are converted byte by byte to the substitute character. The restart point is the continuation byte for the byte which is substituted. Illegal UTF16 characters are replaced completely (2 bytes) by the substitute character. Any isolated remainder byte which is present at the end of the record is also replaced by the substitute character.
When the output is supposed to be to a file, in other words, if SYSOUT is assigned to a file in procedure mode, these specifications apply analogously, with the file’s CCS being taken as the communication character set.
Each record is terminated with a logical end-of-line character. An empty recorded is displayed with just the logical end-of-line character. The logical end-of-line character is not output if SYSOUT is assigned to a file in procedure mode. When a 3270 data display terminal is used, no logical end-of-line characters are displayed, either, but the lines are filled with null characters.
The HEX ON statement is used to switch the display to hex format (see OUTPUT-FORMAT=*HEX).
OUTPUT-FORMAT = *HEX
Library elements which contain B records are displayed in dump format after message SHO0313 has been issued.
The data is edited in a character-oriented text format, hex format. This output complies with character format; the hexadecimal character encoding is displayed in printable form in additional lines:
The data is output as characters in the first lines (as with character format).
Pairs of hex lines which display the content of each byte are then output. The upper line contains the high-order half byte, the lower line the low-order half byte.
Depending on the data character set, the number of these line pairs can vary: precisely one line pair is required with 7/8-bit character sets.
Two hex lines are generally not sufficient for output in the case of Unicode files. With UTF16 two line pairs are required for the hex display, with UTF8 up to three line pairs, and with UTFE as many as four line pairs. However, with UTF8 and UTFE one line pair is normally adequate as the characters can be encoded with variable lengths, and more line pairs are needed only for special characters (such as umlauts, “ß” or the euro sign).An edited record is followed by a format line as an optical separator to the next record.
If the hexadecimal output of a record no longer fits completely in the data window, this record, and possibly others, will only be displayed in character format in the remaining lines and will only be edited when further positioning takes place.
The HEX OFF statement can be used to switch to character format (see OUTPUT-FORMAT=*CHARACTER).
OUTPUT-FORMAT = *DUMP
This output format is not allowed for library elements that only contain A records or for tape files with nonstandard blocks.
Output takes place in dump format. For this purpose SHOW-FILE opens the file to be output using the PAM access method or opens the library element with PLAM and outputs the content in 2-Kbyte units (PAM page):
Each line begins with an 8-digit hexadecimal number, the byte number of the first data byte in the line in the current PAM page. The output follows as an eight-digit decimal number in parentheses.
The byte number is followed by 16 data bytes in groups of 4 bytes each as hexadecimal constants. 32 bytes are displayed in screen format F2.
The data bytes are then displayed as printable characters. As with character format, the substitute character is displayed in place of nonprintable characters. The line ends with a logical end-of-line character. The position count begins with 0, i.e. the first byte of a record occupies byte position 0.
Multibyte sequences of variable length (UTF8, UTFE) are displayed in the part edited for printing in such a way that the character is output at the position of the 1st byte; null characters are output as filler characters at the positions of the 2nd, 3rd and 4th bytes (depending on the length of the sequence). Interpretation begins with the first byte displayed in the data window. Multibyte sequences which extend over more than one screen line result in the character string concerned being made up when it is edited for printing.
Multibyte sequences of fixed length (UTF16) are displayed without filler characters, i.e. two bytes are displayed as one character. If in the case of UTF16, the problem occurs that interspersed 1-byte characters cause the interpretation to be incorrect up to the end of the block, this is simple to correct by shifting the area displayed by one byte. This also applies for the case that unaligned UTF16 character strings in the file which it would not be possible to correct using the OFFSET statement occur in the middle of the block.
As the dump format should in particular also display files which do not have consistent encoding, it is accepted that (in contrast to the text output formats) horizontal displacement might change how the characters are interpreted. The OFFSET statement is consequently also rejected for dump format with message SHO0128.
Return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
|---|---|---|---|
0 | CMD0001 | Command executed without error | |
2 | 0 | SHO0004 | File is empty (HIGHEST-USED-PAGE=0) |
1 | CMD0202 | Error while executing in batch mode | |
32 | SHO0001 | Internal error | |
32 | SHO0003 | Error during execution of a system component | |
32 | SHO0023 | PLAM error during library processing | |
64 | SHO0002 | PLAM reported DMS error | |
64 | SHO0005 | Only SAM, ISAM, PAM files and PLAM libraries are supported | |
64 | SHO0006 | Files with RECORD-FORMAT=UNDEFINED are not supported | |
64 | SHO0008 | PLAM library elements cannot be output in dump format | |
64 | SHO0011 | Specified file is not a PLAM library | |
64 | SHO0012 | Specified PLAM library element is not known | |
64 | SHO0015 | Terminal type is not supported | |
64 | SHO0016 | Device type is not supported | |
64 | SHO0017 | EOF in the case of SYSDTA in procedure mode | |
64 | SHO0018 | WROUT error | |
64 | SHO0019 | Invalid character set for SYSDTA | |
64 | SHO0020 | Invalid character set for SYSOUT | |
64 | SHO0021 | XHCS not available | |
64 | SHO0022 | Dump format not possible with SAM or ISAM access method |
Character sets
SHOW-FILE V17.1A or higher also supports the output of files with the character sets UTFE, UTF8 and UTF16 and further ASCII character sets. As BS2000 terminals only directly support selected EBCDIC character sets, a distinction must be made between the character set in which the data is available/interpreted and the character set in which the data is displayed.
SHOW-FILE interprets the data in the data character set and converts it to the communication character set for output. The contents of files can consequently be output in all the character sets supported by XHCS with the help of XHCS. This is also the case if the data character set is not supported by the terminal.
If XHCS is not active, SHOW-FILE cannot output the file and terminates with SHO0021.
Data character set
The data character set is the character set in which SHOW-FILE interprets the content of the file. SHOW-FILE uses the character set which is stored in the catalog entry of the file or in the metadata of the library element (CCS, Coded Character Set) as the data character set. If no character set (*NONE) is entered, the EDF03IRV character set is used.
If the character set is not known in XHCS, EDF03IRV is also used and warning SHO0314 is output.
The data character set specified automatically by SHOW-FILE can be changed explicitly using the CODENAME statement. This also permits, for instance, a file to be displayed in which the character set from the catalog entry or the EDF03IRV character set which is used as a replacement does not match the character set actually used.
Communication character set
The communication character set is the character set in which the work window is displayed on the terminal and inputs from the terminal are received. The communication character set must be a character set which is accepted by the terminal. When SHOW-FILE is called, it determines the communication character set as follows:
The data character set if it is accepted by the terminal.
A comprehensive character set of the EBCDIC equivalent of the data character set if it is accepted by the terminal.
EDF041 (or EDF03IRV in the case of 7-bit terminals) if the terminal does not accept a comprehensive character set (e.g. data character set UTF16, but the terminal does not support UTFE).
This then results in the following substitutions:
Original | EBCDIC equivalent | Accepted by the terminal |
|---|---|---|
ISO88591 | EDF041 | EDF041 |
UTF16 | UTFE | UTFE |
EDF03DRV | EDF03DRV | EDF041 |
The communication character set specified automatically by SHOW-FILE can also be changed explicitly using the TERMINAL statement.
Input and output character sets
In procedure mode (see "SHOW-FILE") SHOW-FILE uses the following character sets:
Input character set for reading the statements:
Communication character set when SYSDTA has primary allocation (terminal)
CCS of the file to which SYSDTA is assigned
As output characters for outputting the data:
Communication character set when SYSOUT has primary allocation (terminal)
CCS of the file to which SYSOUT is assigned
Both the input and output character set must be an EBCDIC character set. If this is not the case, SHOW-FILE issues message SHO0019 (input character set) or SHO0020 (output character set) and terminates.
Displaying nondisplayable characters
It may not be possible to display a byte code for the following reasons:
Byte code is flagged in XHCS with the “not displayable” attribute (e.g. control character).
Byte code is not defined in the character set (e.g. X'B5' in EDF03IRV).
Byte code is illegal in the character set (e.g. X'5454' in UTFE, two consecutive multibyte start characters).
Byte code cannot be converted to the communication character set (e.g. X'B5' = '§' in EDF041 with communication character set EDF03IRV).
Instead of the nondisplayable byte code the substitute character which is specified as the SUBSTITUTE-CHARACTER in the terminal options is output (see the SHOW-TERMINAL-OPTIONS command).
In the case of illegal byte sequences, the individual bytes of a sequence are replaced byte by byte via the substitute character. The restart point is the continuation byte for the byte which is substituted.
In the case of files in UTF16 character code, occasionally the problem is encountered that a single byte is inserted in the actual UTF16 sequence.
A typical case is that the UTF16 sequence is preceded by a 1-byte printer feed control character (e.g. in IBM print files). Such a file can be displayed effectively if the OFFSET statement is used to ignore the first n bytes of each record.
SHOW-FILE in procedure mode
If job switch 5 is on when the command is called, SHOW-FILE operates in procedure mode, i.e. it reads its inputs from SYSDTA and writes its outputs to SYSOUT.
The maximum record length when reading from SYSDTA is 80 characters.
If a FIND or OPEN statement was entered incompletely up to an interrupt point, the next record which is read in is interpreted as a continuation line.
When SYSDTA or SYSOUT is assigned to the terminal, reading/writing takes place in the communication character set. When they are assigned to a file, this is the CCS of the file concerned. In this case, only EBCDIC character sets are permitted (the communication character set can also only be an EBCDIC character set) to permit the statements to be interpreted.
In procedure mode, INFORMATION also outputs the input and output character sets.
The penultimate line of the work window only contains the status indicator. The RDATA prompt appears in the last line if SYSDTA is assigned to a terminal.
For the output the screen is output to SYSOUT in its normal layout with all control characters. The terminating logical end-of-line characters are not output when a file is output.
Screen display
SHOW-FILE displays the opened file or the library element in the work window on the screen in formatted form. The size of the work window depends on the properties of the data display terminal or terminal emulation used. On a 975x terminal 24 lines each 80 characters long are available for the screen display. The same values apply for a 9763 terminal in start format (F1 format). Here the VDT statement (see "VDT - Specify a new screen format") can also be used to set other formats (F2, F3 or F4 format). In the case of terminals which do not support the F1 format, the format which they support is used as the start format.
The work window subdivides the screen into three areas with different functions:
Data window
The data in the file or of the library element is output in the data window. All lines on the screen except the last line are available for this purpose in their full length. Normally this means 23 lines each containing 80 columns. When a different screen format is specified (see the VDT statement, "SHOW-FILE"), the values change accordingly.
When required, the lower lines of the data window are used to output information lines (2 or 6 lines, see the INFORMATION statement), for message output (1 line) or to provide continuation lines (up to the maximum number of lines in the data window minus 1. After the screen has been refreshed (e.g. using [K3]), the original data lines are visible again.
Statement line
The statement line occupies the last line on the screen (by default line 24) with the exception of the last 26 characters, which are reserved for the status display.
In procedure mode, this line is not displayed in the last line, but one line above this. The RDATA prompt becomes visible in the last line, and the statements can be entered there.
Status indicator
The status indicator provides information on the file type and positional attributes of the file section displayed. The display is in the form:
'BLANK'<type>*<reference><direction><recordno>(<recordpos>)
where:
Position | Content | Meaning and value range |
|---|---|---|
1 | 'BLANK' | Blank |
2 | <type> | File type: I (=ISAM), S (=SAM), P (=PAM) or L (=PLAM) |
3 | * | Separator |
4 | < | Reference position for
For PLAM libraries (file type=L), the PLAM record type is shown. |
7 | < | Direction specifies the sign for the record number in relation to the reference position: + or - |
8 | < | Record number relative to the reference position (see <
In the case of record numbers with more than 10 characters, the high-order part is truncated: the character # followed by the last 9 characters in the record number is displayed. |
18 | ( | Separator |
19 | < | Record position, i.e. number of the first character on the screen. For PAM files, the position within the PAM page is displayed. |
25 | ) | Separator |
26 | Not assigned or [LZE]in procedure mode |
Example
S*SOF+ 1( 1)
Maximum character/byte position
Horizontal scrolling in character and hex format is possible to the maximum character position, and in dump format to the maximum byte position. The maximum character/byte position applies irrespective of whether records of this length exist.
The maximum character position in character and hex format specifies the (theoretical) maximum length for a record in this file. This applies irrespective of whether the file contains records of this length at all. The existence of a record length field is taken into account here, but no other file or device properties.
In the case of SAM and ISAM files with fixed record length, the maximum character position is exactly the record length defined in the catalog.
In the case of SAM and ISAM files with variable record length, the maximum character position is the block size minus 4.
In the case of library elements which only contain A records, the maximum character position is 32764.
In dump format the maximum byte position for files is 2047 (PAM page), and for library elements which contain B records 256 Kbytes-1.
In the text formats, scrolling to the right takes place only as far as to permit the maximum character position to be displayed in the first column of the data window.
In dump format, scrolling to the right takes place only as far as to permit the maximum byte position to be displayed in the first byte position of the data window.
Entering statements
One or more statements can be entered in the statement line. If several statements are entered, they must be separated by semicolons.
The statements are interpreted in EBCDIC. A distinction between uppercase/lowercase is only made within c-strings of the FIND statement if this has been preset using the LOWER operand or the LOWER statement. Keywords are not case-sensitive.
Null characters are treated like blanks when they are entered.
When job switch 5 is on, SHOW-FILE operates in procedure mode (see "SHOW-FILE in procedure mode").
Commands can only be entered again after SHOW-FILE has terminated (e.g. /HELP-MSG-INFORMATION to explain an error message).
The [K3] key can be used to restore the screen contents if, for example, the screen has been overwritten by a message from the operator.
Continuation lines
The space required for the OPEN or CLOSE statement can be more than one line. If the statement completely fills and overruns the line allocated to it, the required continuation lines are provided.
When a search string is being entered, a continuation line is offered until the maximum search string length of 256 bytes (256 characters in the case of a c-string and 512 characters in the case of an X string) is reached or a concluding apostrophe is entered. When the maximum search string length is exceeded, the input is aborted with message SHO0113.
No more than the maximum number of continuation lines required to make another data line visible is offered. If the statement is still incomplete after this, the input is aborted with message SHO0101.
Interrupting long-running statements
Positioning and searching in big files may take a long time. In such cases, it is possible to interrupt long-running statements of the SHOW-FILE command by pressing the [K2] key. This applies to the following statements:
sequential forward positioning with +n
sequential backward positioning with -n
search for string (c-string or x-string) with FIND
In procedure mode, interruption by the [K2] key is not possible.
If one of the above statements is interrupted, the warning SHO0307 is issued and SHOW-FILE waits for your next input. Screen output resumes at the position that had just been reached. The presetting of the statement line depends on the interrupted statement (see "Presettings for the statement line").
Presettings for the statement line
In interactive dialog, SHOW-FILE presets the statement line after a positioning statement has been entered or the FIND and OPEN statements have been issued with a plausible continuation statement. This permits, for example, the file to be scrolled through simply using [DUE] without reentering “+”.
After SHOW-FILE has been called, “+” is initially preset in the statement line if the file contains more than one record.
Input | Preset with | No presetting |
|---|---|---|
+[n] | +[n] | Only one record is displayed. |
++ | - | Only one record exists. |
-[n] | -[n] | The first record is displayed. |
-- | + | Only one record exists. |
>[n] | >[n] | Maximum character or byte position has been reached. |
<[n] | <[n] | First character or byte position is displayed. |
<< | > | |
FIND [REVERSE] | FIND [REVERSE] | No hit found. |
OPEN | + | The element contains only one record. |
The statement line is not preset in the following cases:
SHOW-FILE was called in procedure mode (job switch 5 is set).
The file consists of only one record,
When errors occur, the last entry is output once more in the statement line. If the statement line was overwritten, the presetting can be made visible again with [K3].
Overview of the statements
The table below lists all the statement in the order in which they are subsequently described. Statement names and operands can be abbreviated from left to right as long as they remain unambiguous.
Statement | Function |
++ | Position to end of file |
+[n] | |
-[n] | |
-- | |
Rn | |
<< | |
<[n] | |
>[n] | |
Sn | |
Further instructions | |
FIND | |
LOWER | |
HEX | |
OFFSET | |
CODE-NAME | |
TERMINAL | |
VDT | |
INFORMATION | |
OPEN | |
END | |
Statements for scrolling
The character or byte position currently set is not changed when vertical scrolling takes place. This also applies if the records in the new display are shorter than the position set.
++ | Position to the end of file, i.e. the last record is (if possible) displayed in the last line of the data window. In the text formats, the last record is displayed as far down in the data window as possible when scrolling takes place. In dump format, the last record is scrolled to. In the case of tape files, this statement is rejected with message |
-- | Position to the start of file, i.e. the first record is displayed in the first line of the data window. |
+[n] | Scroll forward in the file (toward the end of file). If n is not specified, you scroll forward by the number of lines contained in the data window. If records which had not yet been edited were visible in hex output format, you scroll to the first record which has not been edited. You scroll forward no further than to the last record. If n goes beyond this, you scroll to the last record and message |
-[n] | Scroll backward in the file (toward the start of file). If n is not specified, you scroll in such a manner that the record preceding the first record visible in the data window is displayed as far down as possible in the data window. You scroll backward no further than to the first record. If n goes beyond this, you scroll to the first record and message |
Vertical positioning to a specific record
Rn | Position to the nth record, in the case of a display in dump format to the nth PAM page. The records in the file are regarded as being numbered consecutively. This is also the case for library elements in which the numbering is displayed for each record type. |
Statements for horizontal positioning
<< | Move the record section to the left, to the start of the record. |
<[n] | Move the record section to the left character by character or byte by byte (toward the start of the record). n determines the number of characters or bytes by which it is moved. If n is not specified, the following default applies:
If n is greater than the current character or byte position, the position is set to the first character position or the first byte (byte position 0) and message |
>[n] | Move the record section to the right character by character or byte by byte (toward the end of the record and beyond). n determines the number of characters or bytes by which it is moved. If n is not specified, the following default applies:
However, the record section is moved to the right no farther than to permit the maximum character position of a record to be displayed in the first column of the data window or to permit the maximum byte position of a record to be displayed in the first byte position of the data window (see "Maximum character/byte position"). |
Horizontal positioning to a particular character or byte
S[n] | Position the record section displayed to the nth character, in the case of display in dump format to the nth byte of the PAM page. Values where n=<integer 0..2147483647> are accepted. Leading zeros are ignored. Default: n = 1. The position is set to the right no farther than to permit the maximum character position of a record to be displayed in the first column of the data window or to permit the maximum byte position of a record to be displayed in the first byte position of the data window (see "Maximum character/byte position"). |
FIND - Search for a character string or an ISAM key
The FIND statement is used to search for character strings or ISAM keys and sets the position to the first hit.
Format:
|
|
Meaning of the operands
| Specifies that the search string is to be interpreted as an ISAM key. A search string which does not comply with the key length is filled with null characters on the right if it has too few characters or truncated on the right if it has too many. |
| Search string (character string containing a maximum of 256 characters from the communication character set or the CCS assigned to SYSDTA). Quotes within the search string must be doubled. If the character string is too long, the statement is rejected with The character string is converted to the data character set for the search. If that is not possible, the statement is rejected with |
| Search string in hexadecimal format (character string containing a maximum of 512 hexadecimal characters). An even number of characters must be specified. Otherwise, the statement is rejected with |
| Specifies whether lowercase letters in the search string are to be converted to uppercase letters. If this operand is not specified, the default value of the LWER statement applies (see "LOWER - Preset conversion of lowercase letters in search strings"). |
| Lowercase letters are retained. A hit is found only if uppercase/lowercase match. |
| Lowercase letters are converted to uppercase letters. Even when lowercase letters are entered, only uppercase letters are found. |
| Selects the hit-based search strategy (see "Search strategies"). This operand can only be specified in conjunction with a search string. The operand is ignored in a search for ISAM keys. |
| Reverses the search direction, i.e. the search is made toward the start of file. The operand is ignored in a search for ISAM keys. |
Hit display when searching for ISAM keys
When the K operand is specified, the specified search string is interpreted as an ISAM key and the search is restricted to the ISAM keys. The following applies for the hit display:
Data is output starts at the record with the specified ISAM key, the character/byte position in the record remains unchanged.
If no corresponding key exists, error message
SHO0409is issued and the position is set to the record with the next highest existing key. If there is no record with a higher key, the position is set to the last record.
Search strategies
In a new search (a character or byte string was specified) FIND starts at the current character or byte position in the uppermost record which is displayed in the data window. Depending on the data type and the ALL operand, the FIND statement uses two different search strategies when searching for character or byte strings:
The record-based strategy is employed for SAM and ISAM files and library elements with records of the A format if they are displayed in a text format and the ALL operand is not specified. In the event of a hit, i.e. when a record is found which contains the search string at least once, the position is set to the start of the hit record. The search for the next hit begins at the start of the record following the hit record or, in the case of REVERSE, at the start of the preceding record.
The hit-based strategy is always employed for PAM files and library elements with format B records. It is also always employed for SAM and ISAM files if these are displayed in dump format. In all other cases, it is employed only if the ALL operand is specified. To permit the hit-based strategy to be used in the reverse direction, the search direction is also reversed within the record. In the event of a hit, the position is set to the first byte of the character string or byte string found. If, when searching for byte strings, a hit is recorded within a character encoded in several bytes, the position is set to the first byte of this character. The search for the next hit begins with the first byte following the hit byte or, in the case of REVERSE, with the byte preceding the hit byte.
Further information
In the event of a hit, the statement line is preset with FIND or FIND REVERSE, thus enabling the search to be continued in the same direction simply by pressing [DUE]. If the continued search (FIND without a search string) yields no further hits, message
SHO0303is issued and the statement line is no longer preset.If no hit is found in the first search (FIND with a search string), error message
SHO0408is issued. To search the entire file backward in accordance with the hit-based strategy, the position must first be set to the last character or byte of the last record (or behind it).If no operand or only the REVERSE operand is specified, the search is continued with the last search string specified, and if required the search direction is changed. If no search string has been saved, the statement is rejected with message SHO0401.
LOWER - Preset conversion of lowercase letters in search strings
The LOWER statement determines whether SHOW-FILE should convert lowercase letters in the search string to uppercase letters if the LOWER parameter is not specified in a FIND statement.
Format: LOWER
[
ON
/
OFF
]
Meaning of the operands:
| Lowercase letters are retained if no other specification is made within a search statement. |
| Lowercase letters are converted if no other specification is made within a search statement. |
LOWER OFF is preset when SHOW-FILE is called.
HEX - Switch hexadecimal on/off
The HEX statement switches the display between the two text output formats.
Format: HEX
[
ON
/
OFF
]
Meaning of the operands:
| Output takes place in hex format (see OUTPUT-FORMAT=*HEX). |
| Output takes place in character format (see OUTPUT-FORMAT= *CHARACTER). |
In dump format, the statement is rejected with message SHO0119.
OFFSET - Ignore bytes at the start of a record
In text formats the OFFSET statement causes the first n bytes in each record to be ignored. In dump format the statement is rejected with message SHO0128.
In this display mode records with a length <= n are treated like records with a length of zero.
Format: OFFSET
[ n ]
Meaning of the operands:
n | Number of bytes which are to be ignored at the start of the record. Values where n=<integer 0..2147483647> are accepted. Leading zeros are ignored. |
When the statement is executed, the character position for the display is implicitly reset to 1 because the way the characters are interpreted may change.
CODENAME - Specify a new data character set
The CODENAME statement is used to explicitly specify the data character set in which the content of the file is interpreted.
Format: CODENAME
[ ccs-name ]
Meaning of the operands:
css-name | Name of the communication character set to be specified (<name 1..8>). The character set named must be known to XHCS and must be accepted by the terminal. Otherwise, SHOW-FILE will reject the statement with message If the operand is not specified, SHOW-FILE once again specifies the communication character set which was determined automatically (see also "SHOW-FILE"). |
Switching the data character set implicitly triggers a number of actions:
If automatic selection of the communication character set is active (see the TERMINAL statement), it is determined again and, if necessary, specified once more.
The last search string is invalidated, i.e. a FIND statement without a search string is then rejected.
The character position is reset to 1 or the byte position to 0 because the way the data is interpreted may have changed.
The file position remains unchanged so that the user can recognize the effects which changing the character set has on the record which is currently being examined.
TERMINAL - Specify a new communication character set
The TERMINAL statement is used to explicitly specify the communication character set.
Format: TERMINAL
[ ccs-name ]
Meaning of the operands:
css-name | Name of the communication character set to be specified (<name 1..8>).The character set named must be known to XHCS and must be accepted by the terminal, otherwise SHOW-FILE will reject the statement with message If the statement is specified without an operand, SHOW-FILE once again specifies the communication character set which was determined automatically (see also "SHOW-FILE"). |
VDT - Specify a new screen format
The VDT statement is used to explicitly specify a screen format (see also "Screen display") if the terminal supports the format specified.
Format: VDT
[
F1
/
F2
/
F3
/
F4
]
Meaning of the operands:
| Sets the screen format to 24 lines and 80 columns. |
| Sets the screen format to 27 lines and 132 columns. |
| Sets the screen format to 32 lines and 80 columns. |
| Sets the screen format to 43 lines and 80 columns. |
Screen formats F2, F3, and F4 are only supported by terminals of the type 9763. If the terminal does not support the format specified, the statement is rejected with message SHO0306.
INFORMATION - Output information about a file or library element
The INFORMATION statement outputs information about the file or library element which is currently displayed.
Format: INFORMATION
In the case of files, the information output overwrites the last two data lines (by default lines 22-23). The file name and an information line containing the character sets concerned (CCS of the file, data character set, and communication character set) are displayed:
FILE: <filename 1..54> CCSN: FILE=<name 1..8> DATA=<name 1..8> TERM=<name 1..8> FILE: <filename 1..54> CCSN: FILE=<name 1..8> DATA=<name 1..8> TERM=<name 1..8>
In the case of library elements, the information output overwrites the last six data lines (by default lines 19-23). The library name, element name, element type, version, and variant are displayed, as well as an information line containing the character sets concerned (CCS of the file, data character set and communication character set):
LIBRARY: <filename 1..54> ELEMENT: <composed-name 1..64> TYPE: <name 1..8> VERSION: <text 1..24> VARIANT: <integer 1..9999> CCSN: FILE=<name 1..8> DATA=<name 1..8> TERM=<name 1..8>
The information displayed can be cleared by pressing [DUE] (send key) or by entering the next statement. It disappears the next time the screen is redrawn.
If INFORMATION is entered as part of a statement chain, the information is displayed on the next screen of output information. Processing of the statement chain is not interrupted. If output of another message is pending at the same time, it takes precedence over the INFORMATION output.
Example
If you enter +;inf;find c'find' and the ‘find’ string is not found, the message “SHO0408 SPECIFIED STRING DOES NOT EXIST” is output instead of the information.
OPEN - Open new library element
This statement opens a new element in the library specified with the SHOW-FILE call. Any element which had already been opened is automatically closed. If a file is specified in the SHOW-FILE call instead of a library element, the statement is rejected with message SHO0107.
Format: OPEN
([type[,elname[,version]]])
Meaning of the operands:
| Element type (see also the TYPE operand). |
| Element name (see also the ELEMENT operand). |
| Version of the element (see also the VERSION operand). |
Notes:
When the new element is opened, the data character set and the output format are determined again in accordance with the element’s properties.
The communication character set is determined again if automatic selection is enabled.
The position is reset and the search string is invalidated.
Any communication character set which is explicitly specified, the screen format and the default for converting lowercase letters to search strings (see the LOWER statement) are retained.
If the element does not exist, SHOW-FILE issues message
SHO0407. No library element can then be opened and SHOW-FILE only accepts the OPEN and END statements.
END - Terminate file output
The END statement closes the file or library element which is currently being displayed and terminates SHOW-FILE. The terminating message SHO0500 contains the complete file name of the last file displayed or the library name, element name, version, variant and element type of the last library element displayed.
Format: END
The [K1] key has the same effect as the END statement. However, specifications in the statement line are ignored.
Notes for disk files
Files with BLOCK-CONTROL-INFORMATION=*PAMKEY or *WITHIN-DATA-BLOCK may exhibit interblock gaps, i.e. logical blocks which are in fact reserved for a file but not yet actually occupied. These logical blocks are recognized via their invalid CFIDs. As these blocks may still contain data that does not belong to the file, the PAM pages of such blocks are output as “empty” PAM pages (2048 * X’00’). In addition, a message is issued pointing out that
the currently displayed PAM page (OUTPUT-FORMAT=*DUMP) or
one or more PAM pages (in the case of PAM files and OUTPUT-FORMAT=*CHAR or *HEX)
is/are not occupied.
This applies to all PAM files (regardless of the OUTPUT-FORMAT) and to all ISAM and SAM files with OUTPUT-FORMAT=*DUMP.
If DMS error ‘0BB7’ (record with invalid length was read) occurs when a SAM file is being displayed, SHOW-FILE is terminated with a message.
The following disk files are opened with SHARED-UPDATE=*YES:
PAM files, irrespective of the output format
ISAM files, only when displayed in one of the text formats
Write accesses of another task are not possible if the file is also opened with SHARED-UPDATE=*YES.
Notes for tape files
The SHOW-FILE command can also be used to display the contents of tape files, in which case attention must be paid to the following:
Positioning to the end of the file (using ++) is not possible and is rejected with message
SHO0129.Tape files of the type PAM (in all output formats) and type files of the type SAM (in dump format) can be displayed only if the catalog entry contains the correct number of data blocks.
Tape files of the type SAM without a catalog entry (foreign files) can be displayed in the text formats as follows:
Create catalog entry with IMPORT-FILE, e.g.:
/import-file support=*tape(volume=vol001,dev-type=tape,file-name=tape.file)Create TFT entry with the link name DSHOW and the access method SAM using ADD-FILE-LINK, e.g.:
/add-file-link link=dshow, file-name=band.datei, access-method=*samOpen the file with SHOW-FILE, e.g.:
/show-file tape.fileTape files should be displayed sequentially right to the end of the file in a single SHOW-FILE call. When the output is concluded the current block counter is transferred to the catalog entry as the number of file data blocks (see SHOW-FILE-ATTRIBUTES command, BLK-COUNT output field).
If SHOW-FILE is terminated before the end of the file is reached, the file will only be output up to this data block the next time SHOW-FILE is called, the remaining data blocks will not be displayed.
In order to resolve this, the catalog entry may have to be deleted and recreated (EXPORT-FILE and IMPORT-FILE commands).
Tape files of the type SAM which have no catalog entry cannot be displayed in dump format. Tape files of the type PAM which have no catalog entry can never be displayed.
Examples
Hex format display of a file in the UTFE character set (=data character set):
Habe nun, ach! Philosophie,<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - C88849A96488854D8899A998886- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 81250545B0138A078936267895B- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 Juristerei und Medizin,<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DA98AA89884A984D888A896- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1499235959045404549995B- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 Und leider auch Theologie«????????»,<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - E98498888948A884E889998885AAAAAAAA56- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 45403594590143803856367954DDEDDDDD4B- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - F9AB8AFD8F- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - AD04BBAAFA- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9- - - - - - - - 8- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A- - - - - - - - A- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 Durchaus studiert, mit heißem Bemühn.<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CA9888AA4AAA8889A6498A48889894C896894- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 44938142023449593B04930859E540254885B- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A- - - - - - B- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - B- - - - - - 7- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 Da steh ich nun ich armer Tor!<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - S*SOF+ 1( 1)
Dump format display of a file in the UTFE character set (=data character set):
00000000 ( 0) 3DA7841C 00000001 01000000 000001E4 ?xd?- - - - ??- - - - ?U<- - - - - 00000010 ( 16) 01D44040 E6859595 40A28983 88404541 - M Wenn sich Â- <- - - - - 00000020 ( 32) EA45AA8B 45AA9045 AABE45AA 9D45AAB7 - ë- - à- - ä- - è- - ì- - <- - - - - 00000030 ( 48) 45AA9D45 B0416B40 9EB29285 6B40E672 è- - ?- - , Å- ke, Wł<- - - - - 00000040 ( 64) B08184A8 A272B081 A640A495 8440FC8F - adys?- aw und Á- <- - - - - 00000050 ( 80) AEB5ADDA AD8BAD8B ADA0ADDA ADABAEB0 χ- ι- λ- λ- ε- ι- ο- ς- <- - - - - 00000060 ( 96) 40858995 85954054 B2BA40A3 85899385 einen _- - teile<- - - - - 00000070 ( 112) 956B4082 85929694 94A34091 85848599 n, bekommt jeder<- - - - - 00000080 ( 128) 4067B754 B2BA4B40 E6859595 40A28983 1⁄4- _- - . Wenn sic<- - - - - ... ... ... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - P*SOF+ 1( 0)