The MAP OUT statement creates or modifies detail occurrences for a pageable map or requests a transfer of data from variable-storage data fields to map fields on the terminal screen. MAP OUT can also be used to transfer data to another area in program variable storage; this is referred to as a native mode data transfer.
►►─── MAP OUT (map-name) ─┬──────────┬────────────────────────────────────────► ├─ WAIT ◄ ─┤ └─ NOWAIT ─┘ ►──┬───────────────────────┬─────────────────────────────────────────────────► ├─ io-specification ────┤ └─ no-io-specification ─┘ ►─┬──────────────────────────────────────────────┬─ ; ───────────────────────►◄ └─┬─ DETAIL ──┬───────────┬─┬──────────────┬─┬─┘ │ ├─ NEW ◄ ───┤ └─ KEY (key) ──┘ │ │ └─ CURRENT ─┘ │ └─ RESUME ─┬────────────────────────────┬──┘ └─ PAGE ─┬─ CURRENT ◄ ─────┬─┘ ├─ NEXT ──────────┤ ├─ PRIOR ─────────┤ ├─ LAST ──────────┤ ├─ FIRST ─────────┤ └─ (page-number) ─┘
Expansion of io-specification
►►─┬──────────────────────────────────────────────────────────────────────────►─ └ IO ◄ ─┬────────────────────────────────────────────────────────────┬───── └ OUTPUT ─┬────────────────────────────────────────────────┬─┘ └ DATA ─┬─ YES ───────┬─┬─────────┬─┬──────────┬─┘ ├─ NO ────────┤ └ NEWPAGE ┘ └ LITERALS ┘ ├─ ERASE ─────┤ └─ ATTRibute ─┘ ─►───────────────────────────────────────────────────────────────────┬────────►◄ ─┬───────────────────────────────────────────────────────────────┬─┘ └─ MESSAGE (message-text) ─┬─ TO (end-message-data-location) ─┬─┘ └─ LENGTH (message-data-length) ───┘
Expansion of no-io-specification
►►─┬──────────────────────────────────────────────────────────────────────────►─ └─ NOIO DATASTREAM INTO (mapped-data-location) ──────────────────────────── ─►────────────────────────────────────────────────────────────────────────────►─ ─┬─ TO (end-mapped-data-location) ─┬──────────────────────────────────────── └─ MAX LENGTH (max-data-length) ──┘ ─►───────────────────────────────────────────────┬────────────────────────────►◄ ─┬───────────────────────────────────────────┬─┘ └─ RETURN LENGTH INTO (data-actual-length) ─┘
Specifies the 1- to 8-character name of a map specified by the DECLARE MAP statement, as described in DML Precompiler-Directive Statements.
Specifies that the data transfer will be synchronous. The system places the issuing task in an inactive state. When the MAP OUT operation is complete, the task resumes processing according to its established dispatching priority. WAIT is the default.
Specifies that the data transfer will be asynchronous; the task will continue executing. If NOWAIT is specified, the program must issue a CHECK TERMINAL before performing any other I/O operation.
Specifies the type of data transfer associated with the MAP OUT request. IO (the default) specifies that the data transfer is to a terminal device.
Specifies (for I/O requests only) screen-display options for the data being output:
Specifies whether the variable-storage data fields are to be transmitted to the terminal. This specification applies to all variable-storage data fields unless overridden by an OUTPUT DATA clause in a previously issued MODIFY MAP request. The following options apply:
YES Transmits the contents of variable-storage data fields to the corresponding map fields.
NO Does not transmit the contents of variable-storage data fields to the corresponding map fields. However, if the automatic error-handling facility detects an error in any field, the system will transmit the applicable attribute bytes.
ERASE Does not transmit the contents of variable-storage data fields and fills the corresponding map fields with null values.
ATTRIBUTE Transmits only the attribute bytes for variable-storage data fields. Data in the record buffer is not sent to the terminal.
Activates the erase-write function; the system clears the screen and transmits both literal and variable fields to the map. If NEWPAGE is not specified, the system will write over any existing screen display without first erasing it. The keywords NEWPAGE and ERASE are synonymous.
To erase individual map fields, use the OUTPUT DATA ERASE option of the MODIFY MAP statement (described later in this chapter). To request the system to erase all screen fields and to activate the erase-write function, the MAP OUT statement must specify OUTPUT DATA ERASE NEWPAGE.
Transmits literal fields as well as variable-storage data fields to the terminal. If LITERALS is not specified, the system will write literal fields to the map only when a MAP OUT request specifies the NEWPAGE option.
Specifies (for IO requests only) the message to be displayed in the map's message area. Message-text is the symbolic name of a program variable-storage entry that contains the message text.
Note: The MESSAGE parameter can only be used with MAP OUT DETAIL if the $MESSAGE field is associated with the detail occurrence at map generation. To reference a message stored in the data dictionary, use the ACCEPT TEXT INTO parameter of the WRITE LOG statement (explained later in this chapter) to copy the message into message-text.
TO (end-message-data-location) Specifies the end of the program variable-storage entry that contains the message text and is specified following the last data item in message-text. End-message-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 output data stream.
LENGTH (message-data-length) Defines the length, in bytes, of the message text. Message-data-length is either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.
Transfers data from variable-storage data fields associated with the named map to another area of program variable storage; 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 to which the data will be transferred.
Indicates the end of the program variable-storage entry for the output 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 output data stream.
Defines the maximum length of the output data stream. Data-length is either the symbolic name of the user-defined fixed binary field that contains the length of the data stream or the length itself expressed as a numeric constant.
The optional RETURN LENGTH INTO (data-actual-length) clause specifies the program variable-storage entry to which the system will return the length, in bytes, of the output data stream. If the data stream has been truncated, data-actual-length contains the length before truncation.
Specifies (for pageable maps only) that the MAP OUT command is to create or modify a detail occurrence, and optionally associates a numeric key value with the occurrence.
Note: For more information about pageable maps, see the CA IDMS Mapping Facility Guide.
Creates a detail occurrence of a pageable map. Occurrences are displayed in the order in which they are created by the application program. NEW is the default.
Modifies the detail occurrence that was referenced by the most recent MAP IN DETAIL or MAP OUT DETAIL statement.
Optionally specifies a value to be associated with the created or modified detail occurrence. The 4-byte numeric value is not displayed on the terminal screen. Key is the name of a FIXED BINARY(31) field that contains the db-key of the database record associated with the detail occurrence.
When the KEY parameter is used with the MAP OUT DETAIL CURRENT command, the specified value replaces the value (if any) previously associated with the detail occurrence.
Specifies (for pageable maps only) the page of detail occurrences to be mapped out to the terminal:
Specifies that the current page is to be redisplayed. If no page has been displayed, the first page of the pageable map is displayed. CURRENT is the default.
Specifies that the page that follows the current page is to be displayed. If no page follows the current page, the current page is redisplayed.
Specifies that the page that precedes the current page is to be displayed. If no page precedes the current page, the current page is redisplayed.
Specifies that the first available page of detail occurrences is to be displayed.
Specifies that the page of detail occurrences with the highest available page number is to be displayed.
Specifies a variable field that contains the number of the page to be displayed. Page-number is defined as a FIXED BINARY(31) field. A page number is stored in the variable field by a preceding MAP IN PAGE (page-number) statement that names the same numeric variable field.
The following statement writes all literal and data fields associated with the EMPMAPLR map to the terminal:
MAP OUT (EMPMAPLR) OUTPUT DATA YES NEWPAGE MESSAGE (INITIAL_MESSAGE) LENGTH (80);
The following statement maps out the current detail; no terminal I/O is associated with this request if the first page of the pageable map is not yet filled:
MAP OUT (EMPMAPPG) DETAIL KEY (DBKEY);
Upon completion of the MAP OUT function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
The output operation has been interrupted; the operator has pressed ATTENTION or BREAK.
A logical error (for Example, an invalid control character) has been encountered in the output data stream.
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 output data area is zero or negative.
The map load module named in the MRB cannot be found.
The program variable-storage entry specified for return of the output data stream 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.
An error has occurred in a user-written edit routine.
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.
There is no current detail occurrence to be updated (MAP OUT DETAIL CURRENT only). No action is taken.
The amount of storage defined for pageable maps at system generation time is insufficient. No action is taken. This and subsequent MAP OUT DETAIL statements are ignored.
No detail occurrence, footer, or header fields exist to be mapped out by a MAPOUT RESUME command.
The first screen page has been transmitted to the terminal.
The last detail for a screen was written; a map page is complete and ready to be transmitted to the terminal.
|
Copyright © 2014 CA.
All rights reserved.
|
|