gtpd2m1jData Communications Services Reference

Mapping Support User and Operating Procedures

Introduction

This section describes the process and procedures necessary to (a) create, load, utilize, and maintain the online Terminal Map Record files, and (b) generate symbolic reference modules (DSECTS) in user assembled programs. In addition, the terminal inputs required to utilize paging and scrolling, and their resultant responses, are detailed. The information set forth includes input preparation, system error and message interpretation, general process flow, input messages and associated responses, and the job control language (JCL) necessary to invoke the offline phases of processing.

Physical/Symbolic Map Create Process

The process of creating and defining map formats results in the generation of symbolic reference modules (DSECTs) in user assembled programs and the initialization and maintenance of the physical online map records used by the Input/Output Mapping Program. The following steps outline the entire process involved in order to obtain the final results.

  1. The user decides on the exact contents and format of a printout or CRT display. This may be defined by a desired report design or function design. The user describes, on graph paper or on an IBM 3270 Information Display System Panel Layout Sheet, the fields that are to appear in the panel, the attributes and characteristics of each field, and the text that is to appear on each panel.
  2. After laying out the panel, the information is transcribed to coding sheets. The various panel contents and field characteristics are written as components of macro keyword parameters. Each panel and group of fields comprising that panel is represented by a series of parameterized DPANL and DDATA map macro source statements. In addition, each panel is assigned, by the user, a unique symbolic name and sequence number.
  3. The information previously recorded on coding sheets is punched into cards.
  4. Each group of map source statements, which corresponds to a panel, is composed of a series of one or more DDATA statements. There is one DPANL statement preceding the first DDATA card and one following the last DDATA card; this sequence constitutes a map. Each uniquely named and numbered map is added, by the user, to a Map Source Statement Library using a standard MVS Source Library Edit utility. The Map Source Statement Library, which is allocated by the user as a partitioned data set, contains all the map source statements (DPANL and DDATA) and should be the only storage medium where these statements reside.
  5. Utilizing the symbolic name assigned to each field comprising a map, the user codes his ECB controlled source program to perform a desired function. Within the source code, the user will write one or more COPY mapname statements. Each COPY statement will cause the assembler to insert the requested map source statements from the library into the source program immediately after the COPY statement and to generate an associated DSECT. The mapname operand is the same as the member name in the source library.
  6. The source program, including COPY statements, is input to the MVS Assembler. These copy members must be on the MVS SYSLIB data set. The result of the assembly is an object module and program listing. The latter will contain an expansion of the DSECT, informational comments, and error messages, if applicable. Incorrectly coded or missing DPANL and DDATA parameters result either in default assumptions being taken or assembly errors being initiated. The user should use the assembly listing as a guide to correct errors and incorrectly coded map specifications. The corrected map source statements are then replaced in the library and the user source program is reassembled. The result of the successful assembly is a DSECT consisting of symbolically addressable fields.
  7. The Map Source Statement Library is used as input to the offline Map File Create and Load Program (03-ASL). When a file create or replacement has been requested, this segment (ASLOL) sequentially reads the source statements in the library, beginning with the first DPANL statement, then proceeding to the DDATA field definitions, and finally concluding with the ending DPANL statement, for each map (ASLOL in this topic refers to both offline segments ASLOL and ASLOM). That is, for the addition, deletion, or replacement of specific MSP records in a file, segment ASLOL obtains the uniquely assigned map name or map sequence number from the input cards and locates the associated map in the Map Source Statement Library. ASLOL inspects each statement for valid order, format, and data; errors are written to the printer. If no error is encountered during the edit of a map, ASLOL will construct the corresponding Terminal Map Record and write the formatted record to the Map Macro Tape File (MRT). During this phase of the Map File Create processing, the user may invoke a function which provides two listings of the map names and sequence numbers currently residing in the Map Source Statement Library. The first listing consists of the symbolic map names, in ascending alphabetic order, and their associated sequence numbers. The second listing contains the symbolic map names and sequence numbers and is arranged in ascending order, by map sequence number.
  8. Upon completion of MSP file create or replacement, the user invokes the SORT Utility Program to arrange the Terminal Map Records by ascending map sequence number within each device type. The sorted records are written to the Map Macro Tape File (AS0MP), which will be used as input to the online portion of the Map File Create and Load Program.
  9. A Z-type command invokes the online segment of the Map File Create and Load Program which sequentially reads the MSP Records from the MRT File and writes each record to its respective file location. During this phase of processing, the mapping and formatting function is inhibited. Any errors encountered during the load phase are recorded on the PRC high speed RO device. At the conclusion of the load phase, mapping and formatting are again allowed, and a map load completed response is sent to the terminal which initiated the command. The command is ZAMAP. With the Multiple Data Base Facility, to load into a particular subsystem, prefix the command with the subsystem ID.

Macro Description

The Mapping Support macro instructions are used in application development to declare a data structure used in processing terminal displays. DPANL and DDATA macro instructions (called map statements) written by an application programmer must be placed onto a Map Source Statement Library with an MVS utility program. Map statements are then included in ECB controlled source code through the use of the assembly language COPY instruction. The copied map statements have the effect of declaring symbolic names used in a display data structure, since the DPANL and DDATA instructions expand into a DSECT included in the source code. The DSECT is adjusted and a register is assigned as the result of parameters included in the map statement coding.

The effect of using map statements is analogous to the use of a data macro instruction. However, map statements do not appear in the source code of ECB controlled programs. This means that source code does not contain the register assignment of the DSECT generated as the result of copied map statements.

A map statement on the Map Source Library is used in two different ways:

Terminal Panel Display Macro (DPANL)

This macro, which consists of parameterized keywords coded by the user, provides the capability for the user to specify, for each format or panel, a unique map name and sequence number, a related terminal type, 3270 command and control information, and DSECT size. There are two of these statements for each user written map.

Terminal Data Field Display Macro (DDATA)

This macro statement, which is coded by the user, defines the symbolic name, length, characteristics, and position of each field in a user designated report or display. The inclusion of the field name provides the user symbolic addressability to a specific area of a DSECT. There is a single DDATA statement for each field appearing in a user desired report or display.

Record Description

Terminal Map Record

This record is constructed offline by ASLOL. The data that is contained in each record is obtained from the keyword parameters of the DPANL and DDATA macro source statements previously written by the user. After the MSP Records have been constructed and written to the MRT File, they are loaded by the online ASL program for use by the Input/Output Mapping Program to format data streams. There is one physical Terminal Map Record created for each terminal type specified on the DPANL macro statement of a specifically named and numbered map.

Creating Map Source Statements

Terminal Panel Display Macro (DPANL)

There are two (2) DPANL statements required for each user defined map. The first precedes and the latter follows the DDATA field definitions.

The following examples of DPANL statements and their associated MVS Assembler generated parameters are provided as representative samples of this macro. Note that a map definition consists of DPANL and DDATA statements; only examples of the former are shown at this point.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
MAP1      DPANL   DSECT=START,                                        X
                  MODE=IN,                                            X
                  SEQNO=75,                                           X
                  MAXFLDS=10
+MAP1I    DSECT
+MAP1IHDR DS      0CL16         MESSAGE BLOCK HEADER
+MAP1IBID DS      CL2           RECORD ID
+MAP1ICHK DS      CL1           RECORD CHECK
+MAP1ICTL DS      CL1           RECORD CONTROL FIELD
+MAP1IPGM DS      CL4           MODIFYING PROGRAM FIELD
+MAP1IFCH DS      CL4           FORWARD CHAIN ADDRESS
+MAP1ILIT DS      CL4           LINE IA TA & CPUID
+MAP1IMF  DS      CL2           INPUT FIELD BIT INDICATORS
          ---
          ---
          ---
          ---
 
 
          DPANL   DSECT=END,REG=R1
+         USING   MAP1I,R1
+ IS      CSECT
+#MAP1I   EQU     75            MAP SEQUENCE NUMBER
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
MAP2      DPANL   DSECT=START,                                        X
                  MODE=OUT,                                           X
                  SEQNO=128,                                          X
                  DEV=(3277-1,3286-1),                                X
                  OMSGBLK=128,                                        X
                  CMD=W
+MAP2O    DSECT
+MAP2OHDR DS      0CL16         MESSAGE BLOCK HEADER
+MAP2OBID DS      CL2           RECORD ID
+MAP2OCHK DS      CL1           RECORD CHECK
+MAP2OCTL DS      CL1           RECORD CONTROL FIELD
+MAP2OPGM DS      CL4           MODIFYING PROGRAM FIELD
+MAP2OFCH DS      CL4           FORWARD CHAIN ADDRESS
+MAP2OLIT DS      CL4           LINE IA TA & CPUID
          ---
          ---
          ---
          DPANL   DSECT=END,REG=R4
+         USING   MAP2O,R4
+ IS      CSECT
+#MAP2O   EQU     128           MAP SEQUENCE NUMBER
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
MAP3      DPANL   DSECT=START,MODE=BOTH,SEQNO=(3,4),MAXFLDS=17
          DDATA
          DPANL   DSECT=END,REG=R4
 
+MAP3I    DSECT                 MSG BLOCK DSECT
+MAP3IHDR DS      0CL16         MSG BLOCK HEADER
+MAP3IBID DS      CL2           RECORD ID
+MAP3ICHK DS      CL1           RCD CHECK
+MAP3ICTL DS      CL1           RCD CONTROL FIELD
+MAP3IPGM DS      CL4           MODIFY PGM FIELD
+MAP3IFCH DS      CL4           FWD CHAIN FIELD
+MAP3ILIT DS      CL4           LINE IA TA & CPU ID
+MAP3IMF  DS      CL3           MODIFY FIELDS INDICATORS
          DS      GENERATED BY DDATA - REFERENCE DDATA MACROS
+         USING   MAP3I,R4
+ IS +     CSECT
+#MAP3I    EQU     3             MAP SEQUENCE NUMBER
          ---
          ---
          ---
          ---
          ---
 
+MAP3O    DSECT                 MSG BLOCK DSECT
+MAP3OHDR DS      0CL16         MSG BLOCK HEADER
+MAP3OBID DS      CL2           RECORD ID
+MAP3OCHK DS      CL1           RCD CHECK
+MAP3OCTL DS      CL1           RCD CONTROL FIELD
+MAP3OPGM DS      CL4           MODIFY PGM FIELD
+MAP3OFCH DS      CL4           FWD CHAIN FIELD
+MAP3OLIT DS      CL4           LINE IA TA & CPU ID
+MAP3ORES DS      CL3           NOT USED
          DS      GENERATED BY DDATA - REFERENCE DDATA MACRO
          USING   MAP3O,R4
+ IS      CSECT
+#MAP30   EQU     4             MAP SEQUENCE NUMBER

Terminal Data Field Display Macro (DDATA)

There is a variable number of DDATA statements for each user defined map. Generally, there is one (1) DDATA statement for each field the user desires to define for input or output data streams. For a detailed description of the various keywords and parameters to be declared by using the DDATA macro, see TPF General Macros.

The following examples of DDATA statement and their associated MVS assembler generated parameters are provided as representative examples of this macro.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
ABCD     DDATA    POS=(1,1),LENGTH=10,REPEAT=4 (input map)
ABCD0L   DS       H          DATA FIELD INPUT LENGTH
ABCD0I   DS       CL10       INPUT DATA
ABCD1L   DS       H
ABCD1I   DS       CL10
ABCD2L   DS       H
ABCD2I   DS       CL10
ABCD3L   DS       H
ABCD3I   DS       CL10
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
XYZ      DDATA    POS=(5,10),LENGTH=3,REPEAT=2 (output map)
         DS       0H
XZY0A    DS       CL1         ATTRIBUTE BYTE
         DS       CL1         RESERVED
XYZ0O    DS       CL3         OUTPUT DATA
         DS       0H
XYZ1A    DS       CL1         ATTRIBUTE BYTE
         DS       CL1         RESERVED
XYZ1O    DS       CL3         OUTPUT DATA

In this case, the first field will be positioned at row 5, column 10 of a display/print; the second field (XYZ1A + XYZ1O) will be at row 6, column 10.

MNOTE Messages Produced By DPANL and DDATA Macros

The MNOTE messages produced by the DPANL and DDATA macros are self- explanatory. The severity code associated with each MNOTE message indicates whether corrective action is necessary or not. A severity code of 2 indicates that a default value is assigned to an omitted keyword parameter. A severity code of 4 indicates a condition which must be corrected. A severity code of 0 is an information message.

Offline Map File Create and Modify

The following section details the JCL requirements, hardware, card input, and messages associated with the offline portion of the Mapping Support. This phase of the package provides the user with the means of creating and replacing entire Terminal Map Record (MSP) files, and of adding, deleting, and replacing individual MSP records residing in a file.

Hardware Requirements

System hardware requirements for the execution of the offline version of the Map File Load/Create program are as follows.

For the Create Run


Device #REQ Device Name Purpose
CARD READER 1 OS/READER
SYSIN
Read JCL to initiate program ASLOL. Sort program/print program.
PRINTER 1 OS/PRINTER
SYSPRINT/SYSUT2
Print JCL error messages/ utility messages.
PRINT Name given printer device by program ASLOL to log program error messages.
DISKS 1 (min) MAPD/MAPS Names given users Map Source Library.
SORTWK01,02,03 Disk workspace for Sort program.
TAPE 1 MAPTAPE Name given MRT tape to be created by program ASLOL.
SORTIN/SORTOUT Same MRT tape created by ASLOL but used as input/output to Sort program.
SYSUT1 Same MRT tape created by ASLOL and sorted by Sort. Now used as input to Print/ Punch utility.

For The Modify Run

Hardware requirements for the modify phase are the same as the Create run, with the following exception. The card reader will be used by the ASLOL program as an input device with the logical name Card needed in the JCL run (see JCL Examples).

JCL Examples

Create Run

//CREATE JOB
//JOBLIB DD DSN=P8740SM1.VSM1.PTF0037.SORTLIB,DISP=SHR
//MAPINIT EXEC PGM=IEHINITT       (INITIALIZE MRT TAPE)
//SYSPRINT DD SYSOUT=A
//LABEL DD UNIT=(TAPE,,DEFER)
//SYSIN DD *
LABEL    INITT   SER=111111
/*
//MAPGEN EXEC PGM=ASLOL,PARM='CREATE,PRINT',TIME=5  (MRT CREATE)
//STEPLIB DD DSN=USER LINK LIBRARY,DISP=(SHR,PASS)  (ASSUMED CATALOGED)
//PRINT DD SYSOUT=A,DCB=(RECFM=FB,BLKSIZE=3630,LRECL=121)
//MAPD   DD DSN=USER MAP LIBRARY,DISP=SHR  (ASSUMED CATALOGED)
//MAPS    DD DSN=USER MAP LIBRARY,DISP=SHR  (ASSUMED CATALOGED)
//MAPTAPE DD DCB=(BLKSIZE=1055,LRECL=1055,RECFM=FB),DSN=MAPRCDS,
//        UNIT=(TAPE,,DEFER),VOL=SER=111111,DISP=(OLD,PASS),
//        LABEL=(,SL)
//SYSUDUMP DD SYSOUT=A
//PRINT2 DD SYSOUT=A,DCB=(RECFM=FBA,BLKSIZE=3630,LRECL=121)
//SYSOUT DD SYSOUT=A
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//STORE DD DSN=&&PRTDATA,DCB=BLKSIZE=18,LRECL=18,RECFM=FB),
//      UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG),DISP=(NEW,DELETE)
//SORTIN DD DSN=&&PRTDATA,DISP=(,PASS),VOL=REF=*.STORE
//SORTOUT DD DSN=&&PRTDATA,DISP=(OLD,DELETE),VOL=REF=*.STORE
//SORTWK01  DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//SORTWK02  DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//SORTWK03  DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//CARD   DD *
/*
//SORT   EXEC SORTD  (MRT SORT)
//SORT.SORTIN DD DSN=MAPRCDS,UNIT=(TAPE,,DEFER),VOL=SER=111111,
//     DCB=(LRECL=1055,BLKSIZE=1055,RECFM=FB),
//     LABEL=(,SL),DISP=OLD
//SORT.SORTOUT DD UNIT=AFF=SORTIN,DSN=MAPRCDS,VOL=SER=111111,
//     DCB=(LRECL=1055,BLKSIZE=1055,RECFM=FB),LABEL=(,SL),
//     DISP=(NEW,PASS)
//SORT.SORTWK01 DD UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG),
//       VOL=REF=*.MAPGEN.SORTWK01
//SORT.SORTWK02 DD UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG),
         VOL=REF=*.MAPGEN.SORTWK02
//SORT.SORTWK03 DD UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG),
         VOL=REF=*.MAPGEN.SORTWK03
//SORT.SYSIN DD *
SORT FIELDS=(23,1,CH,A,13,2,BI,A,5,4,CH,A,9,2,BI,A),SIZE=E120
END
/*
//PRINT EXEC PGM=IEBPTPCH  (PRINT FINAL SORTED MRT)
//SYSUT1 DD DCB=(BLKSIZE=1055,LRECL=1055,RECFM=FB),DSN=MAPRCDS,
//       UNIT=(TAPE,,DEFER),VOL=SER=111111,DISP=(OLD,KEEP),
//       LABEL=(,SL)
//SYSPRINT DD SYSOUT=A
//SYSUT2 DD SYSOUT=A
//SYSIN DD  *
    PRINT   TOTCONV=XE
/*
//

Modify Run

//MODIFY JOB
//JOBLIB DD DSN=P8740SM1.V3M1.PTF0037.SORTLIB,DISP=SHR
//MAPINIT EXEC PGM=IEHINITT       (INITIALIZE MRT MOD TAPE)
//SYSPRINT DD SYSOUT=A
//LABEL DD UNIT=(TAPE,,DEFER)
//SYSIN DD *
LABEL    INITT  SER=111111
/*
//MAPGEN EXEC PGM=ASLOL,PARM='MODIFY,PRINT',TIME=8
//STEPLIB DD DSN=USER LINK LIBRARY,DISP=(SHR,PASS)  (ASSUMED CATALOGED)
//PRINT DD SYSOUT=A,DCB=(RECFM=FB,BLKSIZE=3630,LRECL=121)
//MAPD    DD DSN=USER MAP LIBRARY,DISP=SHR  (ASSUMED CATALOGED)
//MAPS     DD DSN=USER MAP LIBRARY,DISP=SHR  (ASSUMED CATALOGED)
//MAPTAPE DD DCB=BLKSIZE=1055,LRECL=1055,RECFM=FB),DSN=MAPRCDS,
//        UNIT=(TAPE,,DEFER),VOL=SER=111111,DISP=(OLD,PASS),
//        LABEL=(,SL)
//SYSUDUMP DD SYSOUT=A
//PRINT2 DD SYSOUT=A,DCB=(RECFM=FBA,BLKSIZE=3630,LRECL=121)
//SYSOUT DD SYSOUT=A
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//STORE  DD DSN=&&PRTDATA,DCB=(BLKSIZE=18,LRECL=18,RECFM=FB),
//       UNIT=SYSDA,SPACE=TRK,(20),,CONTIG),DISP=(NEW,DELETE)
//SORTIN DD DSN=&&PRTDATA,DISP=SHR,VOL=REF=*.STORE
//SORTOUT DD DSN=&&PRTDATA,DISP=(OLD,DELETE),VOL=REF=*.STORE
//SORTWK01   DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//SORTWK02   DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//SORTWK03   DD  UNIT=SYSDA,SPACE=(TRK,(20),,CONTIG)
//CARD  DD  *
D       299  B   DELETE MAP WITH SEQ NO. OF 299 FOR DEV TYPE B
D       2300 BF  DELETE MAP WITH SEQ NO. OF 2300 FOR DEV TYPE B & F
D       3000 BF  DELETE MAP WITH SEQ NO. OF 3000 FOR DEV TYPE B & F
D       2800 ABC DELETE MAP WITH SEQ NO. OF 2800 FOR DEV TYPE A, B & C
A       AAAA     ADD MAP NAMED AAAA
A       MAP      ADD MAP NAMED MAP
A       LARG     ADD MAP NAMED LARG
A       RCDS     ADD MAP NAMED RCDS
R       TKT1     REPLACE MAP NAMED TKT1
R       PAGE     REPLACE MAP NAMED PAGE
R       LARG     REPLACE MAP NAMED LARG
R       ZZZZ     REPLACE MAP NAMED ZZZZ
/*
//PRINT EXEC  PGM=IEBPTPCH  (PRINT MRT MOD TAPE)
//SYSUT1  DD  DCB=(BLKSIZE=1055,RECFM=FB),DSN=MAPRCDS,
//        UNIT=(TAPE,,DEFER),VOL=SER=111111,DISP=(NEW,KEEP),
//        LABEL=(,SL)
//SYSPRINT DD SYSOUT=A
//SYSUT2 DD SYSOUT=A
//SYSIN DD  *
    PRINT   TOTCONV=XE
/*
//

Input Requirements For Program (ASLOL)

Create Run

For the Map File Create program, the input requirements for a Create run are as follows:

  1. The user-coded DPANL and DDATA statements installed on the user's Map Source Library.
  2. The JCL as shown in the JCL example.

Modify Run

The input requirements for the modify run of the Map File Load/Create run are as follows:

  1. The user-coded DPANL and DDATA statements installed on the user's Map Source Library.
  2. The JCL as shown in the JCL example.
  3. The Modify Control Cards. Reference Modify Control Card Specifications and examples.

Modify Control Card Specifications

Delete a Map

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
D        Map    Device Type Code
         Seq. #
 
Note:
More than 1 Device Type Code can appear on 1 card starting in column 16 and ending before column 72.

Modify an Existing Map

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
R        Map Name
 

Add a New Map

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
A        Map Name
 

Modify Run Examples

Delete a map for Device Type A (3277-1) with sequence number 123.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
D        123   A
 

Delete a map for Device Types A and B (3277-1 and 3277-2) with sequence number 156.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
D        156   A B
 

Modify the existing map named Map1 with the version now on the Map Source Library.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
R        MAP1
 

Add to the existing map file the map named MAP2 now in the Map Source Library.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
 
A        MAP2

Error and Communication Messages

All error and communication messages issued by the offline generic mapping support program are full length descriptive messages and should provide the user with information about what action to take in order to correct the problem. Should the user have difficulty understanding the messages and what action, if any, to take, see Messages (System Error and Offline) and Messages (Online).

Input/Output Mapping User Requirements

To format (map) input and output data streams, the user written application program segment must request activation of the Input/Output Mapping Program. This is accomplished by means of an ENTER type macro to members ASFO/ASFI for RCB associated devices or to ASFP/ASFJ for devices not associated with an RCB. In addition, the user passes information in a variable length work area and the unformatted data stream to the mapping function. A more detailed explanation of these points follows.

Input Mapping

This phase of processing reformats native mode data streams emanating from the IBM 3270 Information Display terminal. The native mode data, includes device dependent control characters (buffer address and buffer order characters) interspersed among the entered text. Input mapping deletes from the data stream the device dependent control characters inserted by the 3270 control unit and places the agent/operator entered text in specific areas of blocks of main storage; these areas coincide with a previously defined symbolic reference module (DSECT). In addition, a series of bit indicators, one for each possible input field, is used by the input mapping function to summarize, to the user application, the contents of each respective input field. When text is entered for a field, the corresponding bit is set on.

These bit indicators are stored in the field suffixed by IMF in the user DSECT.

The reformatted block is then returned to the user via the BACKC macro or passed to a user determined destination via the ROUTC macro.

The user written application program segment entry requirements to input mapping are summarized as follows:

It is the user application's responsibility to determine if the device has an associated RCB. If the device has an associated RCB, the user application codes an ENTRC ASFI to regain control or codes ENTNC ASFI if not. If the device does not have an associated RCB, the user application codes an ENTRC ASFJ to regain control or codes an ENTNC ASFJ if no return is desired.

When an ENTRC Has Been Issued


Bytes 0-1 Contain the map sequence number in binary representation.
Byte 2 For return, must be set to a X'00'. On return from ASF, contains X'00' for nonerror condition or binary value for error condition.
Bytes 3-5 Reserved for use by Mapping Support Package.
Note:
In this case, the input data is reformatted and returned to the user. No ROUTC is issued by the AS package.

When an ENTNC Has Been Issued


Bytes 0-1 Contain the map sequence number in binary representation.
Byte 2 For no return, must be set to a X'80'.
Bytes 3-5 Reserved for use by the Mapping Support Package.
Bytes 6-17 This represents the Routing Control Parameter List (RC0PL) that is used to route messages.
Bytes 6-9 Contain the message destination, either a terminal address and processor ID or a symbolic application name.
Bytes 10-13 Contain the symbolic application name origin of this message.
Bytes 14-17 Contain control information - Reference RC0PL.
Note:
When byte 2 =X'80', the AS package issues the ROUTC.

An example of code necessary to invoke the input formatting function may consist of the following:

         BEGIN
           --
           --
           --
           --
          LA    R1,#MAP1I      MAP SEQUENCE NUMBER
          STH   R1,EBW000      STORE IN WORK AREA
          MVI   EBW002,X'00'   INDICATE RETURN
          LA    R1,EBW000      ADDR OF WORK AREA
          ENTRC ASFI
          CLI   2(R1),X'00'    ERROR RETURN
          BNE   ERROR          YES
          L     R2,CE1CR0      USER DSECT
          TM    MAP1IMF,X'40'  SECOND INPUT FIELD CONTAIN DATA
          BO    TAG1           YES
          TM    MAP1IMF,X'01'  EIGHTH INPUT FIELD CONTAIN DATA
          BZ    TAG2           NO
          --
          --
          --
          --
          --
          FINIS

Additional Considerations

Output Mapping

This phase formats for display on 3270 CRTs and for printing on hard copy terminals output messages which have been constructed by the user application program. For 3270 type terminals, whether CRT or printer, output mapping reformats the user created data stream, which consists solely of text, and constructs an output message containing device dependent control characters. These control characters consist of 3270 commands, orders, and attributes. The user created text is resident in a block(s) of storage which coincides with a program member assembled symbolic reference module (DSECT).

For non-3270 type devices supported by output mapping, data fields are placed in their defined positions by using blanks (X'40') as fill characters or, for those devices equipped with a mechanical tab feature (for example, 1980 Model 24), tab control characters (X'05'). When fields are placed on new lines, carriage control characters (X'15') are inserted into the output data stream. The positioned data is obtained from the user program generated DSECT.

After the output data has been mapped, the blocks are either returned to the user via the execution of a BACKC macro, or the data is routed to a terminal/application via the ROUTC macro.

The user written application program segment entry requirements to output mapping are summarized as follows:

  1. The prime user block (DSECT) must be on data level 0. When overflow records exist, these are on file.
  2. The mapping interface work area has been correctly initialized with the map sequence number and RCPL (Routing Control Parameter List); the latter when control is not returned to the requesting program. This work area has already been discussed in the previous section.
  3. The appropriate ENTER type macro must be executed. When the user application segment is to regain control after the output data has been reformatted, an ENTRC must be coded. When the user application does not want control returned after the output data has been mapped, an ENTNC must be coded. It is the user application's responsibility to determine if the device has an associated RCB. If the device has an associated RCB, the user application codes an ENTRC ASFO to regain control or codes an ENTNC ASFO if not. If the device does not have an associated RCB, the user codes an ENTRC ASFP to regain control or codes an ENTNC ASFP if mapping is to route the formatted block. In this case, the interface work area must contain a user created RCPL. The Output Mapping function will issue a ROUTC.
  4. The mapping interface work area must not reside in the DSECT block on level 0.
  5. Register 1 must contain the address of the start of the mapping interface work area, which begins on a halfword boundary.
  6. Bytes 12-15 of the prime user block (DSECT) on level 0 must contain the symbolic LNIATA or RID and the CPU ID of the terminal against which the output data is to be mapped. This field is symbolically addressable by the tag mapname OLIT (e.g. MAP2OLIT).

    Examples:

    For LNIATA: Bytes 12-15 520302C1

    For RID: Bytes 12-15 001006C1

  7. The user is responsible for obtaining the block(s) of storage which will contain his data. This is the block that is passed to ASFO/ASFP on level 0. The user is also responsible for insuring that the portions of his work block which do not contain data are initialized with binary zeros (X'00'). This is necessary because output mapping interrogates each field of the user DSECT for the existence of data; the presence of binary zeroes implies no data for that specific field. If fields which do not contain data are not set to binary zeroes, the results are unpredictable. The user application must ensure that all fields as reflected by the MSP DSECT are accounted for, either with or without data. The user is responsible for forward chaining on file the blocks of storage which will contain his data.
  8. Two additional bytes are provided for each output field in the user's DSECT. The purpose of this is to provide the user application program with the capability to override the attribute byte defined in the Terminal Map Record at the time the output data is being created. The attribute byte override is simply moved into the left-most byte of the two byte field. It must contain a bit configuration recognizable by the 3270 hardware or the results will be unpredictable. No validation of user generated attributes is performed by the output mapping function.
  9. When the user desires to output to shared buffer printers (3278/3284) there are various options that must be taken into consideration:
    1. For RCB dependent applications the RCB for the CRT will contain the address of the associated printer so applications should pass either the printer RCB or LNIATA.
    2. For systems with no RCBs there is only one RVT entry for the CRT/printer combination, so the user must enter output mapping with the WCC start print on and pass the resource ID (RID) of the combined unit.
    3. There are no shared buffer terminals for the extended 3270 CRTs (3278). When the user wants to transmit to a CRT and a printer the WCC start print bit must be on. The cluster controller will display the message on the CRT specified by the RID and will print the message on the first printer it finds that is not busy.
  10. Bytes 3-5 of the mapping interface work area enable the user to either override the 3270 command, WCC, and CCC in the Terminal Map Record or to provide the FROM address for a COPY command. When the user wishes to override the 3270 command, the one byte command (write, E/W, Copy, Erase All Unprot, Erase/Write Alternate) code is moved into byte 3 of the work area. When a 3270 WCC or CCC is to be overridden, the desired eight bit character is moved into byte 4 of the work area. When a COPY command has been specified, either in the Terminal Map Record or byte 3 of the work area, byte 5 must contain the 3270 address of the device being copied from. It is the user's responsibility to place the correct values and characters in bytes 3-5. If bytes 3, 4, and 8 are not used, they must be initialized to values of X'00'. Also, the user must ensure the unsolicited bit is set in the RCPL (RC0PL).

    The purpose of the following sample code is to provide an example of how the entry requirements to output mapping (ASFO) may be accomplished:

                  BEGIN
                   ---
                   ---
                   ---
                   ---
                  GETCC   D0,L2 OBTAIN 1055 BYTE BLOCK
                  L       R2,CE1CR0                 LOAD BASE ADDRESS
                  MVI     MAP2OBID,X'00'            INITIALIZE BLOCK
                  MVC     MAP2OBID+1(256),MAP2OBID
                  MVC     MAP2OBID+256(256),MAP2OBID
                  MVC     MAP2OBID+512(256),MAP2OBID
                  MVC     MAP2OBID+768(256),MAP2OBID
                  MVC     MAP2OBID+1024(26),MAP2OBID
                  MVC     MAP2OLIT(4),LITC           LNIATA & CPUID
                   ---
                   ---
                   ---
                   ---
                   ---
                  XC      EBW000(18),EBW000
                  LA      R1,#MAP2O                 MAP SEQUENCE NBR
                  STH     R1,EBW000                 STORE IN WORK AREA
                  MVI     EBW002,X'80'              INDICATE NO RETURN
                  MVC     EBW006(12),PRCPL          MOVE RCPL TO WORK AREA
                  LA      R1,EBW000
                  ENTNC   ASFO                      OUTPUT MAPPING
                   ---
                   ---
                   ---
                   ---
                   ---
    LITC          DC      XL4'030802C1' LNIATA & CPUID
    PRCPL         DC      XL12'Reference Routing Control Parameter List
                          RC0PL'
                  FINIS
    

Page/Scroll Entries

Mapping activates the Page/Scroll program (03-ASC) when more than one screen is needed to complete a display. The Page/Scroll program, in turn, creates a Multiple Screen Control Record (AS5MB) for this entry. This allows the program to control each display, based on user input and information contained in the AS5MB record.

The user, at map creation time, can specify the type of display that best fits his needs. For information, see Terminal Panel Display Macro (DPANL). If SCREEN=SPLIT was specified at map create time, the Page/Scroll program can interpret input for the upper portion of the screen, the lower portion or both. This allows the user to page or scroll the upper half or lower half of the screen independently of each other. If SCREEN=FULL was specified or the default taken, the Page/Scroll program accepts input only from the last line of the screen and pages or scrolls the entire display.

The following pages provide examples of messages required to invoke the page/scroll function. The page and scroll entries are shown with their respective responses.

Example 1: Initial Page/Scroll Display

                  DEN TUL         08/04/74
                          CLASS   FARE     AIRLINES
 
                            A     88.80    AA AC AD AE AF AG
                                           BA BC BD BE BF BJ
                            T     44.07    AB AC BE
                            F     88.80    AB AC AE AT AJ AK
                                           BB BC BE
                            Y     44.07    AA AC AD AE AF AH
                                           BA BH
                            Z     44.07    AA AC AD AE AF AH
                                           BA BC BD BE BF BH
 
Agent Request:    PD2
 
 
Where:  PD2 = Page forward 2 pages.

Example 2: Response From Above Agent Request

                  DAL       F     88.80    AA-AC AD-AE AF-AH
                                           BA-BC BD-BE BF-BH
                  ELP       T     88.80    AA-AB AC-AD AE-AF
                                           BA-AB CA-BC
                            A     44.07    AB-AC CA-CD EF-AB
                                           BB-BC
 
Agent Request:  MU3
 
Where:  MU3 = Move display forward three lines.

Example 3: Response From Above Agent Request

                                           BB BA BC BD BE BF
 
                          CLASS   FARE     AIRLINE PAIRS
 
                  DAL       F     88.80    AA-AC AD-AE AF-AH
                                           BB-BC BD-BE BF-BH
                                           CA-CC CD-CE CF-CH
                  ELP       T     88.80    AA-AB AC-AD AE-AF
                                           BA-AB CA-BC
                            A     44.07    AB-AC CA-CD EF-AB
                                           BB-BC
 
Agent Request:    PT
 
Where:  PT = Redisplay page 1.

Example 4: Response To Agent "PT" Entry

                  DEN TUL                  08/04/74
                          CLASS   FARE     AIRLINES
 
                            A     88.80    AA AC AD AE AF AG
                                           BA BC BD BE BF BJ
                            T     44.07    AB AC AE
                            F     88.80    AB AC AE AI AJ AK
                                           BB BC BE
                            Y     44.07    AA AC AD AE AF AH
                                           BA BH
                            Z     44.07    AA AC AD AE AF AH
                                           BA BC BD BE BF BH
 
Agent Request:  PD12B
 
Where:  PD12B = Incorrect page request.

Example 5: Response To Above Agent Request

                  DEN TUL                  08/04/74
                          CLASS   FARE     AIRLINES
 
                            A     88.80    AA AC AD AE AF AG
                                           BA BC BD BE BF BJ
                            T     44.07    AB AC AE
                            F     88.80    AB AC AE AI AJ AK
                                           BB BC BE
                            Y     44.07    AA AC AD AE AF AH
                                           BA BH
                            Z     44.07    AA AC AD AE AF AH
                                           BA BC BD BE BF BH
 
                   INVALID FORMAT
 

Example 6: Initial Page/Scroll Display With Split Screen

                  DEN TUL                  08/04/74
                          CLASS   FARE     AIRLINES
 
                            A     88.80    AA AC AD AE AF AG
                                           BA BC BD BE BF BJ
                            T     44.07    AB AC AE
                  PB
                            F     88.80    AB AC AE AI AJ AK
                                           BB BC BE
                            Y     44.07    AA AC AD AE AF AH
                                           BA BH
                            Z     44.07    AA AC AD AE AF AH
Agent Request:   PD2
 
Where:  PB  = Page to last page.
        PD2 = Page down 2 pages.

Example 7: Response To Above Agent Request

                                           AA-AC AB-AD AF-AE
                                           BB-BC
                            Y     44.07    AB-AC
                  DAL       F     88.80    AA-AC AD-AE AF-AH
                                           BA-BC BD-BE BF-BH
                  MU3
                                           CA-CC CD-CE CF-CH
                  ELP       T     88.80    AA-AB AC-AD AE-AF
                                           BA-AB CA-BC
                            A     44.07    AB-AC CA-CD EF-AB
                                           BB-BC
 
Agent Request:   PU2
 
Where:  MU3 = Display 3 lines more from top.
        PU2 = Page up 2 pages.

Example 8: Response To Above Agent Request

                  HNL       F     88.80    AA-AB AC-AB AD-AC
                                           BC-BD
                            M     44.07    CA-CC CB-CD CE-CF
                                           AA-AC AB-AD AF-AE
                                           BB-BC
                  >
                            F     88.80    AB AC AE AI AJ AK
                                           BB BC BE
                            Y     44.07    AA AC AD AE AF AH
                                           BA BH
                            Z     44.07    AA AC AD AE AF AH
 
                   >
 
Where:  > indicates where user is to input page/scroll request
            (First character of page/scroll request overlays >
            character)