The MAP IN statement requests a synchronous transfer of data from map fields on the screen to the corresponding variable-storage data fields. The MAP IN statement can also be used to transfer data from an area in variable storage that contains a 3270-like data stream to map-related variable-storage data fields; this is referred to as a native-mode data transfer.
►►─── MAP IN (map-name) ──────────────────────────────────────────────────────► ►─┬──────────────────────────────────────────────────────────────────────────►─ └─┬─ IO ─┬────────────────────────┬──────────────────────────────────────── │ └─ INPUT DATA ─┬─ YES ─┬─┘ │ └─ NO ──┘ └─ NOIO DATASTREAM FROM (mapped-data-location) ────────────────────────── ─►───────────────────────────────────────┬────────────────────────────────────► ─────────────────────────────────────┬─┘ ─┬─ TO (end-mapped-data-location) ─┬─┘ └─ MAX LENGTH (data-length) ──────┘ ►─┬────────────────────────────────────┬─────────────────────────────────────►◄ ├─ detail-specification ─────────────┤ └─ HEADER ─┬──────────────────────┬──┘ ├─ PAGE (page-number) ─┤ └─ MODIFIED ───────────┘
Expansion of detail-specification
►►─┬──────────────────────────────────────────────────────────────────────────►─ └─ DETAIL ┬ NEXT ◄ ─────────────────────────────────────────────────────┬─ ├─ FIRST ─┬──────────────────────────┬─────────────────────────┤ │ └─ RETURNKEY (data-field) ─┘ │ ├─ KEY (key-name) ─────────────────────────────────────────────┤ ├─ SEQUENCE_NUMBER (sequence-field) ─┬────────────────────────┬┤ │ └ RETURNKEY (data-field)─┘│ └─ RETURNKEY (data-field) ─────────────────────────────────────┘ ─►─────────────────────────────────────────┬──────────────────────────────────►◄ ─┬──────────────────────┬─┬────────────┬─┘ └─ PAGE (page-number) ─┘ └─ MODIFIED ─┘
Specifies the 1- to 8-character name of a map specified by the DECLARE MAP statement, as described in DML Precompiler-Directive Statements.
Specifies the type of data transfer associated with the MAP IN request:
Transfers data from map fields to variable-storage data fields that are associated with the specified map.
Specifies whether the contents of map fields will be moved to variable-storage data fields (YES) or left unchanged (NO). This specification applies to all variable-storage data fields unless overridden by an INPUT DATA IS YES/NO clause in a previously issued MODIFY MAP request.
Transfers data from an area in program variable storage to the variable-storage data fields that correspond to the specified map. No terminal I/O is associated with the request.
Mapped-data-location is the symbolic name of a user-defined field that contains the program variable-storage entry of the data stream to be read by the system. The length of the data stream is determined through one of the following specifications:
Indicates the end of the program variable-storage entry that contains the data stream and is specified following the last data-item entry in mapped-data-location. End-mapped-data-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the input data stream.
Explicitly defines the length, in bytes, of the input data stream. Data-length is either the symbolic name of a user-defined field that contains the length of the data stream, or the length itself expressed as a numeric constant.
Specifies (for pageable maps only) that the MAP IN operation is to retrieve data from a modified detail occurrence (MDT set on). The contents of all map fields in the detail occurrence are retrieved unless MODIFIED is specified for the MAP IN DETAIL statement; MODIFIED causes only modified fields to be retrieved.
Note: For more information about pageable maps, see the CA IDMS Mapping Facility Guide.
Retrieves the next sequential modified detail occurrence. An end-of-data condition (ERROR_STATUS is 4668) is returned in either of the following cases:
NEXT is the default.
Retrieves the first available modified detail occurrence. The optional RETURNKEY (data-field) clause specifies the name of a variable field in which the system stores the 4-byte key value (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, the system sets data-field to zero. Data-field, which does not have to be fullword aligned, is the symbolic name of either a CHAR(4) or a FIXED BINARY(31) field that contains the key value.
Note: A value is associated with a detail occurrence by using the KEY parameter in a MAP OUT DETAIL command for that occurrence.
An end-of-data condition results if all modified data occurrences already have been mapped in.
Retrieves a modified detail occurrence based on the value associated with the detail occurrence. Key is the name of a FIXED BINARY(31) field.
Note: A value is associated with a detail occurrence by using the KEY parameter in the MAP OUT DETAIL command for that occurrence.
A detail-not-found condition is returned in either of the following cases:
Retrieves a detail occurrence by sequence number. Detail occurrences are built at runtime by the application program and are stored in the sequence in which they are created. Sequence-field-name is a FIXED BINARY(31) field.
A detail-not-found condition is returned in either of the following cases:
The optional RETURNKEY (data-field) clause specifies the name of a variable field in which the system stores the 4-byte key value (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, the system sets data-field to zero. Data-field, which does not have to be fullword aligned, is the symbolic name of either a CHAR(4) or a FIXED BINARY(31) field that contains the key value.
Performs the same operation as the NEXT clause (described previously) and specifies the name of a variable field in which the system stores the 4-byte value (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, the system sets data-field to 0. Data-field, which does not have to be fullword aligned, is the symbolic name of either a CHAR(4) or a FIXED BINARY(31) field that contains the key value.
Specifies (for pageable maps only) the name of a variable field in which to store the current value of the $PAGE field on mapin. Page-number is defined as a FIXED BINARY(31) field.
Specifies (for pageable maps only) that, within a modified detail occurrence, only modified fields (MDT set on) are to be retrieved in the MAP IN operation.
Specifies (for pageable maps only) that the MAP IN operation is to retrieve the contents of data fields in the header and footer areas. The contents of all data fields in the header and footer areas are retrieved unless MODIFIED is specified for the MAP IN HEADER statement; MODIFIED causes only modified fields to be retrieved.
Specifies (for pageable maps only) the name of a variable field in which to store the current value of the $PAGE field on mapin. Page-number is defined as a FIXED BINARY(31) field.
Specifies (for pageable maps only) that, within a modified detail occurrence, only modified header fields (MDT set on) are to be retrieved in the MAP IN operation.
The following statement reads the EMPMAPLR map. Data values are transferred from map fields on the EMPMAPLR map to the corresponding variable-storage data fields. Subsequent commands can evaluate the input values and perform appropriate processing.
MAP IN (EMPMAPLR) INPUT DATA YES;
The following statement maps in the next modified detail occurrence of the EMPMAPPG map:
MAP IN (EMPMAPPG) DETAIL NEXT;
Upon completion of the MAP IN function, the ERROR_STATUS field of the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
A permanent I/O error has occurred during processing.
The dial-up line for the terminal has been disconnected.
The map request block (MRB) contains an invalid field, indicating a possible error in the program's parameters.
The derived length of the specified map input data area is zero or negative.
The map load module named in the MRB cannot be found.
The specified program variable storage entry has not been allocated.
The terminal being used is out of service.
The NOIO option has been specified but the requested data stream cannot be found.
The requested map does not support the terminal device being used.
The specified edit or code table either cannot be found or is invalid for use with the named map.
A data conversion error has occurred; internal map data does not match the map's data description.
The user-written edit routine specified for the named map cannot be found.
The requested node for a header or detail was either not present or not updated.
No more modified detail occurrences require mapin.
The scratch record that contains the requested detail could not be accessed (internal error).
|
Copyright © 2014 CA.
All rights reserved.
|
|