Working with Enumerations

Contents of Article

Introduction

Combining Fast Enumeration with Line Exclusion

Enumeration patterns

Examples

Handling of blanks in the prefix

Use of the ENUMWITH command

Application Note: Using a keyboard macro to automatically insert sequence numbers


Introduction


The Enumerate Facility allows a selected set of columns in a range of lines to be enumerated, that is, sequenced starting from an initial value on the first line and incremented for each subsequent line, within a fixed field on a set of lines.  Enumeration values are always right-justified within the field.  The increment amount defaults to 1 and can be changed with the ENUMWITH primary command; see discussion below.  


There are two kinds of enumeration that you may perform:


Power Enumeration



Fast Enumeration



When these conditions are true, a mapped Enumerate keyboard primitive command can be issued.  If the requisite conditions are not present, attempting these commands will result in an error message.  The Enumerate commands that you can map to a key are the following:



The two hex enumeration functions control how digits A-F should be cased, where (EnumHexLc) makes digits greater than 9 in lower case, and (EnumHexUc) makes them upper case.  Based on user preference, it is likely that a given user would only select one of these two functions on a regular basis.


The highlighted field on the first line of selected text constitute the ‘initial' or ‘base' value of the enumeration, defining the first value in the sequence.  All subsequent lines (in increasing line number order) in the line range are incremented for each new line.


If a Power Typing range is being used, it might not consist of physically adjacent lines, such as when X | NX or U | NU is specified, or a range of tagged lines is specified. The enumeration only applies to the selected lines, and has no bearing on the physical line numbering involved.  So if physical lines 1 and 7 are being ‘Power Typed' (but not the lines between them) and an enumeration starts at line 1 begins with a base value of 5001 and an increment of 1, line 7 gets the second enumeration value of 5002, not the seventh one which would have been 5007.


Combining Fast Enumeration with Line Exclusion


If you would like to quickly enumerate many lines, but also want to convenience of the Fast Enumeration method, you can exclude the majority of the affected lines, leaving only the first and last ones visible.  Then, set up your model line, and enumerate the range.  You will see the full range enumerated once you unexclude them.


Example:  Lines 1 to 5 need to be enumerated.  (The example is small, but imagine if you had hundreds or thousands of lines; the same method would still work.)  Lines 2-4 are excluded, line 1 is set up as the model line, a starting value is created, and then the entire line range is highlighted.  This works because the text-selection highlighting is also applied to all the lines within the the excluded range.  Notice on the status line the size of the selected area is a length of 3 characters wide by  5 lines (Len 3 x 5), even though you only physically selected 3 lines.



Then, issue the desired enumeration function as you have mapped it.  You will see the final line containing 005 as expected:



Finally, unexclude the lines to see all of them:




Enumeration patterns


The highlighted field on the first line defines a pattern used to describe how the enumeration process is to be done, in addition to providing an initial starting value.  Enumerated values are assigned in ascending order by incrementing the starting value for each new line where subsequent enumeration values are stored.  The enumeration pattern is in the form  prefix  digits  suffix, where the prefix and suffix are optional.


prefix

The optional prefix may consist of any string of characters (including digits characters themselves) as long as the last character is a non-digit.  Neither (EnumHexUc) nor (EnumHexLc) will adjust the casing of the prefix string; the value is left as-is.  (For example, if you had a prefix of 0x in a C program, (EnumHexUc) will not change 0x into 0X.)


digits

For (Enum), digits are the characters 0-9.  


For (EnumHexUc) and (EnumHexLc), digits are the characters 0-9, A-F and a-f.


At least one digit must be present.  The digits value may contain a maximum of 9 full decimal digits or 8 hex digits, since the underlying arithmetic to increment values is done with 32-bit integers.  The maximum decimal value is 4294967295 and the maximum hex value is FFFFFFFF.  If the maximum value is reached and there are more lines to be enumerated, the number value wraps around to zero.


If sufficient data lines are enumerated to cause a maximum value to be developed (such as 999 in a 3-position decimal field) then the value will wrap around to zero and continue forward.


If a wrap-around-to-zero occurs, the zero and positive values will not have any leading zeros.  If an exact size or number of leading zeros is required and wrap-around may occur, you may wish to perform the Enumeration in two steps; one from the initial value to the maximum value, followed by zero to the final value.  Another approach is to allow the Enumeration function to operate over the entire range, and the overlay a line containing 0 characters in the required positions.  The overlay command will only replace blanks with zeros, and so you can safely pad an Enumeration value to any number of desired leading digits.


The function (EnumHexUc) will adjust all digits greater than 9 to upper case A-F, even on the first (model) line. The function (EnumHexLc) will adjust all digits greater than 9 to lower case a-f, even on the first (model) line.


suffix

The optional suffix may consist of any string of non-digit characters.  Neither (EnumHexUc) nor (EnumHexLc) will adjust the casing of the suffix string; the value is left as-is.



Examples


the prefix is  16#, the digits value is FF and the suffix value is #


the prefix is  0x, the digits value is FF and there is no suffix


the prefix is  &H, the digits value is 123 and there is no suffix


the prefix value is  X',  the digits value is FF and the suffix value is '


the prefix value is  Page.. (note that . represents blanks), the digits value is 1, and there is no suffix


Handling of blanks in the prefix


The enumerate function will utilize blanks in the prefix to accommodate changes in length of the digits string as enumeration takes place.  This is done to retain formatting as much as possible.   Some examples of how this works (note that . represents blanks):


...&Hff        enumerates as        ...&Hff        ..&H100        ..&H101        etc.


Page..8        enumerates as        Page..8        Page..9        Page.10        etc.


..(98)        enumerates as        ..(98)        ..(99)        .(100)        etc.


(..98)        enumerates as        (..98)        (..99)        (.100)        etc.


Use of the ENUMWITH command


Normally, the (Enum), (EnumHexUc) and (EnumHexLc) functions increment each successive line by 1.  You can change the increment value to something other than 1 by using the ENUMWITH primary command.  When you do this, the increment value applies to all edit sessions until you change it, but it will reset back to 1 when SPFLite is restarted.  See ENUMWITH - Change Increment for Enumerate Functions for more information.


Application Note: Using a keyboard macro to automatically insert sequence numbers


You may a file containing a fixed column of sequence numbers that need to be frequently renumbered.  IBM ISPF has several "numbering" commands, such as AUTONUM, NUMBER, NONUMBER, RENUM and UNNUMBER.  Because PC data is not generally "card-image based", like mainframe data, SPFLite does not support these commands.  However, you can use the Enumerate feature of Power Typing to place (or remove) sequence numbers anywhere you wish.


You can automate the process of resequencing a file by placing the operation into a keyboard macro.  Here is the general outline of how you could do this:



Suppose the data you want to resequence was a COBOL program that uses columns 1-6 for sequence numbers.  Here is a macro that would enumerate columns 1 to 6.  Let's assume you are going to map this to Ctrl-Shift N.  So, you would enter KeyMap, and in the Ctrl-Shift N item, you would enter the following:


      (TxtHome)[000001](Left)(6:MarkLeft)(Enum)(Enter)


Here's what happens when you run this macro:


(TxtHome)

The cursor is placed in column 1 of the model line


[000001]

The initial value of the sequence gets stored in columns 1-6 of every line in the Power Typing range


(Left)

The cursor is moved from column 7 to column 6


(6:MarkLeft)

Columns 1-6 are highlighted, going in reverse order


(Enum)

All lines in the Power Typing range are numbered


(Enter)

This ends the Power Typing session


Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor