The Format Line tool accepts a variable which is a string of text and
returns it in a separate variable so that it is formatted to appear
on multiple lines. An option exists to format the line in the same
manner as system messages appear.
By default, the lines are formatted so that:
** A word is never split over two lines
** A line does not start with a blank
** Excess blank characters (more than 1) between non-blank
characters are squeezed out.
** An extra blank is inserted if a period is followed by a space
such as at the end of a sentence.
For example if your string of text looks like:
aaa bbbbb cccc ddd ee fffffff gggg hhhh iii j kkkk
The return variable may look like:
aaa bbbbb cccc ddd ee fffffff gggg hhhh iii j kkkk
<----- Line 1 -------><------- Line 2 -------><--- Line 3 --..
FMTLIN requires that you describe the length of your lines. You must
then extract (e.g. substring) from the return variable to match the
length of your lines as specified on the command.
Unless special formatting characters are used (described later) each
string of data would appear as a single paragraph. A straight left
edge would exist and a ragged right edge such as:
------------------
----------------
-------------------
The input string can be up to 9799 bytes in length. The output
string must be declared as *CHAR LEN(9999). The maximum line length
is 200 bytes.
The following shows a sample of how you would use FMTLIN. Assume
that a string of text is placed into the variable &INPUT. The
variable is declared as 1000 bytes in length, but the INPLEN
parameter on FMTLIN specifies that only the first 300 bytes be
formatted. The LINLEN parameter specifies that the lines should be
formatted into 60 byte sections.
The data that is used to fill the variable &INPUT is less than 100
bytes. After FMTLIN, the CL substring function is used to substring
out two 60 byte lines.
DCL &INPUT *CHAR LEN(1000)
DCL &FMTLINES *CHAR LEN(9999)
DCL &MSG2 *CHAR LEN(60)
.
CHGVAR &INPUT ('This is what a normal line looks +
line after it is formatted by the +
FMTLIN TAA Tool.')
FMTLIN INPUT(&INPUT) INPLEN(300) LINLEN(60) +
FMTLINES(&OUT)
CHGVAR &MSG2 %SST(&FMTLINES 1 60)
SNDPGMMSG MSG(&MSG2)
CHGVAR &MSG2 %SST(&FMTLINES 61 60)
SNDPGMMSG MSG(&MSG2)
Other formatting comments
-------------------------
There are special formatting characters that may be placed in the
text to control:
** Starting a new line
** Indenting a new line or an overflow line
** Causing extra spaces within a line
See the later discussion.
You can output the text to a display field that may take up several
lines. If an 80 byte wide display is used, each line length would
normally be specified as 80. You would want to start the field at
position 1 of a line.
If you have some lead in description followed by a long field such
as:
Text: ------------
--------------------
--------------------
You can specify a different length of the first line (in this case it
would be shorter than the the other lines). See the FSTLINLEN
parameter.
If there are no blank spaces within a line of output (i.e. one very
long word), no error occurs and the line is output as best can be
achieved.
If the INPUT value is all blanks, all blanks will exist in the return
variable.
Building the string of text from data base records
--------------------------------------------------
Because FMTLIN will squeeze out blank spaces, it makes it convenient
to build a string of text from data base records (or array elements).
Assume your record length is 80 and you have a variable number of
records to be displayed or printed.
There are two methods of storing the data:
** As a single string. A word may be split over two records.
** As separate strings. When the data is entered, place it into
the records so that a word is never split over a record and
position 80 is always blank. When the data is concatenated
together (or via substring), a single string will exist.
Excess blanks are squeezed out.
Calling the CPP Directly
------------------------
You can call the CPP directly from a HLL program. For example,
assume you want to print the text in a block of 60 characters per
line with a maximum of 20 lines. You would place the string of text
into the INPUT field which is defined with a length of 1000 in this
example. The text could come from one or more data base records,
array elements or be generated by the program.
E DATA 9999 1
IFMTLIN DS
I 19999 DATA
C CALL 'TAACLPXC' FMTLIN CPP
C PARM INPUT Input
C PARM 1000 INPLEN 50 Input len
C PARM 60 LINLEN 30 Line len
C PARM FMTLIN Rtn var
C PARM 60 FSTLIN 30 Fst ln len
C PARM '*NO ' FMTCHR 4 Fmt option
C Z-ADD1 DX 50 Inlz
C DO 20 Do 20 times
C MOVEADATA,DX LINE 60 Move a line
C EXCPTDETAIL Print
C ADD 60 DX Bump
C ENDDO Do 20 times
Formatting options
------------------
The same formatting options as used for system messages may be
specified (&N &P &B). These have the same meaning as the system
functions. See the ADDMSGD description of the SECLVL parameter. You
must specify FMTCHAR(*IBM).
Special formatting options may be placed in the text to cause a new
line, indentation, and blank spaces.
To cause the FMTLIN command to be sensitive to these options, you
must specify FMTCHAR(*YES). The default is *NO which causes the
special characters to appear in the output (no special formatting
occurs).
The following are supported.
.N New line - Successive 'new lines' cause a blank
line. An implicit '.N ' is assumed at the beginning
of the output.
.Bn Blank spaces - the 'n' is a value 1-9. If you want
to indent the first character of a new line, use
'.Bn ' before the first character to print. If you
want more than one blank between words within a
line, specify '.Bn ' where required. If you request
blanks that pass the 'end of line' point, blanks do
not carry over to the next line.
.In Indentation of overflow lines - the 'n' is a value
1-9. This does not refer to the first line of a
'new line', but any overflow lines in the paragraph.
When a '.N ' is used for a new line, the overflow
lines indentation is reset to 0. If you want
several paragraphs that are all indented the same,
you must specify '.In ' for each paragraph (i.e.
after each '.N ')
A lower case entry is also supported such as '.n '. You must follow
the entry with a blank.
Any invalid values appear in the output and do not cause formatting
such as:
.n1 Does not end with a blank
.b5x Does not end with a blank
.b& The 'n' value is not 1-9
I5 No leading '.'
The following describes how you can use the special formatting
characters to achieve typical output requirements:
1. Start a new line
------ Input ------ ---- Output ----
xxxx .n yyyy zzzz xxxx
yyyy zzzz
A new line occurs when the 'new line' request is made.
2. Cause a blank line
------ Input ------ ---- Output ----
xxxx .n .n yyy xxxx
yyy
Two 'new lines' in succession cause a blank line.
3. Indent the first line
------ Input ------ ---- Output ----
.B5 -----... -----
----------
The first line is indented by 5 spaces because of the
'.B5 '.
4. Indent the overflow lines
------ Input ------ ---- Output ----
.i3 -----... ----------
-------
-------
The overflow lines are indented 3 because of the '.i3
'.
5. Cause 3 blanks between two fields
------ Input ------ ---- Output ----
xxx .b3 yyy xxx yyy
Three spaces appear between the two fields because of
the '.b3 '. The extra space after the xxx value is
suppressed.
5. Indent a description
------ Input ------ ------ Output ------
Bob: .b5 ----- Bob: ---------
.n .n Mary: .b4 ---- --------
Mary: --------
---
To achieve this format, you must specify the FSTLINLEN
parameter larger than LINLEN. In the example shown, it
should be 9 positions larger. You must account for how
many blanks exist between the colon and the left edge
of the paragraphs.
FMTLIN escape messages you can monitor for
------------------------------------------
TAA9895 The INPUT parameter may not be all blank
Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
INPUT The variable to be formatted. The variable must be
between 20 and 9799 bytes in length. The data
should look like a single string of text. Excess
blanks between words are squeezed out (see prior
discussion).
INPLEN The length of the data to be formatted.
The value does not have to match the actual data.
It must not exceed the length of the INPUT
parameter. The length must be between 20 and 9799
bytes.
You can have a large INPUT variable and control how
much of the value should be formatted by specifying
a shorter length. If you have a large INPUT
variable that is rarely filled, specifying the
length of the variable for INPLEN causes the FMTLIN
tool to process excessive blanks.
No error occurs if the length is less than the
actual data supplied. Truncation occurs.
LINLEN The length of the lines to be formatted. The length
must be between 20 and 200 bytes. This is also the
length of the data that you substring out to provide
for a formatted line.
All line lengths must be the same with the exception
of the first line. See the FSTLINLEN parameter.
FMTLINES The formatted lines returned in a variable. The
variable must be declared as *CHAR LEN(9999).
FSTLINLEN The length of the first line to be formatted. The
default is *LINLEN which means the same length as
specified for the LINLEN parameter.
The first line may be a different length than all of
the other lines to be formatted. It can be longer
or shorter. If you substring out of the return
variable, this must be the length of the first line.
The length must be between 20 and 200 bytes.
FMTCHAR A *YES/*NO/*IBM value that determines if any special
formatting options found in the INPUT string will be
considered. The default is *NO.
*IBM must be specified if you are displaying a system message and
want the same formatting characters as used by ADDMSGD. A LINLEN
value of 78 should be used to make the message appear the same as
DSPMSGD.
*YES must be specified if you want the special formatting options
supplied for FMTLIN.
See the prior discussion of the valid formatting options.
Restrictions
------------
** Because FMTLIN returns a variable, the command can only be
used in a CL program. The CPP can be used directly from any
HLL program.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
FMTLIN *CMD TAACLPX QATTCMD
TAACLPXC *PGM CLP TAACLPXC QATTCL
|
