III.7 Street Name Browsing and Functions BB and BF

Functions BB ("browse backward") and BF ("browse forward") enable users to include interactive street name browsing functionality in their CICS applications. These functions may be used to assist data entry staff in determining valid spellings of street names that were rejected or the spelling of which is unknown to the staff.  Functions BB and BF are supported in both the CICS and batch environments and are called using one work area.

A sequence of repeated calls to Functions BB and/or BF will browse backwards and/or forwards in alphabetical order through a list of all the valid normalized street names in a given borough. Each call to one of these functions returns up to ten names in alphabetical order. A call returns fewer than ten names if there are fewer than ten names remaining in the given borough in the given browse direction. When fewer than ten names are returned, a warning is issued.  The starting point of the browse is determined by the value of the input character string. 

Both Function BB and Function BF process an input borough code and character string, which are passed in the WA1 input Borough Code 1 and Street Name 1 fields, respectively.  The input character string can be from one to 32 bytes long. 

In addition, when issuing a COW Function BB or BF call, a user may request that either all street names, only primary street names, or only principal street names be returned. The request is made via the Browse Flag. If this flag is set to P, then only primary street names are returned. If this flag is set to F, then only principal street names are returned. Any other value causes an error message to be generated. When the principal street names are requested, the primary street names will also be returned since all primary street names are also principal street names. For more information on Primary (P) and Principal (F) street names, please refer to Chapters IV.5 and IV.6.

The list of output normalized street names in alphabetical order is returned in the WA1 output field List of Street Names. The number of names returned is returned in packed decimal format in the MSW WA1 output field Number of Street Names in List. In COW WA1 output, the Number of Street Codes and Street Names in List is returned in character format.

The List of Street Names is a 320‑byte WA1 output field containing ten 32‑byte sub-fields or ‘slots’ for normalized street names.  Let us call these sub-fields Namefield1 through Namefield10.  (Do not confuse Namefield1 with the WA1 input street name field called Street Name 1.) Each output normalized street name is returned left-justified and blank-filled within its sub-field.  When fewer than ten names are returned, the unused slots are left blank.

Function BF returns up to ten names for the given input borough, in alphabetical order, starting with the alphabetically first normalized name that is equal to or greater than the input character string.  If the input string itself is a normalized name, it is returned in Namefield1, followed by the other returned names in Namefield2, Namefield3 etc., if any.  Otherwise, the first name alphabetically greater than the input string for the given borough, if any, is returned in Namefield1, followed by the other returned names, if any.

Function BB works similarly but the list of up to ten names it returns ends with the alphabetically first name greater than or equal to the input string.  Notice that, for a given input character string, there is an overlap of one name between the sets of names returned by Functions BB and BF.

If Function BB or BF returns ten names (in sub-fields Namefield1 through Namefield10) and the user wishes to continue the browse, additional browse function calls may be issued. For Function BF, prior to the subsequent call, the user primes the WA1 input field called Street Name 1 with the street name that was returned in Namefield10. For Function BB, prior to the subsequent call, the user primes the WA1 input field called Street Name 1 with the street name that was returned in Namefield1.