Specifying a Picture or Format String

Contents of Article


Introduction

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.


P'='

Any character


P'^' or P'¬'

Any character that is not a blank.  Both P'^' and P'¬' work identically.


Note that ¬ can be either the ANSI ¬ character (X'AC') or the the OEM ¬ character (X'AA').  You should select the character that displays properly with your chosen editor font, but either one will work.


P'#'

Any numeric character, 0-9

Note that the three special superscript characters in ANSI for ¹, ² and ³ are not considered numeric.


P'-'

Any non-numeric character. which is any character not matching a Picture of P'#'


P'.'

Any non-displayable character; that is, any character not in the Normal list in Global Options


P'@'

Any alphabetic character, uppercase or lowercase.  This includes the non-English letters in the ANSI character set.


P'<'

Any lowercase alphabetic character.  This includes the non-English letters in the ANSI character set.


P'>'

Any uppercase alphabetic character.  This includes the non-English letters in the ANSI character set.


P'$'

Any special character, neither alphabetic nor numeric.  


P'%'

Any character not defined in the WORD setting.  i.e. a delimiter.


P'&'

Any character defined in the WORD setting.  A span of P'&' characters would be a "user-defined word".


P'!'






P'!='

Allowed only in the change-string.  It represents the entire string value actually found (not the string-1 operand), regardless of its length.  It is allowable to use the ! code multiple times in the change-string; if done, the found string is repeated in the result as many times as the ! code is used.


The found string is copied as-is without case conversion.


A Picture of P'!' may be specified as P'!=' with essentially identical meaning.  P'!=' would only be used in cases where a Picture of P'!' needed to be followed by a Picture of P'>' or P'<' to mean that (a) a found string is copied as is, and then (b) an individual copied character is converted to upper or lower case.  The P'!='  notation is like an "escape" that prevents the ! from being confused with P'!>' or P'!<'.


P'!>'






P'»'

Allowed only in the change-string.  It represents the entire string value actually found (not the string-1 operand), regardless of its length.  It is allowable to use the !> code multiple times in the change-string; if done, the found string is repeated in the result as many times as the ! code is used.


The found string is copied and converted to upper case.


If desired, P'!>' can be shortened to P'»' if the » character is mapped to some key, so that it can be typed on the command line.


Note that » can be either the ANSI » character (X'BB') or the the OEM » character (X'AF').  You should select the character that displays properly with your chosen editor font, but either one will work.


P'!<'






P'«'

Allowed only in the change-string.  It represents the entire string value actually found (not the string-1 operand), regardless of its length.  It is allowable to use the !< code multiple times in the change-string; if done, the found string is repeated in the result as many times as the ! code is used.


The found string is copied and converted to lower case.


If desired, P'!<' can be shortened to P'«' if the « character is mapped to some key, so that it can be typed on the command line.


Note that « can be either the ANSI « character (X'AB') or the the OEM « character (X'AE').  You should select the character that displays properly with your chosen editor font, but either one will work.


P'['

In a search string, P'[' is used to represent the left-hand edge of a line.  When used this way, the [ code must appear left-most in the Picture string, and there must not be any other [  codes present in the Picture, unless escaped as \[.  Because the [ code represents the edge of a line, and not an actual data character value, there must be at least one other character in the string, such as P'[ABC'.   A find-string written literally as P'[' is illegal.  


In a change-string, a Picture or Format of P'[' is treated as ordinary data.


P']'

In a search string, P']' is used to represent the right-hand edge of a line.  When used this way, the ] code must appear right-most in the Picture string, and there must not be any other ]  codes present in the Picture, unless escaped as \].  Because the ] code represents the edge of a line, and not an actual data character value, there must be at least one other character in the string, such as P'ABC]'.   A find-string written literally as P']' is illegal.  


In a change-string, a Picture or Format of P']' is treated as ordinary data.


P'{'

In a search string P'{' is used to represent the left-hand edge of a line including any optional leading blanks.  When used this way, the { code must appear left-most in the Picture string, and there must not be any other {  codes present in the Picture, unless escaped as \{.  Because the { code represents the logical left edge of a line, and possibly not an actual data string (since the optional blanks may not be present), there must be at least one other character in the string, such as P'{ABC'. A find string written literally as P'{' is illegal.  When a successful find occurs, the effective length of the 'found' string includes the leading spaces, if present.


In a change string, a Picture or Format of P'{' is legal, and is treated as a variable number of spaces equal to the leading spaces found by the accompanying search-string, and may be of zero length.  The change Picture or Format of P'{' is somewhat similar to the change Picture or Format of P'!' in that it represents a variable number of characters, and can appear anywhere in the change string, even multiple times.  When the { code is used in a change string Picture or Format, and there is no associated { code in the find picture, the { code on the change side represents a zero-length string.


P'}'

In a search string  P'}' is used to represent the right-hand edge of a line including any optional trailing blanks.  When used this way, the } code must appear right-most in the Picture string, and there must not be any other }  codes present in the Picture, unless escaped as \}.  Because the } code represents the logical right edge of a line, and possibly not an actual data string (since the optional blanks may not be present), there must be at least one other character in the string, such as P'ABC}'. A find string written literally as P'}' is illegal.  When a successful find occurs, the effective length of the 'found' string includes the trailing spaces, if present.


In a change string, a Picture or Format of P'}' is legal, and is treated as a variable number of spaces equal to the trailing spaces found by the accompanying search-string, and may be of zero length.  The change Picture or Format of P'}' is somewhat similar to the change Picture or Format of P'!' in that it represents a variable number of characters, and can appear anywhere in the change string, even multiple times.  When the } code is used in a change string Picture or Format, and there is no associated } code in the find picture, the } code on the change side represents a zero-length string.


P'|'

In the change-string Picture of a SPLIT primary command, P'|' is used to represent a line-break, where the line is to be split in two.  For SPLIT, the contents of the change-string completely replace the find-string.  It is possible to delete the entire find-string and replace it by a line-break by having a change-string written literally as P'|' as the only Picture code present.


For commands other than SPLIT, a change-string Picture containing P'|' is ignored, and will neither be used for line-splitting purposes nor as a literal '|' character.  If you wish to have a change-string Picture contain a literal '|' character, it must be escaped as P'\|'.


P'\x'        

The \ backslash is used to escape a character that might otherwise be used as a special Picture code, like $.  For example, P'@#' is used to find to a letter followed by a digit, whereas P'\@#' is used to find to an @ sign followed by a digit.  When \ backslash is doubled as \\ or is used as the last character of a Picture string, it is taken literally as a single \ backslash data character.  When \ backslash precedes a letter, the letter is taken literally; that is, it matches exactly in case, even when CASE T is in effect.



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




  • To find a string of 3 numeric characters:  


       FIND P'###'  


 


  • To find any 2 characters that are not blanks but are separated by a blank:  


       FIND P'^ ^'  


 


  • To find a blank followed by a numeric character:  


       FIND P' #'  


 


  • To find a numeric character followed by AB:  


       FIND P'#AB'  


 


  • To find the next character in column 72 that is not a blank:  


       FIND P'^' 72  


 


  • To change any characters in columns 73 through 80 to blanks:  


       CHANGE ALL P'=' ' ' 73 80  


 


  • To find the next line with a blank in column 1 and a character in column 2 that is not a blank:  


       FIND P' ¬' 1  



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:








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.



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:






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:




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: Create help files for the Qt Help Framework