Testing for Input Conditions

Data Manipulation Language Statements › #MAPINQ › Testing for Input Conditions

Testing for Input Conditions

This version of the #MAPINQ statement tests for the following input conditions related to specific map fields:

If map fields have been modified and the data fields in storage contain the new (changed) contents of that field.
If map fields have not been modified and the data fields in storage remain unchanged.
If map fields have been erased by operator action.
If map fields have been truncated.
If the specified map fields are either in error (the error flag has been set on) or the map fields are correct, (the error flag has been set off). This option applies only to those maps and map fields for which automatic editing is enabled.

Syntax

►►─── #MAPINQ MRB=map-request-block-pointer ──────────────────────────────────►

 ►─┬─────────────────────────────────────────────┬────────────────────────────►
   └─ ,MRBLIST= ─┬─ MRBPLIST ◄ ─────────────────┬┘
                 └─ mrb-parameter-list-pointer ─┘
 ►─┬───────────────────────────┬──────────────────────────────────────────────►
   └─ ,CURSOR=cursor-position ─┘

 ►─┬──────────────────────┬───────────────────────────────────────────────────►
   └─ ,AID=aid-indicator ─┘

 ►─┬─ field-options ────┬─────────────────────────────────────────────────────►◄
   ├─┬─ flist-options ─┬┤
   │ └─ for-options ───┘│
   └─ if-options ───────┘

Expansion of field-options

►►─── ,FIELD=field-name ──────────────────────────────────────────────────────►

 ►─┬─────────────────────────┬────────────────────────────────────────────────►
   └─ ,INDEX=index-register ─┘

 ►─┬──────────────────────────────┬───────────────────────────────────────────►◄
   └─ ,INLEN=field-length-number ─┘

Expansion of flist-options

►►─── ,FLIST= ────────────────────────────────────────────────────────────────►

         ┌──────────────────── , ────────────────────────┐
 ►─── ( ─▼─ FIELD,field-name ─┬─────────────────────────┬┴─ ) ────────────────►
                              └─ ,INDEX=index-register ─┘

 ►─┬─────────────────────────────────────────────┬────────────────────────────►◄
   └─ ,PLIST= ─┬─ SYSPLIST ◄ ───────────────────┬┘
               └─ parameter-value-list-pointer ─┘

Expansion of for-options

►►─── ,FOR= ──────────────────────────────────────────────────────────────────►

 ►───┬─ CURRENT ─┬────────────────────────────────────────────────────────────►◄
     ├─ ALL ─────┤
     ├─ NONE ────┤
     ├─ SOME ────┤
     └─ ANY ─────┘

Expansion of if-options

►►─── ,IF= ───────────────────────────────────────────────────────────────────►

 ►─── ( ─┬─ DATANO,unchanged-field-label ─────┬─ ) ───────────────────────────►◄
         ├─ DATAYES,updated-field-label ──────┤
         ├─ DATAERAS,erased-field-label ──────┤
         ├─ DATARUN,truncated-field-label ────┤
         ├─ EDITERR,edit-error-field-label ───┤
         ├─ EDITCOR,edit-correct-field-label ─┤
         ├─ DATAIDEN,identical-data-label ────┤
         └─ DATADIFF,different-data-label ────┘

Parameters

MRB=

Specifies the storage area associated with the MRB about which the inquiry is being made.

map-request-block-pointer

A register that points to the MRB area or the symbolic name of that area.

MRBLIST=

Specifies the location of the 20-fullword storage area that is substituted for the DC/UCF portion of SUBSCHEMA-CTRL.

MRBPLIST

(Default); is the symbolic name of the storage area that will be substituted for the DC/UCF portion of SUBSCHEMA-CTRL.

mrb-parameter-list-pointer

A register that points to the area or the symbolic name of the area.

CURSOR=

Requests that the system return the cursor address from the last map in operation to the specified location in the issuing program.

cursor-position

The symbolic name of a 2-byte user-defined field. The system will set the value of cursor-position to the row and the column, each a 1-byte binary number, of the cursor position on the screen.

AID=

Requests the system to return the AID to the specified location in the issuing program.

aid-indicator

The symbolic name of a 1-byte user-defined field that will be set to the 3270 AID character received in the last map in request.

FIELD=

Moves field-related information to the issuing program.

field-name

Specifies the name of the map field being tested. The following options can be used with FIELD:

INDEX=index specifies the occurrence of the field if field-name is a multiply-occurring field. Index is either a register or the symbolic name of a user-defined field that contains the subscript or an absolute expression.
INLEN=field-length. requests that the system return the entered length, in bytes, of the specified map field to the issuing program. Field-length is a register or the symbolic name of a halfword or fullword user-defined field to which the system will return the length.

FLIST=

Specifies a list of map fields to be tested, as indicated by the FOR parameter, described below. The FLIST-parameter values must be enclosed in parentheses. Each field specification must be coded on a separate line. The FLIST parameters are:

Field-name is the name of the map data field to be tested.
INDEX= specifies the occurrence of the field if field-name is a multiply-occurring field. Index-register is a register or the symbolic name of a user-define field that contains the subscript or an absolute expression.
PLIST= (optional); indicates the location in which the system will build the field parameter list.
SYSPLIST (default); is the symbolic name of the storage area in which the system will build the field parameter list.
Parameter-value-list-pointer is a register that points to the area or the symbolic name of the area.

FOR=

Specifies the map data fields to which the test applies.

CURRENT

Specifies that the test applies only to the current data field; that is, the data field that was referenced in the last #MAPMOD or #MAPINQ statement issued by the program. If the last #MAPMOD or #MAPINQ statement specified a field list, no currency exists.

ALL

Specifies that the test is true if all map data fields meet the specified condition.

NONE

Specifies that the test is true if none of the map data fields meet the specified condition.

SOME

Specifies that the test is true if more than one, but not all of the map data fields meet the specified condition.

ANY

Specifies that the test is true if one or more of the map data fields meet the specified condition.

ALLBUT

Specifies that the test is true if all map fields except for the named field meet the specified condition.

NTCURFLD

Specifies that the test is true if all map fields except the current field meet the specified condition.

IF=

Specifies the input test condition. For each condition, the associated label specifies the symbolic name of the routine in the issuing program to which the system will pass control if the tested condition is true. The IF-parameter condition and label must be enclosed in parentheses.

DATANO

Determines if the terminal operator did not enter data in the named map fields. This condition is true if the field has not been modified or if it had been modified but the INDATA=NO option was in effect for the field during the last #MREQ IN request.

DATAYES

Determines if the terminal operator entered data in the named map fields.

DATAERAS

Determines if the data has been erased from the named map fields using 3270 local editing features. In this case, the data fields would remain unchanged unless a padding character had been specified, which would fill the field with that character.

DATATRUN

Determines if the data has been truncated in the named map fields. A field that has been truncated would also fulfill the condition DATAYES, described above.

EDITERR

Determines if the named map fields were found to be in error during automatic editing. To test for this condition, automatic editing must be enabled for the map and for each of the named map fields.

EDITCOR

Determines if the named map fields were found to be correct during automatic editing. To test for this condition, automatic editing must be enabled for the map and for each of the named map fields.

DATAIDEN

Tests whether input data is identical to map data currently in program variable storage. DATAIDEN is true in either of the following cases:

The field's modified data tag (MDT) is off. On mapin, the MDT is off if the user did not type any characters in the field, a previous modify map did not set it, or the map specifies N to MDT on Y/N.
The field's MDT is on, but each character that the user typed in is identical (including capitalization) to the data in variable storage.

DATADIFF

Tests whether input data is different from map data currently in program variable storage. DATADIFF is true if the field's MDT is on and at least one input character differs from the data in variable storage.

Example

The following example of the #MAPINQ statement tests for whether the terminal operator entered data in more than one, but not all of the fields described in the FLIST parameter. If this condition is true the program branches to the label CHECFLDS. A false condition returns control to the next executable instruction.

#MAPINQ MRB=BLOCK1,FLIST=(FIELD,SCREENF2,                     *
      FIELD,SCREENF3,                                         *
      FIELD,SCREENF4,                                         *
      FIELD,SCREENF5),                                        *
      FOR=SOME,IF=(DATAYES,CHECFLDS)

Status Codes

The #MAPINQ request is unconditional; any return code other than X'00' will result in an abend of the issuing task.