APPENDIX 12: CHARACTER-ONLY WORK AREAS (COW)

Introduction

Important Note: As of January 1, 2020, Mainframe-Specific Work Areas (MSWs) will no longer be supported. It is therefore essential that users convert their MSW applications to the COW format.

This appendix is based on Geosupport System Technical Bulletin 02-01 (dated 15 November 2002) and Geosupport Technical Bulletin 02-01 Addendum (dated 22 November 2002). It contains information needed to create Geosupport applications using the Character-Only Work Areas (COWs). Included are the following topics:

  • Comparison of COWs and Mainframe-Specific Work Areas (MSWs)
  • Considerations when using COWs
  • Work Area Lengths
  • Specifying the Work Area Format
  • GBAT Considerations
  • COW COPY Files

Notes:

  1. There are two versions of the sample programs in Appendix 5 of this User Programming Guide. One version is for MSWs and the other is for COWs. When coding, bear in mind the differences between COWs and MSWs.

  2. The Work Area Layouts in Appendix 2 of this User Programming Guide are the layouts of the MSWs. For the COW layouts, see Appendix 13.

  3. The COPY files that are printed in Appendix 5 of this User Programming Guide are for the Mainframe-Specific Work Areas (MSWs). For the COW COPY files, see Appendix 14.

Overview

Standard work areas with pre-defined layouts are used to pass data between the Geosupport System and user-developed application programs. The same work areas are also used by GBAT, the Geosupport batch utility program, to pass data to and from Geosupport.

The Geosupport work areas that have long been in use are called the Mainframe-Specific Work Areas (MSWs). Most of the MSWs contain one or more packed decimal fields, a data encoding schema unique to IBM mainframes. This appendix discusses an alternative set of Geosupport work areas called the Character-Only Work Areas (COWs) which, as the name implies, contain character fields only. The introduction of the COW is an essential part of a long-term effort to port the Geosupport System to other platforms.

Each specific Geosupport work area (for example, Work Area 2 for Function 3S) has both a COW version and an MSW version. User-written application programs running on mainframes now have the option to use either set of work areas when making calls to Geosupport. GBAT users can also specify the use of either set of work areas.

From now on, all new applications should be designed to use the COWs. We also recommend that all existing applications be converted to use the COWs. Although the MSWs will continue to be supported, as of some future date (not yet determined), only the COWs will be enhanced with new data items and functionality. Eventually, the MSWs may be de-supported.

Comparison of COWs and MSWs

Each non-character field in an MSW has a character field counterpart in the corresponding COW. Except for an item called the HND (discussed below in the sub-section on house number fields), each character field in an MSW appears in identical form in the corresponding COW. However, corresponding fields do not necessarily occupy the same byte positions or occur in the same order in the corresponding MSW and COW. In designing the COWs, the opportunity has been taken to reorganize the layouts to situate related fields near each other and to increase the amount of filler space available for adding new data items in the future.

The data items for which the MSWs contain non-character fields are house numbers, street codes, segment lengths, and count fields. Each of these is discussed in detail below.

House Number Fields. The Geosupport System uses three different formats for standardized or ‘normalized’ house numbers: the House Number in Display format (HND), the House Number in Internal format (HNI), and the new House Number in Sort format (HNS).

  • The HND is a character item that is present in both the COWs and the MSWs, but it has a different length in each: 16 bytes in the COWs and 12 bytes in the MSWs. The length of the HND was increased in the COWs to insure that house numbers having suffixes fit within the HND field without the suffix having to be abbreviated. (House number suffixes are certain character strings that occur at the ends of some New York City house numbers, such as 1/2, 1/4, REAR, GARAGE.) For compatibility with MSW, by default Geosupport uses only the first 12 characters of the 16-byte COW HND. The remaining 4 characters are blank. To use all 16 characters, the user can specify an HNL (House Number Length) of 16.

  • The HNI is a six-byte data item with a hybrid format: the first five bytes are in packed decimal format, and the sixth byte contains a binary value. HNIs occur only in the MSW.

  • The HNS is a new 11-byte item that is the character equivalent of the HNI in the COWs.

The HND is the appropriate format for displaying house numbers on application screens, reports and computer-generated maps, and is specifically designed for that purpose. In particular, the HND is left-justified and space-filled. However, the HND renders unsatisfactory results when used as a field to sort addresses. For example, it would, inappropriately, cause 102 MAIN STREET to sort ahead of 98 MAIN STREET.

In contrast to the HND, both the HNI and the HNS are suitable to use as fields to sort addresses. For example, both would, appropriately, cause 98 MAIN STREET to sort ahead of 102 MAIN STREET. However, neither the HNI nor the HNS is suitable for display:

  • The HNI is not a character item and so cannot be displayed as intelligible data unless first converted to character format. Any of the Geosupport display functions (Functions D, DG and DN) can be used with the MSWs to convert an HNI to an HND.

  • The HNS, although it is a character item, is unsuitable for display. In particular, the HNS is in an internal format with a unique layout and flags. If the house number has a suffix, the HNS does not contain the suffix itself, but instead, contains a code for the suffix meaningful only to the Geosupport software. Any of the Geosupport display functions (Function D, DG and DN) can be used with the COWs to convert an HNS to an HND.

To reiterate, the HND should be used for display, and the HNI (in MSWs) or the HNS (in COWs) should be used for sorting.

Street Code Fields. A notable feature of the Geosupport System is its set of numeric street codes assigned to the names of New York City streets and selected non-street geographic features. The street code feature provides specialized capabilities that are essential for certain types of applications.

Street codes appear in several forms in the Geosupport work areas. In many of the MSWs, there are four-byte fields for a packed decimal data item called the Packed Borough and 5-Digit Street Code (PB5SC). The COW counterparts of PB5SC fields can take one of the following three forms:

  • A six-byte field for an item called the Borough and 5-Digit Street Code (B5SC). This is simply the unpacked version of the PB5SC

  • The first six bytes (constituting the B5SC) of an eight-byte field for an item called the Borough and 7-Digit Street Code (B7SC)

  • The first six bytes (constituting the B5SC) of an 11-byte field for an item called the Borough and 10-Digit Street Code (B10SC)

Segment Length Fields. Both Work Area 2 for Function 3 and Work Area 2 for Function 3C contain fields for the segment length expressed in feet. In the MSW format, these are 3-byte packed decimal fields. In the COW format, they are 5-byte character fields.

Count Fields. Some count fields, e.g. Number of Street Names in List, are packed decimal fields in the MSW format, and character fields in the COW format.

Consideration When Using the COWs

The Long Work Area 2 option that is available when using the MSWs is occasionally not needed or not supported when using the COWs, as follows:

  • When using the COWs, Functions 1, 1E and 3 do not have the long Work Area 2 option. This option is unnecessary in these cases, since the COW versions of the regular Work Area 2s for these functions already accommodate all the requisite fields. However, Functions 1A and BL continue to have the long Work Area 2 option when COWs are used. (See Chapter II.5 for a general discussion of the long Work Area 2 option.)

Work Area Lengths (COWs and MSWs)

The following table lists the lengths of the members of both sets of work areas. Note that the lengths of corresponding members from the two sets differ in most cases.

Table A12-1: Lengths of Work Areas (COWs and MSWs)
Work Area Length of COW Length of MSW
Work Area 1 (used with all functions) 1200 884
Regular WA2 for Functions 1, 1E 300 200
Long WA2 for Functions 1, 1E N/A 300
Extended WA2 for Functions 1, 1E 1500 NA
Regular WA2 for Functions 1A, BL, BN 1363 939
Long WA2 for Functions 1A, BL 17750 17683
Extended WA2 for Functions 1A 2800 NA
WA2 for Function 1B 4300 N/A
WA2 for Function 2 200 200
Regular WA2 for Function 3 450 200
Long WA2 for Function 3 N/A 300
Extended WA2 for Function 3 1000 N/A
Auxiliary Segment WA2 for Function 3 950 N/A
Extended WA2 with Auxiliary Segment for Function 3 1500 N/A
WA2 for Function 3C 300 200
Auxiliary Segment WA2 for Function 3C 800 N/A
Extended WA2 with Auxiliary Segment for Function 3C 1350 N/A
Regular WA2 for Function AP 1363 N/A
Extended WA2 for Functions AP 2800 N/A
WA2 for Function 3S 19274 4224

Specifying a Work Area Format (COW or MSW)

To indicate which set of work areas is being used in a call to Geosupport, an application program uses a new field called the Work Area Format Indicator. This field is one byte long and is located at position 213 of both the COW Work Area 1 and the MSW Work Area 1.

  • The value ‘C’ in the Work Area Format Indicator indicates to Geosupport that COWs are being used for the given call.

  • A blank in the Work Area Format Indicator indicates that MSWs are being used.

  • If the Work Area Format Indicator is invalid, the call is rejected with a Geosupport Return Code of 27 and an appropriate message.

Since every call to Geosupport is an independent event, application programs must insure that the Work Area Format Indicator is appropriately set for each call; Geosupport doesn’t ‘remember’ previous calls.

Note that the MSWs are the default work areas, that is, the work areas that Geosupport expects when the Work Area Format Indicator is blank. Therefore, existing applications that use the MSWs will continue to execute properly without modification, provided Work Area 1 is being passed to Geosupport with position 213 containing a blank. (As a matter of course, every application program should be designed so that, each time a call to Geosupport is to be made, the program clears Work Area 1 entirely to blanks prior to moving the input data for that call into the requisite Work Area 1 fields. This insures that Work Area 1 will not be ‘polluted’ by stray input data lingering from a previous call.)

GBAT Considerations for COWs

When executing GBAT, the set of work areas that are used affects the length and format of the records written into OUTFILE (the output file of successfully processed data records).

To specify the set of work areas GBAT is to use, the user codes a control entry in CARDIN (the input control file) containing the keyword WORKAREA, as follows:

  • WORKAREA=COW specifies the COWs.

  • WORKAREA=MSW specifies the MSWs.

  • (Default:) If no WORKAREA control entry is coded, GBAT uses the MSWs.

Since the MSWs are GBAT’s default set of work areas, existing GBAT jobs will continue to execute properly without modification.

When COWs are used, GBAT options that involve processing packed decimal input data are, of course, invalid. Specifically, the following control entries or control entry variable values are invalid when COWs are being used:

  • HNI=YES is invalid.

  • In the control entries STRTCODE, CRSCOD1 and CRSCOD2, the values 3 and 4 are invalid for the length variable.

  • If MSWs are being used, the default is 1ABLVERSION=L (or 1ABLVERSION=LEGACY), which results in an error, since Legacy is no longer supported.

GBAT forms each OUTFILE record by appending Geosupport information to a copy of the data input record. The information that is appended is determined by three factors: the set of work areas being used, the function being executed and the value of the GEOCODE control entry that is in effect. The GEOCODE value affects the appended information as follows:

  • When GEOCODE=NO, the appended items consist only of selected output items from Work Area 1 (and, in case of MSW Functions 1, 1A, and 1E, an item created by GBAT called the HNHPD). See Table A12-2 below for lists of the appended COW items and their lengths by function and set of work areas. For MSW format, see Table 9-4 and Table 9-5.

    When GEOCODE =YES the appended information consists only of work area 2 in its entirety. Table A12-1 above lists the lengths of these work areas by function and work area format. Appendix 2 contains the MSW Work Area Layouts and Appendix 13 contains the COW Work Area layouts.

  • When GEOCODE=ALL, the appended information consists of the data for GEOCODE=NO followed by the data appended for GEOCODE=YES. Table A12-3 lists the lengths of the appended information by function and set of work areas. These lengths typically are the sums of the corresponding lengths listed in Table A12-1 and Table A12-2(and A12-2A if GEOUNIT=YES).

YES and ALL are invalid GEOCODE options for Functions 1N, D, DG and DN, since these functions do not have a Work Area 2.

The information appended for GEOCODE=NO is as follows.

  • For the functions that allow an input house number other than the display functions (viz. Functions 1, 1A, 1B and 1E): the appended information includes normalized house number items as follows:

    • If COWs are being used, the HND and the HNS are appended.

    • If MSWs are being used, the HND and an 8-byte item called the HNHPD are appended. The HNHPD is a normalized house number created by GBAT in a special format for use only by the Department of Housing Preservation and Development.

  • For the display functions (Functions D, DG and DN), which allow input house numbers in the form of HNIs when using MSWs: the appended information includes the normalized house numbers only in the HND format for a length of 12.

  • For the display functions (Functions D, DG and DN), which allow input house numbers in the form of HNSs when using COWs: the appended information includes the normalized house numbers only in the HND format for a length of between 12 and 16.

  • For the functions that involve input street names (Functions 1, 1A, 1B, 1E, 1N, 2, 3, 3C, 3S, D, DG and DN): the appended information includes normalized street name(s) and street codes, as follows:

    • Regardless of which set of work areas is being used, normalized street names are provided in 32‑byte fields, left-justified and blank‑filled.

    • If COWs are being used, street codes are provided as B10SCs, an 11-byte item.

  • If MSWs are being used, street codes are provided as 10SCs (ten‑digit street codes without a borough code), a 10-byte item.

  • For Function BL: the appended information when 1ABLVERSION=STANDARD is specified consists of the standard 10-byte BBL, which is composed of the one-byte borough code followed by the five-byte tax block followed by the four-byte tax lot. Note: STANDARD is the only valid value for 1ABLVERSION.

  • For Function BN: the appended information consists of ten bytes containing the seven-byte Building Identification Number (BIN) followed by a three-byte filler.

Table A12-2 below lists the appended items when GEOCODE=NO, itemized by function and set of work areas. When an item of appended data has no value for a particular record (such as a house number item, when the input location is a non-addressable place name), the given field is still present in the appended data but it contains all blanks. The only exception to this involves the display functions (D, DG and DN) when using MSWs, where there is no field for the second house number unless it is provided as an input datum by the user.

Table A12-2A, which follows Table A12-2, lists the additional appended items when GEOUNIT=YES. Note that that the GEOUNIT option is for COW only. The GEOUNIT items are appended in the output file record immediately after the GEOCODE=NO items (when GEOCODE=NO or GEOCODE=ALL).

Table A12-2: GBAT-Appended Items when GEOCODE=NO (COWs and MSWs)
See Table A12-2A for additional GBAT-Appended Items when GEOUNIT=YES(COW Only)

Functions
[Options]
COWs MSWs
Appended Items Length Appended Items Length
1, 1A, 1B15, 1E, AP16 HND 16 HND 12
HNS 11 HNHPD 8
Normalized Street Name 32 Normalized Street Name 32
B10SC 11 10SC 10
Total Length: 70 Total Length: 62
1N Normalized Street Name 32 Normalized Street Name 32
B10SC 11 10SC 10
Total Length: 43 Total Length: 42
2 Normalized Street Name-1 32 Normalized Street Name-1 32
B10SC-1 11 10SC-1 10
Normalized Street Name-2 32 Normalized Street Name-2 32
B10SC-2 11 10SC-2 10
Total Length: 86 Total Length: 84
2 - NODE input Filler 86 Invalid
Total Length: 86
3, 3C, 3S Normalized Street Name-1 32 Normalized Street Name-1 32
B10SC-1 11 10SC-1 10
Normalized Street Name-2 32 Normalized Street Name-2 32
B10SC-2 11 10SC-2 10
Normalized Street Name-3 32 Normalized Street Name-3 32
B10SC-3 11 10SC-3 10
Total Length: 129 Total Length: 126
AP See 1, 1A, 1E, 1B, AP above 70 Invalid
Total Length: 70
BL (Standard) BBL: BBL:
Borough Code 1 Borough Code 1
Tax Block 5 Tax Block 5
Tax Lot 4 Tax Lot 4
Total Length: 10 Total Length: 10
BL (Legacy) Invalid Invalid
BN BIN 7 BIN 7
Filler 3 Filler 3
Total Length: 10 Total Length: 10
D, DG, DN [HOUSENUM2 control entry not coded] HND-1 16 HND 12
Normalized Street Name-1 32 Normalized Street Name-1 32
Normalized Street Name-2 32 Normalized Street Name-2 32
Normalized Street Name-3 32 Normalized Street Name-3 32
HND-2 16
Total Length: 128 Total Length: 108
D, DG, DN [HOUSENUM2 control entry coded] HND-1 16 HND-1 12
Normalized Street Name-1 32 Normalized Street Name-1 32
Normalized Street Name-2 32 Normalized Street Name-2 32
Normalized Street Name-3 32 Normalized Street Name-3 32
HND-2 16 HND-2 12
Total Length: 128 Total Length: 120

Table A12-2A: Additional GBAT-Appended Items when GEOUNIT=YES (COW only)

Functions
[Options]
COWs
Appended Items Length
1, 1E, 1A, 1B Normalized Display-Format Unit Output 14
Filler 56
Total Length: 70

Table A12-3 lists the length of the data appended by GBAT, itemized by function and option within function, GEOCODE value and set of work areas being used.

Note: CROSSSTNAMES=YES For Functions 1, 1E, 1B, 2, 3 and 3C, when GEOCODE=ALL (and, optionally, GEOUNIT=YES) and CROSSSTNAMES=YES, the appended data consist of the concatenation of the GEOCODE=NO data, (followed, optionally, by GEOUNIT=YES data,) followed by a 320-byte block of data containing cross street names, followed by the GEOCODE=YES data. For further information about the layout of the appended CROSSSTNAMES data, refer to the Appendix 3 entry for the List of Street Names (see paragraph on List of Cross Street Names).

Table A12-3: Length of GBAT‑Appended Data (COWs and MSWs)
Note: The data is appended to the user’s input record

Functions Options 17 GEOCODE=NO GEOCODE=YES GEOCODE=ALL
COWs MSWs COWs MSWs COWs MSWs
1, 1E LONGWA2=NO 70 62 300 200 370 262
LONGWA2=NO
GEOUNIT=YES
140 Invalid Invalid Invalid 440 Invalid
LONGWA2=YES Invalid Invalid Invalid 300 Invalid 362
MODE=X Invalid Invalid 1500 Invalid 1570 Invalid
MODE=X GEOUNIT=YES Invalid Invalid Invalid Invalid 1640 Invalid
1A LONGWA2=NO 70 62 1363 939 1433 1001
LONGWA2=NO, GEOUNIT=YES 140 Invalid Invalid Invalid 1503 Invalid
LONGWA2=YES Invalid Invalid 17750 17683 17820 17745
LONGWA2=YES, GEOUNIT=YES Invalid Invalid Invalid Invalid 17890 Invalid
MODE=X, LONGWA2=NO Invalid Invalid 2800 Invalid 2870 Invalid
MODE=X, LONGWA2=NO, GEOUNIT=YES Invalid Invalid Invalid Invalid 2940 Invalid
1B Invalid Invalid 4300 Invalid 4370 Invalid
GEOUNIT=YES Invalid Invalid Invalid Invalid 4440 Invalid
1N 43 42 Invalid Invalid Invalid Invalid
2 86 84 200 200 286 284
RELATEDNODES = YES (ERRFIL3) Invalid Invalid 3352 Invalid 3352 Invalid
3 LONGWA2=NO with AUXSEG=NO 129 126 450 200 579 326
LONGWA2=YES Invalid Invalid Invalid 300 Invalid 426
AUXSEG=YES Invalid Invalid 950 Invalid 1079 Invalid
MODE=X Invalid Invalid 1000 Invalid 1129 Invalid
MODE=X with AUXSEG=YES Invalid Invalid 1500 Invalid 1629 Invalid
3C AUXSEG=NO 129 126 300 200 429 326
AUXSEG=YES Invalid Invalid 800 Invalid 929 Invalid
MODE=X Invalid Invalid 850 Invalid 979 Invalid
MODE=X with AUXSEG=YES Invalid Invalid 1350 Invalid 1479 Invalid
3S 129 126 19274 4224 19403 4350
AP 70 Invalid 1363 Invalid 1433 Invalid
MODE=X Invalid Invalid 2800 Invalid 2870 Invalid
BL LONGWA2=NO 10 10 1363 939 1373 949
LONGWA2=YES Invalid Invalid 17750 17683 17760 17693
MODE=X, LONGWA2=NO Invalid Invalid 2800 Invalid 2810 Invalid
BN 10 10 1363 939 1373 949
MODE=X Invalid Invalid 2800 Invalid 2810 Invalid
D, DG, DN HOUSENUM2 not coded 128 128 128 Invalid Invalid Invalid
HOUSENUM2 coded 128 120 Invalid Invalid Invalid Invalid

COPY Files for COWs

For COBOL, PL/1, BAL and C programmers, copy files have been created to enable you to easily use the new work areas (COWs) in your programming work. Local Data Areas will be available for Natural programmers. If you use the MVSP LPAR at DoITT, these items will be found in library ‘A030.GEO.COPYLIB’. If you use any other LPAR at DoITT or if you work at a different data center, contact your system programming staff to learn the name of the library in which these members are stored. The following table shows you the copy file name by language and Geosupport Function.

Table A12-4: List of COPY Files for COWs

Language COW Work Area Copy File
COBOL Work Area 1 (used with all Functions)
Regular Work Area 2 for Functions 1 and 1E
Extended Work Area 2 for Functions 1 and 1E
Regular Work Area 2 for Functions 1A, BL, BN
Long Work Area 2 for Functions 1A and BL
Work Area 2 for Function 2
Regular Work Area 2 for Function 3
Auxiliary Segment Work Area 2 for Function 3
Regular Work Area 2 for Function 3C
Auxiliary Segment Work Area 2 for Function 3C
Work Area 2 for Function 3S
Regular Work Area 2 for Function AP
Extended Work Area 2 for Function AP
P1COB
P2COB
P2COB1AL
P2COB1A
P2COB1AL
P2COB
P2COB
P2COB
P2COB
P2COB
P2COB3S
P2COBAP
P2COBAP
PL/1 Work Area 1 (used with all Functions)
Regular Work Area 2 for Functions 1 and 1E
Extended Work Area 2 for Functions 1 and 1E
Regular Work Area 2 for Functions 1A, BL, BN
Long Work Area 2 for Functions 1A and BL
Work Area 2 for Function 2
Regular Work Area 2 for Function 3
Auxiliary Segment Work Area 2 for Function 3
Regular Work Area 2 for Function 3C
Auxiliary Segment Work Area 2 for Function 3C
Work Area 2 for Function 3S
Regular Work Area 2 for Function AP
Extended Work Area 2 for Function AP
P1PL1
P2PL1
P2PL11AL
P2PL11A
P2PL11AL
P2PL1
P2PL1
P2PL1
P2PL1
P2PL1
P2PL13S
P2PLIAP
P2PLIAP
NATURAL Work Area 1 (used with all Functions)
Regular Work Area 2 for Functions 1 and 1E
Extended Work Area 2 for Functions 1 and 1E
Regular Work Area 2 for Functions 1A, BL, BN
Long Work Area 2 for Functions 1A and BL
Work Area 2 for Function 2
Regular Work Area 2 for Function 3
Auxiliary Segment Work Area 2 for Function 3
Regular Work Area 2 for Function 3C
Auxiliary Segment Work Area 2 for Function 3C
Work Area 2 for Function 3S
Regular Work Area 2 for Function AP
Extended Work Area 2 for Function AP
GEOLP1
GEOLP2
GEOLP2AL
GEOLP21A
GEOLP2AL
GEOLP2
GEOLP2
GEOLP2
GEOLP2
GEOLP2
GEOLP23S
GEOL2AP
GEOL2APX
BAL Work Area 1 (used with all Functions)
Regular Work Area 2 for Functions 1 and 1E
Extended Work Area 2 for Functions 1 and 1E
Regular Work Area 2 for Functions 1A, BL, BN
Long Work Area 2 for Functions 1A and BL
Work Area 2 for Function 2
Regular Work Area 2 for Function 3
Auxiliary Segment Work Area 2 for Function 3
Regular Work Area 2 for Function 3C
Auxiliary Segment Work Area 2 for Function 3C
Work Area 2 for Function 3S
Regular Work Area 2 for Function AP
Extended Work Area 2 for Function AP
P1BAL
P2BAL
P2BAL1A
P2BAL1A
P2BAL1A
P2BAL
P2BAL
P2BAL
P2BAL
P2BAL
P2BAL3S
P2PLIAP
P2PLIAP
C All Work Areas for all Functions PAC

___________________________

15 GEOCODE=NO is invalid for Function 1B, but the 70 bytes are appended when GEOCODE=ALL.
16 Functions 1B and AP are valid for COW only