SPFLite - V3.0.24069 2024-03-09

Contents of Article

Picture Strings

Special note for P'[' and P']' or P'{' and P'}'

Picture String Examples

Using Picture strings as the TO operand of a CHANGE command

SPFLite Format Change Strings

Displayable and non-displayable characters

Introduction

IBM ISPF users are familiar with Picture strings. These are used to perform pattern-matching for the search-string part of FIND and CHANGE commands, and for selectively changing text to upper-case or lower-case in the change-string part of CHANGE. Pictures are like a simple form of regular expression. When IBM first introduced them in ISPF, they were a novel and innovative feature for their time, but by today's standards they may seem quite rigid and limited. Still, because Pictures are easier to use than regular expressions, they remain useful. And, as implemented in SPFLite, they are far more useful than IBM's. SPFLite's implementation of Picture strings is more extensive than in ISPF, and includes support for the Picture-like Format string.

A picture or format string in a FIND, CHANGE, EXCLUDE, SPLIT or JOIN command allows you to search for a particular category of character, rather than looking for a specific literal character value. 

Picture and Format strings are very similar. However, Format strings may only be used as the string-2 change-string operand in CHANGE, SPLIT and JOIN commands.

The SPLIT and JOIN primary commands use some additional special characters.

New variations on P'!' now also allow you to copy arbitrary text and perform case conversion at the same time.

When a FIND or CHANGE search picture uses the special characters = or . and a character that cannot be displayed is found, that character's hexadecimal representation is used in the confirmation message that appears in the upper-right corner of the Edit or Browse screen. For example, the command FIND P'..' could result in the message CHARS X'0415' found. This change was made to be compliant with how ISPF handles this situation. 

Picture Strings

You can use special characters within the picture string to represent the kind of character to be found, as follows. Note that SPFLite does not support the ISPF APL pictures P'_' and P'÷', and will will treat these as ordinary data characters.

Special note for P'[' and P']' or P'{' and P'}'

It is possible to specify both [ and ] (or { and } ) in the same find-string Picture, when [ begins the Picture, and ] ends the Picture; that is, if you specify a Picture in the form P'[string]'. When this is done, it requests the command to search for a string which is the only data present on a line. For example, the find-string Picture P'[ABC]' will find the string ABC when it is the only data present on a line, with neither leading nor trailing spaces present.

The P'{ABC}' version would find ABC when it is the only data on a line, regardless of any leading or trailing spaces.Note:  When HILITE FIND is effect, a find picture like P'{ABC}' will cause any extra spaces on the edge of the line that correspond to a { or } Picture to be included in the string that is highlighted.

For the JOIN command, the first string operand must be a Picture string of the form P'[string' or P'string]'. 

The first string operand of JOIN can also be a Picture string of the form P'{string' or P'string}'. 

It is not possible to directly join one line to both the line that precedes it and the line that follows it, at the same time. That is to say, a from-string of a JOIN command cannot be specified in the form of P'[string]'. or as  P'{string}'. For any given line, only one JOIN, on one side of a line, is allowed. JOIN cannot perform a left-join and a right-join at the same time, since this would imply converting three lines of data into one line in a single join operation, an action that SPFLite does not support. 

A find-string written literally as P'[]' is illegal. This cannot be used to find zero-length lines, because there is literally no data to find.

Even though the new Picture codes of { and } represent optional spaces, a find-string written literally as P'{}' is also illegal because, based on the definition of these codes, one possible meaning of such a Picture is a string of zero length, which cannot be found.

  

To find a zero-length line, the command NFIND P'=' or LOCATE SIZE 0 may be used.

Picture String Examples

Using Picture strings as the TO operand of a CHANGE command 

SPFLite expands on the ISPF CHANGE Picture standard in a number of ways that make them even more useful:

• ISPF allows three types of “copy codes” in a change Picture. The = sign is used to copy a character as-is from the search string to the result string; a < sign will copy data and convert it to lower case, and a > sign will copy data and convert it to upper case. SPFLite adds a fourth “copy code” of ~ tilde. A tilde in a change Picture is used to “match against” a character in the search string, but then it will “ignore” or “discard” that character in the result string. So, a change Picture of P'=~=' will copy the first and third characters of the search string, but will skip over the second character of the search picture. The resulting string value will be 2 characters long. 

• A second extension is the picture character ! which is taken to mean the entire string located by the CHANGE function. It is not the string-1 operand of CHANGE, but is the actual value found by the command. (So, if the search operand were P'#' then then actual value found is not '#' but might be a '5'.)  It can be used multiple times in the change string if desired, to replicate the found string. If a command  CHANGE P'@@@' P'!!!'  were issued, and it located the data string ABC, the resulting string would be ABCABCABC.

• You can use change Pictures and Formats of the form P'!>',  F'!>', P'!<' and  F'!<'. These work like P'!' and  F'!' do, with the added effect of converting the result to upper or lower case afterwards. See the discussion above for details.

• The ISPF standard required that a change Picture must have exactly the same length as the search string . That prevents Pictures from being used to shorten or lengthen the value found by the search string. SPFLite relaxes this requirement. Now, a change Picture can be shorter or longer than the search string. When this is done, SPFLite does impose one requirement:  If the change Picture is longer, the positions of the change Picture that extend beyond the length of the search string cannot contain “copy codes” of = < > or ~ because there is nothing to match against. For example, you can't say CHANGE P'@@@' P'@@@=' WORD ALL, because the fourth position of the change string has an = sign, asking that the fourth character of the find string be copied. But, there is no fourth character, since the command only asked to look for strings of length 3.

• In ISPF, pattern codes like $, # and @ are allowed in search Pictures, but not in change Pictures, even though they don't really mean anything special in a change Picture. IBM just doesn't allow it. SPFLite does. Anything in a change Picture which is not one of the “copy codes” is treated as ordinary data. As noted, SPFLite allows an extended copy code of !, !> and  !< to represent the entire found string.

• SPFLite introduces the CASE primary command, which may be issued as CASE T or CASE C. When you issue this command, you will see a T or C on the status line in a little box by itself. This defines what the default case sensitivity mode is for quoted strings that don't have a T or C type code on them. In ISPF, IBM chooses to treat alphabetic characters in search Pictures as case-insensitive (like T strings), and they offer no way to change that assumption. In SPFLite, the current state of CASE defines how search Pictures are treated. So, a search Picture of P'ABC' is case-insensitive if there is a T in the status line, and is case-sensitive if there is a C there. 

Note that CASE T or CASE C affects how a search string is handled. The change string in a CHANGE command, no matter what string type, is treated as case-sensitive, in the sense that any alphabetic data you enter is used exactly as you typed it, and CASE T/C is ignored there.

• In ISPF, any character defined as a Picture code cannot be used as ordinary data. In SPFLite, you can escape any special character with a \ backslash, including the backslash itself.

SPFLite Format Change Strings

With SPFLite, a new Picture-like change string is now available: the Format string. A Format can only be used on the change-side of a CHANGE command; it cannot be used as a search string on FIND, CHANGE or any similar command. Format change strings (we'll just call them Format strings from now on) have the following properties:

• Format strings have a type code of F rather than the type code P for Pictures.

• Like Pictures, a Format string can be longer or shorter than the search string.

• The same special codes of = < > and ~ allowed in a change Picture are allowed in a change Format, and they have the same basic meaning. Also, the same characters considered as ordinary data in a change Picture are ordinary in a Format.

• Since a Format can only be used for changes, it is not affected by the state of CASE T or CASE C.

The thing that makes change Formats different than change Pictures is how the “copy codes” of = < > and ~ are “lined up” or “associated” with the search string. Here is the distinction:

• In a change Picture, a copy code of = < > or ~ in position n is used to match up to a character from the search string in that same position n. So if = is in position 3, it copies position 3 of the search string into position 3 of the result string.

• In a change Format, each copy code of = < > or ~ is effectively “enumerated” from left to right. That is, if you look at the Format string, and ignore any characters which are not a copy code of = < > or ~, then the first copy code is “code 1”, the second code is “code 2”, etc. regardless of what relative position they are in.  Then, the first copy code in the Format is matched up to position 1 of the search string;  the second copy code in the Format is matched up to position 2 of the search string; etc.

Why use Format strings?  With all the features of Picture strings, you might think that was enough. You can even insert data to the right of a found-string using a change Picture longer than the search string.

But, what if you wanted to insert something before the search string?  With Pictures, you can't do it.

Example:  I want to find all 3-letter words and put parentheses around them. Let's try it with a Picture:

       CHANGE P'@@@' P'(===)' WORD ALL

However, this won't work. Why not?  Let's match up the two strings, and see what happens. The arrows represent character matching, and the dashes represent inserted data:

       P'@@@'

         -^^^-

P'(===)'

Here, you can see where the ^ red arrow is that the third = is being matched up against a non-existent search string position, and that's illegal, even in SPFLite.

Let's try this again, using a change Format:

       CHANGE P'@@@' F'(===)' WORD ALL

This does work. Why ? Again, let's match up the two strings, and see what happens:

        P'@@@'

         -^^^-

P'(===)'

Here, the second character in the Format is the first copy code. Enumerating the copy codes, that corresponds to position 1 of the search string. The same holds for the other = signs. So, if CHANGE finds a word like ABC, it will change it to (ABC) and XYZ will be changed to (XYZ).

Suppose you wanted to change a word like ABC into (A/B/C) ?  Easy. Just put the slashes in the format to insert them:

       CHANGE P'@@@' F'(=/=/=)' WORD ALL

Note that in the Format, the = signs are in relative positions 2, 4 and 6, but since we enumerate them, and we aren't looking at their positions in the Format string, the = sign in position 2 is the first = sign, so it copies position 1; the second = in position 4 copies position 2, and the third = in position 6 copies position 3.

Any time you need to insert data before or in the middle of the search string, Format is what you want. If you want to insert after, either Format or Picture should work fine.

Note: When a Format string contains the "copy entire string" codes of F'!', F'!>' or  F'!<', the copying operation for these codes is done independently of any copy codes of = < > or ~ that may be present in the Format string. The F'!', F'!>' or  F'!<' codes do not count when considering the enumeration of characters in the found-string.

Why didn't we just make Pictures work the same as Formats, and be done with it?  Because, for people who make extensive use of Pictures, Formats don't really work exactly the same way as Pictures, and we didn't want to cause confusion or break old editing habits if it wasn't necessary to do so.

Displayable and non-displayable characters

The picture character P'.' (period) requests a search for non-displayable characters. Depending on the font you are using, particularly when national characters are involved, deciding what is non-displayable can be confusing. SPFLite provides you with the ability to specifically indicate what characters you wish to consider displayable. 

The Options - General settings page allows you to alter what these characters are. See Options - General for how this is changed. 

Note that the Normal Characters on that screen define what the P'.' picture does not match to. Be careful not to get this point confused.

The non-displayable picture concept comes from IBM's ISPF that originally ran on 3270 terminals, which have far fewer displayable characters in EBCDIC than PCs do using the ANSI character set. A 3270 terminal would "lock up" if non-displayable characters were written to the screen, but this will not happen in SPFLite. Because of this, the issue of non-displayable characters is of less importance to an SPFLite user than it would be to an IBM ISPF user. 

The  P'.'  Picture code is provided for ISPF compatibility, but you may not have extensive need for it. If you chose to, you could probably define the Normal Characters string so that a P'.' Picture would detect essentially the same unprintable characters that it would on the mainframe. However, it would be very unusual to try to emulate a mainframe 3270 in this manner.

Created with the Personal Edition of HelpNDoc: Enhance Your Documentation with HelpNDoc's Advanced Project Analyzer