CICS BMS MAP LOW-VALUES

Input Mapping

When BMS makes the map available to your program on a RECEIVE MAP operation it
places data in three areas for each input field. These three areas are the length
field, the flag/attribute byte and the data field.

There are several situations at execution time for which BMS allows. In the
physical map, a length for the field is specified. If more data is keyed in than
is specified in this length, the data is truncated on the right and the length
field is set to the truncated length. If less data is keyed in than the length
specified, the length field is set to the number of characters entered and the
data field is padded on the right with blanks or on the left with zeros
(depending on whether the field is alpha or numeric). However, if any data was
previously in the field and the keyed data failed to cover up the old data, the
entire field would be returned with a length representing the original field
length.

There is an exception to the right-justify, zero-fill feature for a numeric item.
If the numeric field is initialized with other characters previous to the data
you entered, your data may not come in right-justified and zero-filled.

The flag byte is almost always initialized to X'00' when the map comes to you.
The length field is usually used to tell whether or not any data has been
entered. Data has been entered in the field when the length field is not equal
low-values (nulls). However, a special situation occurs when a field is modified
but no data is sent (as when a field is modified to low values with the erase to
end-of-file key). The length field would show as zero and there would be no data
in the data field. To be able to tell when this has happened, the flag byte is
set to X'80' and the length area is set to zeros. Therefore, if the flag byte is
set to X'80', the user has cleared the field. The length and data areas of any
fields that are defined but not modified are set to low values (X'00').

Output Mapping

Do not re-use symbolic mapping areas under BMS unless they are cleared to low
values. BMS relies on x'00' in the first byte of a field to construct
an accurate output data stream.

To place data in the output map, move it to the output data field. Be careful,
however, not to let any low-value (X'00') characters begin your field or BMS will
ignore that field. If a field begins with low values, the data in the field is
not returned to the program.

It is also possible to change the attribute of the output field. This can be done
when the input and output portions of the map redefine each other. In that case,
you have to move the desired attribute byte into the input map's attribute byte
and your attribute will override what was originally specified. However, when the
map is received, that byte is reset.

You may code your own attribute constants to supplement the attributes supplied
by IBM. Sample explanation for some of the attributes followed by the COBOL
statements defining some additional attributes are shown as follows:

'I': Moving 'I' to the attribute byte for an alphanumeric field in error will
make this field high intensity, unprotected and MDT on.

'R': Moving 'R' to the attribute byte for a numeric field in error will make this
field high intensity, unprotected, numeric lock on and MDT on.

'4': Moving '4' to the attribute byte for a edited field that has passed the
edits will protect this field.

NOTE: If an attribute is needed for the FSET, BRT combination, define the
following in WORKING-STORAGE:

01  FSET-BRT            PIC X VALUE 'I'.

Using the map fields defined under the "Input Mapping" topic, the move statement
to set this attribute would be coded:

MOVE  FSET-BRT TO INFLDA.

MAPFAIL

There is an important situation that occurs under BMS called "MAPFAIL". This
occurs when a RECEIVE MAP command is issued but no data was returned to the
program. One common way this would happen is when no field is modified on a map.
When no field is modified, the length, flag and data fields are not changed or
updated in any way. You must know if data is returned or entered before you start
your edit checking.

One technique that is used to avoid the MAPFAIL condition is the code
in the mapset a one-byte dummy "autoskip" field with FSET specified so at least
one byte of date is sent to the program when the map is returned.

You can test EIBAID to ensure that data was entered via the ENTER key (or other
planned key) by checking for which AID key was pressed. The clear or PA key will
look like data entry, but no data is returned. See the "Input Mapping" topic for
more information about receiving a map with no data. There is a MAPFAIL
exceptional condition that is handled by the HANDLE CONDITION command in command-
level programming.

In command-level programming, if the HANDLE AID command is specified, it could
override the MAPFAIL handle condition specified. This could mean that the handle
aid would take precedence over the handle condition. The RESP and RESP2 options
may also be used to test for exceptional conditions. Since the use of RESP
implies NOHANDLE, you must be careful when using it with the RECEIVE command,
because NOHANDLE overrides the HANDLE AID command as well as the HANDLE CONDITION
command. The result is that PF key responses are ignored.