UMAP - Terminal Mapping Utility

UMAP is a real-time terminal mapping utility that allows you to dynamically create, modify, and test maps on a 3270-type or compatible terminal. UMAP also generates Assembler, COBOL, and PL/I source statements that define the data area passed to the Com-plete mapping system at execution time.

Note:
The UMAP utility functionally replaces the current macros MAPSTART, MAPF, and MAPEND.

This document covers the following topics:


Command Format

To invoke UMAP, enter the following command:

*UMAP

When you enter this command, a menu of the UMAP command functions is displayed. See the section UMAP Main Menu for a detailed description of this menu.

Direct Command Support

You can also access UMAP functions using direct command input.

The command format is:

*UMAP f name [operand] *

where:

f Specifies the one-character function ID as listed on the UMAP Main Menu and the UMAP Modify Map Menu.
name Specifies the four-character name of the map on which the function is to be performed. Note that the first character must be alphabetic.
operand Specifies any operands associated with the function.
* Separated by a blank, as the last character of the input string, indicates that the user is to remain in the UMAP utility instead of leaving after completion of the selected function.

Note:
When you use * as the symbol for variable fields (for example, with the SHOW function), you will remain in the UMAP utility after completion of this function.

Using UMAP

You can initiate all UMAP functions via the UMAP Main Menu, which is discussed later in this section. If you want to modify a map, choose that function on the Main Menu and you will be prompted to a (secondary) Modify Map Menu, where you can select more specific modify functions.

Map Storage

UMAP uses two storage methods.

  • SD files, for the dynamic creation and modification of maps;

  • The map library, for backup and cataloging the map for use by an application program.

SD Files

Each time you return to the Modify Map Menu, UMAP writes your map to the SD files, except when you are using the DELETE, TEST, SHOW, and SAVE functions. This feature enables you to create and/or modify the map within the SD file over an extended period of time. The name of the SD file is the same as the map name plus TID=SHR. This convention allows you to modify the maps from any compatible terminal.

You can monitor the use of the SD files by using the UUTIL function SD. For additional information, see the section on the UUTIL utility.

Map Library

To save a map in a designated map library, use the UMAP SAVE function or select the SAVE function on the Clean Up screen when you leave the UMAP utility. Note that a map is saved in the map library for backup and cataloging operations.

In z/OS, the load library is defined by the SYSMAP DD in the Com-plete procedure. This load library may be altered for an installation by user exits.

In z/VSE, the map library defined by LIBDEF PHASE,CATALOG=xxxxxx in the startup JCL.

Map Retrieval

If you do not mark the input field beside "Retrieve from COMPLIB Load Library chain" on the UMAP Main Menu, UMAP retrieves the map by first searching for a copy of the map saved in an SD file and, if no map is found there, then searching the map load library.

If you do specify retrieval from COMPLIB Load Library chain on the UMAP Main Menu, UMAP will search for the map in Com-plete's load library chain only.

Termination

UMAP Function

To terminate a UMAP function, press CLEAR, which backs you out one level at a time. For example, if you invoked a UMAP function from the Modify Map Menu, you would press CLEAR twice to return to the Main Menu. To leave the UMAP utility, press CLEAR a third time.

To return directly to the Main Menu, invoke the SAVE function. If you have outstanding SD files, UMAP first displays a Clean Up screen, shown in the following figure, giving you the choice to either:

  • Delete the SD file;

  • Save the map in the SD file into the map library and delete the SD file;

  • Retain the SD file.

Direct Exit

You can leave the UMAP utility from any map by entering only "*" and pressing ENTER. If there were any SD-files for the UMAP session, you will first be prompted by the Clean Up screen (shown in the following figure) to indicate whether you wish those files to be retained, saved, or deleted.

13:28:56     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                             -- Clean up --                               U2MF


           Map Name                     Action












The above Maps were modified in this session and remain in the SD files.
Actions:
         R - Retain Map in the SD Files.
         S - Save the Map into the Map Library and delete from the SD Files.
         D - Delete the Map from the SD Files.

UMAP Main Menu

When you enter the command *UMAP, the UMAP Main Menu will be displayed, as shown in the following figure.

13:22:19      TID    13           COM-5.1.           User ID ADMIN    09/26/97
                           -- Map Maintenance --                          U2MA
      Function             ID     PFK          Operands
 ----------------------    --     ---   --------------------------------------
             Modify Map    M        1   Mapname
       New Map Creation    N        2   Mapname
               Copy Map    C        3   Mapname, Copy from
Delete Map from SD File    D        4   Mapname
               Show Map    S        5   Mapname, Symbol
 Terminal Control Codes    T        6   Mapname
         Edit Copy Code    E        7   Mapname, (Member,) Language
  Load GDDM Symbol Sets    L        8

                  Help     ?       12   (ID)

        Select Function:       or PFK
           and Operands 
                Mapname:       F2  Retrieve from COMPLIB Load Library chain  
              Copy from:    
       Show with Symbol:    
                 Member:                                      Field Indicators
               Language:            (Asm,Cobol,PL1)             Variable  ?
                   Help:                                        Constant  +

Use the Main Menu to specify the map name and select a UMAP function together with its required operands. The UMAP Main Menu contains the following input fields:

  • A field for entering a UMAP function from the list on the menu;

  • The first four characters of the mapname;

  • A field for indicating that map retrieval is to be from the Com-plete load library chain;

  • Field(s) for the operand(s) required by each UMAP function;

  • The Help indicator.

Mapname

The mapname, a six-character code, is required to invoke all functions except "Help" and "Load GDDM Symbol Sets".

You only need to specify the first four characters, which identify the map. Note that the first character must be alphabetic.

UMAP specifies the last two characters, which is the terminal device code indicating the type of terminal for which the map was designed.

Note:
UMAP allows you to create, display, modify, and delete maps only from terminals for which the map was designed.

UMAP obtains the terminal code from a GETCHR call to Com-plete. The device codes are identified in the following table.

Device Code Line Length Number of Lines Terminal Type
F1 40 12 3277M1
F2 80 24 3277M2/3278M2
F3 80 32 3277M3/3279
F4 80 43 3278M4
F5 80 12 3278M1
F6 132 27 3278M5

Com-plete terminal mapping allows application programs to use maps with device codes other than the terminal's device code. For an explanation of map scaling, see Terminal Mapping in Terminal I/O Functions of the Com-plete Application Programming documentation.

Map Retrieval from Com-plete's Load Library Chain

To request retrieval from Com-plete's load library chain, enter any character in the input field to the right of "Retrieve from COMPLIB Load Library chain" on the UMAP Main Menu.

Note:
This option is not valid for the CREATE, DELETE, and SAVE functions.

If you do not select program library retrieval, the default retrieval is from one of the following:

  • The SD file with this map name and TID=SHR;

  • The map library.

Field Indicators

On the UMAP Main Menu, you can define the characters used to distinguish between variable and constant fields. Two field indicators are used: one to define a variable field and the other to define a constant field. Note that, when a map is displayed, the indicator immediately precedes the field that it defines.

A constant field contains permanent text that resides in the map and is displayed when the map appears on the screen.

A variable field contains a series of characters obtained from a program's calling parameter list, the number of which defines the length of the field.

Note:
If the first character of a variable field is numeric, the field is defined as numeric rather than alphanumeric.

The following table shows examples of field definition using "+" as a constant field indicator and "?" as a variable field indicator.

Example Field Type
+ADDRESS Constant field
?xxxxxxxxxx Alphanumeric variable field
?9999 Numeric variable field

UMAP Main Menu Functions

To select a function, either enter the single character function ID in the "Select Function" field or press the corresponding PF Key.

Note:
Except for the "Load GDDM Symbol Sets" and the "Help" functions, you must key in a map name when selecting a function.

HELP

To display the "UMAP Online HELP System" menu, enter a question mark (?) in the "Select Function" field, or press PF12. When the HELP screen appears, position the cursor at the field next to the desired function, and press ENTER to get help text on the function selected.

To get help for a particular function that is listed on the Main Menu, key in the single character function ID in the "Select Function" field; then either press PF12, or mark the "Help" field at the bottom of the screen and press ENTER.

The UMAP Main Menu functions are summarized in the following table and described in detail in the remainder of this section.

Function Description
Modify Map Displays the UMAP Modify Map Menu.
New Map Creation Displays a blank screen on which you may design a map and specify the desired field types and then save the map in an SD file.
Copy Map Creates a duplicate of the specified map in the SD files.
Delete Map from SD File Deletes a specified map from the SD files.
Show Map Views a mapped screen with all the specified attributes as well as the variable alphanumeric fields displayed with the designated character.
Terminal Control Codes Modifies the current Terminal Control Codes.
Edit Copy Code Edits the source code or the copy code using the Com-plete editor.
Load GDDMSymbol Sets Displays the "Load Programmed Symbols" screen where you may load GDDM-generated symbol sets into a 3279 graphics terminal and assign a symbol set ID.

Modify Map

The "Modify Map" function enables you to display the Modify Map Menu, where you can select more specific modify functions. These functions are described in a later section, UMAP Modify Map Menu.

New Map Creation

The "New Map Creation" function enables you to design, create, and store a map in the SD Files. The procedure to create a new map is as follows:

Step 1

Enter the new map name and select the "New Map Creation" function on the UMAP Main Menu.

UMAP:

  • Verifies the name, default field indicators, and default FDCs;

  • Verifies that the map does not already exist in the SD Files or the map library;

  • Displays a blank screen for you to use to define the map.

Step 2

Design the map on the terminal screen as you want it to appear in final form by inserting the appropriate field indicators immediately preceding each field.

Step 3

You can now either:

  • Press CLEAR to return to the UMAP Main Menu without creating (saving) the map, or:

  • Press ENTER if you are satisfied with the map.

    UMAP validates the information you entered. If there are no errors, the map is written into the SD files and you are passed to the UMAP Modify Map Menu.

Step 4

You can now test the new map, modify fields, or save the map. If errors exist, you are prompted with a HELP screen and the appropriate error message. To return to correct the previously entered map, press ENTER.

In this procedure, the map is written into the SD Files with the following default Terminal Control Codes:

  • Reset modified data tags;

  • Reset keyboard;

  • Erase unprotected fields;

  • Do not sound the audible alarm;

  • Allow Com-plete to determine if the screen should be erased;

  • Allow Com-plete to determine if the constant fields should be rewritten.

    Note that you can change these control codes by using the UMAP Main Menu function "Terminal Control Codes".

    Each field on the map is initially defined with the following:

  • A blank field name;

  • The user-defined screen location (x and y coordinates of the first character) and field length;

  • The default FDCs listed on the UMAP Modify Map Menu.

    Note that the extended 3279 attributes for color and symbol set ID are null.

    Variable fields have the following definitions:

  • The position in the buffer for the data for any given field is the sum of the length of all the previous fields in the buffer;

  • Numeric variable fields in the map are represented in zoned format.

    You can assign field names, alter the FDCs, and/or change the data buffer offset using the Modify Map Menu "All Fields Update" function.

  • To view the map as it will appear when displayed under program control, use the UMAP Main Menu "Show Map" function or the Modify Map Menu "Dynamic Test" function.

  • To add new fields, modify existing fields, or perform other final edits, use the Modify Map Menu "Full Screen Modify" function.

Copy Map

The "Copy Map" function enables you to make a duplicate of a map. The copy procedure is as follows:

Step 1

Enter the new map name, select the "Copy Map" function on the UMAP Main Menu, and enter the name of the map you wish to copy in the "Mapname" input field.

UMAP:

  • Verifies that the new map name does not already exist in the SD Files or the map library.

  • Displays the map to be copied so that you can verify that you selected the right map.

Step 2

You can now either:

  • Press CLEAR to terminate the function without copying and return to the UMAP Main Menu, or:

  • Press ENTER to cause a duplicate map with the new name to be written to the SD Files and return to the UMAP Modify Map Menu.

Delete Map from SD File

The "Delete Map from SD File" function enables you to delete maps in the SD Files from within the UMAP utility. The delete procedure is as follows:

Step 1

Enter the map name and select the "Delete Map from SD File" function on the UMAP Main Menu.

UMAP will display the map on the screen so that you may verify that you selected the right map.

Step 2

You can now either:

  • Press CLEAR to terminate the function without deleting the map and return to the UMAP Main Menu, or:

  • Press ENTER to delete the map and return to the UMAP Modify Map Menu.

Note that the "Delete Map from SD File" function prevents the indiscriminate deletion of a map by requiring:

  • The entry of a valid map name;

  • That the TID=SHR;

  • User verification of the map selected.

Note also that further security may be attained by using a user exit.

Show Map

The "Show Map" function enables you to view a formatted map with all the specified attributes and the variable alphanumeric fields displayed with the designated WITH character. The procedure is as follows:

Step 1

Enter the map name, select the "Show Map" function on the UMAP Main Menu, and enter the desired display character in the "Show with Symbol" input field.

UMAP displays the map with the specified symbol displayed in the alphanumeric variable fields and the numeric variable fields displayed with "9"s in the variable positions.

Your map will be written with a Write Mapped Conversational call using the MRCB fields with:

  • Blanks in the cursor out field;

  • No overriding Terminal Control Codes;

  • A blank write option.

    The data buffer fields are written with:

  • Zeros in the numeric fields;

  • The specified symbol displayed in the alphanumeric variable fields.

Note that in order to reduce buffer storage, the preceding procedure recomputes the data buffer offsets and rearranges overlapping fields. No Field Control Table is used.

Warning:
The Terminal Control Codes are not overridden in the MRCB. If the "Do not erase screen before write" TCC option (W) is defined for the map, the formatted map is written over the UMAP Main Menu.

Terminal Control Codes

The "Terminal Control Codes" function allows you to select alternate Terminal Control Codes (TCCs) for a specified map. The procedure is as follows:

Step 1

Enter the map name and select the "Terminal Control Codes" function on the UMAP Main Menu.

UMAP will display the "TCC Update for Map" screen.

Step 2

Make the desired alterations.

UMAP will process the screen until there are no errors.

Step 3

You can now either:

  • Press CLEAR to terminate the function without altering the TCCs and return to the UMAP Main Menu, or:

  • Press ENTER to update the map and write the map to the SD files.

    The TCC update screen, shown in the following figure, displays the current TCCs and allows you to alter the codes. You can also alter the TCCs either via the TCC field in the MRCB at execution time within the application program or when you use the Modify Map Menu "Dynamic Test" function.

13:30:22     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                     -- TCC Update for Map  TESTF4 --                     U2ME
Yes/No  TCC                                            Defaults
 YES    E/N         Erase unprotected fields.............Yes.
 NO     A/Q         Sound audible alarm..................No.
 NO     P/S         Start the printer....................No.
 YES    K/M         Turn off the modified data tags......Yes.
 YES    R/L         Reset the keyboard...................Yes.

Select only one
 B      B  COM-PLETE determines if erase is needed before a write (default).
        W  Do not erase screen before the write.

 F      C  Always rewrite the constant fields of this Map.
        D  Do not rewrite the constant fields.
        F  COM-PLETE determines if constant fields are to be written
           (default).

Extended 3270 Attributes

        Default Color:  BL RE PI GR TU YE NE
        Default Highlighting: B-blink, V-video, X-underline.
        Default Symbol Set ID

The Terminal Control Codes (listed in the above in the "TCC" column) are described in the following table.

TCC Description
A Sounds the audible alarm.
B Allows Com-plete to determine if the screen should be erased before the write.
C Always formats the screen for this map with constant fields.
D Does not format the screen. Even though a new map is requested, the format will not be written.
E Erases unprotected fields.
F Allows Com-plete to determine if the screen is to be formatted.
K Turns off all modified data tags.
L Does not reset the keyboard.
M Does not turn off modified data tags.
N Does not erase unprotected fields.
P Starts the printer.
Q Does not sound the audible alarm.
R Resets the keyboard.
S Does not start the printer.
W Does not erase the screen before writing the format (constant fields).

The extended 3270 attributes, as shown at the bottom of the TCC Update screen, are as follows:

Default Color Specifies the color of the default screen. This two-character color code can be used on all fields not overridden by a color code unless changed for the individual field by the Modify Map Menu "Modify with Prompt" function for the individual field. Valid codes are:
BL blue
RE red
PI pink
GR green
TU turquoise
YE yellow
NE neutral
or blank neutral
Default Highlighting Specifies the character to be used on all fields not overridden by an FDC on a field. Valid characters are:
B blink
V video
X underline
or blank null
Default Symbol Set ID Specifies a one-character symbol set ID to be used on all fields not overridden by a symbol set ID specified on a field. See the section Extended Graphics Support in Terminal I/O Functions in the Com-plete Application Programming documentation for a discussion of symbol sets.

Edit Copy Code

The "Edit Copy Code" function allows you to either produce both a copy code for the map's data buffer and a model Field Control Table (FCT) or produce the source code of the map. The procedure is as follows:

Step 1

Enter the name of the map, select the "Edit Copy Code" function on the UMAP Main Menu and enter the member name (optional) and programming language (ASM, COBOL, or PL/I) desired for copy code/FCT, or MACRO for the source code.

UMAP displays the map on the screen so that you can verify that you selected the right map.

Step 2

You can now either:

  • Press CLEAR to terminate the function without producing copy code/FCT or source code and return to the UMAP Main Menu, or:

  • Press ENTER to verify the map.

    If there are any maps remaining in the SD Files from this session, UMAP displays the Clean Up screen.

Step 3

Enter the desired Action and press ENTER.

UMAP:

  • Stores the copy code/FCT or source code in the editor work file format.

  • Fetches the editor with the recover option using the library and member name specified. Note that in z/VSE, the SUB-LIBRARY CODE is set to A for ASM, C for COBOL, P for PL/I, and M for MACRO.

Step 4

Make any desired changes and then use the UEDIT "EDIT SAVE" command to place the text into a source library to be specified.

Notes:

  1. At this point, you are operating in the UEDIT utility; that is, UEDIT has replaced UMAP as the active program in the thread. This function generates copy code for Assembler, COBOL, or PL/I. The copy code may appear very complex because any overlapping fields or fields with negative data offsets require overlayed buffer definitions.
  2. Once you are back in UMAP, to "normalize" the data buffer, use the Modify Map Menu "Rearrange Data Buffer" function.

Construction of Source Variable Names

If COBOL copy code is generated, the data buffer created has a group name of the mapname concatenated with "data-buffer". The symbol used in the Write or Read Mapped Call statement is a concatenation of the mapname and MCALL-PARM. PL/I is similar to COBOL but the Assembler names are, of necessity, very short. Note that the Assembler copy code requires that you modify the first two characters of the symbolic names.

Assembler copy code is created with the assumption that the calling parameter is aligned on a fullword boundary. All filler bytes are included in the generated code with this assumption.

For COBOL and PL/I, data buffer variables are a concatenation of the map name and field names. Names of FCT entries are a concatenation of the map name, the FCT entry field, and the map's field name. The copy code generated is skeletal and may not compile because:

  • Different levels of PL/I and COBOL compilers handle overlayed data storage differently.

  • UMAP creates variable names from a concatenation of the map name and the field name. Invalid variable names will result if a map has variable fields without field names.

  • All definitions of filler bytes use the same variable name FILLER, which is invalid in many PL/I compilers.

  • Assembler names are restricted to eight characters, the labels generated by a concatenation of ( ) and the field name. No attempt is made to label the FCT table entries.

  • The FCT generated is for an "E" format FCTE, that is, 13 characters each.

EDIT SD File Creation

The source is placed in an SD file that is retrievable via the editor. If your installation is one that requires users to log on, the SD file created is named with the mapname and the TID='SHR'. In installations not requiring logon, the SD file is named UEDIT and the TID is the actual Terminal ID. Note that the above naming conventions are for user information only.

Load GDDM Symbol Sets

The "Load GDDM Symbol Sets" function enables you to load the storage planes of a 3279 graphic terminal with GDDM-generated symbol sets.

Note:
This function can only be performed from 3279 graphics terminals.

If you select this function, the following screen is displayed.

13:31:14     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                       -- Load Programmed Symbols --

Enter:                                       Result:
- Programmed Symbol Set Name                 - Test Data
- Symbol Set Identification Character        - Storage ID Used
- Storage ID to be Loaded (optional)
- Test Data

  Symbol Set       Storage        Test                   Storage Plane
   Name        ID   Plane         Text                      Used
1.                            ........................
2.                            ........................
3.                            ........................
4.                            ........................
5.                            ........................
6.                            .........................

The procedure for loading the storage planes is as follows:

Step 1

Select the "Load GDDM Symbol Sets" function on the UMAP Main Menu.

UMAP displays the "Load Programmed Symbols" screen.

Step 2

Specify the symbol set names, a symbol set ID, and (optionally) the storage plane ID.

UMAP accesses the symbol sets by searching the STEPLIB libraries and then the VSAM file with DD name of ADMF in the Com-plete JCL. The same "Load Programmed Symbols" screen is rewritten using an extended FCT specifying the symbol set ID for each "Test Data" field.

Step 3

To see the symbols as defined in the symbol set, enter any keyboard characters into the "Test Data" input field.

The symbol sets loaded are now available for application programs testing.

For more information describing the use of programmed symbols and their creation, see the IBM User's Guide for the Graphical Data Display Manager.

UMAP Modify Map Menu

When you select the "Modify Map" function on the UMAP Main Menu and enter a mapname, the Modify Map Menu is displayed as shown in the following figure.

13:26:16     TID    13            COM-5.1.          User ID ADMIN     09/26/97
                          -- Map Maintenance --                           U2MH
                             -- Modify Map --
       Function            ID    PFK          Operands
------------------------   --    ---   ---------------------------------------
      Full Screen Modify   F       1   Mapname (preset)
      Modify with Prompt   M       2   Mapname (preset)
       All Fields Update   A       3   Mapname (preset)
  Variable Fields Update   V       4   Mapname (preset)
   Rearrange Data Buffer   R       5   Mapname (preset)
   Save Map into Library   S       6   Mapname (preset)
            Dynamic Test   D       7   Mapname (preset)

                    Help   ?      12   (ID)

         Select Function:      or PFK
                 Mapname:  TEST F4
                    Help:  

Field Indicators     New Field Default FDC   <DNHBLVX.UTPS..RO..KM..YZ..E >
  Variable  ?          Variable Alphanumeric     D     U    O   K   Y   
  Constant  +          Variable Numeric          D     U    O   K   Y   
                       Constant                  D     S        K   Y

Use the Modify Map Menu to select a UMAP modify function (the map name will already be supplied with the input from the UMAP Main Menu) and modify the field indicators and field description codes. The UMAP Modify Map Menu contains the following input fields (indicated in the preceding figure by underscores):

  • A field for entering a UMAP modify function from the list on the menu;

  • The help indicator;

  • Fields to define the two field indicators;

  • Fields to define the default Field Description Codes (FDCs).

Field Indicators

On the Modify Map Menu, you may define the characters used to distinguish between variable and constant fields. Two field indicators are used: one to define a variable field and the other to define a constant field. Note that, when a map is displayed, the indicator immediately precedes the field that it defines.

For additional information, see the subsection Field Indicators in the section UMAP Main Menu, earlier in this section.

New Field Default Field Description Codes

The Modify Map Menu displays the default Field Description Codes (FDCs) used when a field is added to a map by use of either the UMAP Main Menu "New Map Creation" function or the Modify Map Menu "Full Screen Modify" function. Note that these codes are intended only to be a starting point for initialization.

You may change the FDCs on the menu; however, the codes are only verified when you request one of the two functions mentioned above.

Valid FDCs are listed in Field Descriptor Codes of the Com-plete Application Programming documentation.

UMAP Modify Map Menu Functions

You can select a function on this menu in the same way as is described for the UMAP Main Menu functions (see the earlier section, UMAP Main Menu Functions).

The UMAP modify functions are summarized in the following table and described in detail in the remainder of this section.

Function Description
Full Screen Modify Modifies the fields within a map.
Modify with Prompt Modifies the fields within a map and updates the field attributes after each modification.
All Fields Update Modifies the name and attributes for each field on a map.
Variable Fields Update Modifies the name and attributes for each variable field.
Rearrange Data Buffer Rearranges the data fields in the buffer.
Save Map into Library Saves the map into the designated load library and deletes the SD file.
Dynamic Test Tests the user-designed map.

Full Screen Modify

The "Full Screen Modify" function enables you to add, move, delete, copy, size, or alter the attributes of the fields within a map. The procedure to modify a map is as follows:

Step 1

Enter the name of the map to be modified and select the "Modify Map" function on the UMAP Main Menu.

UMAP prompts you with the Modify Map Menu.

Step 2

Select the "Full Screen Modify" function.

UMAP displays the selected map on the screen.

Step 3

Edit the map using the valid modify procedures described below. Note that each time you modify a field, you must press ENTER.

After each modification, UMAP displays the updated map.

Step 4

To write the map to the SD Files and return to the UMAP Modify Map Menu, press the CLEAR key once.

Step 5

To return to the UMAP Main Menu, press CLEAR a second time.

Note that in this procedure, you can only modify one field each time you press ENTER. Each time you press ENTER, UMAP immediately shows you the results of the modification. The cursor is moved to the indicator position of the modified field after processing. If an error occurs, UMAP displays the error message and the Full Screen Modify HELP screen.

Note that the field indicators and cursor location control the action of this function.

The valid full screen modify operations are described below.

Note:
Pressing ENTER without making a modification to a field is considered to be an error.

Adding a Field

To add a field, enter a field indicator, the desired text, and press ENTER.

Note:
UMAP assumes that you are adding a field if you haven't altered any existing field indicators.

UMAP will backscan from the cursor location until an indicator is found. If the indicator belongs to an existing field, you will be prompted with an error message and a HELP screen. If the indicator was one that you entered, UMAP will attempt to add the new field.

Note that a field with zero length or one that would cause overlapping screen fields causes an error message and displays the HELP screen.

The new field will be assigned:

  • A blank field name;

  • Screen location and length as defined by you;

  • The default FDCs currently listed on the menu;

  • The field type as defined by the indicator and the first character of the field;

  • No color attribute code;

  • No symbol set ID.

    Variable fields will be assigned:

  • The data buffer location starting at the end of the current data buffer;

  • If the first character of the field is numeric, the field is defined as zoned.

Deleting a Field

To delete a field, replace the field's indicator with a blank and press ENTER. The map will then be displayed without the field.

Copying a Field

To copy an existing field, replace the field's indicator with a "C", move the cursor to the location on the screen where you wish the new field's indicator to be, and press ENTER.

Note that if the copy operation would result in a map with overlapping screen fields, the copy is not performed and you are prompted with an error message and the HELP screen.

The copy operation adds a new field identical to the original, except the new field has:

  • A blank field name;

  • A different screen location.

Note that variable fields have the data buffer offset starting at the end of the current data buffer.

Moving a Field

To move a field, replace the field's indicator with an "M", move the cursor to the location on the screen where you want the field to be moved, and press ENTER.

Note that if the move operation you attempt would result in overlapping screen fields, the move is not performed and you are prompted with an error message and the HELP screen.

Note:
The move operation only alters the screen location of a field. UMAP will still be able to find the fields in the data buffer.

Sizing a Field

To alter the size of an existing field, replace the field's indicator with an "S", move the cursor to the position immediately following the new end of the field, and press ENTER.

Note that if the sizing operation you attempt would result in a map with overlapping screen fields or a zero-length field, you are prompted with an error message and the HELP screen.

Be sure to consider the following when performing a sizing operation:

  • The text associated with a constant field will be the characters located between the field indicator and the cursor location with trailing blanks removed.

  • For alphanumeric and zoned fields only, you must change the length of the field in the data buffer if you change the length of the field on the screen. The sizing operation does not affect the data buffer locations of other fields. Thus, lengthening a field will cause it to overlap the next field's buffer position and shortening a field means a field of filler will exist before the next field's buffer position.

Updating Attributes

To access the Attribute Update screen for a field, replace the field's indicator with a "U" and press ENTER. The Attribute Update screen for that field will then be displayed; it is described in detail later in this section.

Note that each attribute update only affects the field you're currently altering; that is, a change in one field's data buffer offset does not affect the buffer offsets of any other field.

When you press ENTER, the modifications are made and you are returned to the map display.

Modify with Prompt

The "Modify with Prompt" function is identical to the Modify Map Menu "Full Screen Modify" function except that UMAP automatically displays the Attribute Update screen after each field modification. This option is useful for updating the attributes of modified fields and adding new fields. The Attribute Update screen is described later in this section.

All Fields Update

The "All Fields Update" function enables you to verify and/or modify the attributes for every field on the map using the Attribute Update screen (described later in this section). The procedure is as follows:

Step 1

Enter the name of the map and select the "Modify Map" function on the UMAP Main Menu.

UMAP prompts you with the UMAP Modify Map Menu.

Step 2

Select the "All Fields Update" function on the Modify Map Menu.

UMAP displays the Attribute Update screen, shown in the following figure, for the first field on the map.

Step 3

Modify the attributes as desired.

Step 4

To display the attributes for the next field on the map, press ENTER.

Step 5

To write the map to the SD Files and return to the UMAP Modify Menu, press CLEAR.

Step 6

To return to the UMAP Main Menu, press CLEAR a second time.

Note that when you update attributes, it only affects the field you're currently altering, that is, changing one field's data buffer offset does not affect the buffer offset of any other field.

Attribute Update Screen

The appearance of the Attribute Update screen depends on the type of field being updated. The following figure shows the Attribute Update screen for a constant field.

13:32:20     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                 -- Attribute Update in Map TESTF4 --                     U2MB
                                                     Field Name .....: M04010
FDC    (select one from each group)                  Location ........( 3  2 )
 D D=display, N=nondisplay, H=high, B=blink,         Screen Length ..:    13
      V=video, L=light pen, X=underline;
 S U=unprotected, P=protected, S=skip,
      T=tab (variable only);
   O=optional, R=required (variable only);
 K M=set MDT on (variable only), K=set MDT off;      Color ..........:   
 Y Y=skip may end field, Z=skip may not end field;   ( bl gr ne pi re tu ye )
   ' '=no erase, E=erase (variable only).            Symbol Set ID ..:     


+JKLFSDAJKLFDS
...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....

+KAJHSDFKJHASDF

Common input fields on the preceding screen for constant and variable fields are:

Field Name Displays the field name.
Note that the field name must be either blank or a field name that is unique for this map.
Location Displays the row and column location of the first character in the field.
Screen Length Displays the number of characters used by the field.
FDC Displays the Field Description Codes (FDCs) currently applied to the field.
(select one from each group) Lists the valid FDC(s) and their meaning(s).
bottom half Displays a window of the selected field within the map. The row of screen/tab/containing the selected field will be shown above the row scale.

The Attribute Update screen for variable fields also displays the following data elements:

Type Displays the type of data. Valid data types are:
A alphanumeric
P numeric (packed)
Z numeric (zoned)
F numeric (fullword)
H numeric (halfword)
Note that alphanumeric data types can not be modified. Numeric data types, however, can be modified to other numeric data types.
Buffer Offset Displays the data buffer offset for the field.
Note that the offset must be a positive or negative integer. Altering a field's data buffer offset has no affect on any other field's data buffer offset.

Note:
Buffer offset modifications may cause overlapping fields and fields with negative buffer offsets.

Color Displays the color code of this field. Valid codes are:
bl blue
re red
pi pink
gr green
tu turquoise
ye yellow
ne neutral
or blank neutral
Symbol Set ID Displays the one-character symbol set ID. Valid codes are:
blank none
nonblank character greater than x'40' value

The Attribute Update screen for numeric variable fields also displays the following data elements:

Decimal Places Displays the number of decimal places for fullword and halfword fields only.
Packed Length Displays the internal length for packed numeric fields only.

Variable Fields Update

The "Variable Fields Update" function is identical to the previous function ("All Fields Update") except that the sequence of Attribute Update screens is limited to the variable fields for a selected map.

Rearrange Data Buffer

The "Rearrange Data Buffer" function enables you to manipulate the data buffer of a map while remaining totally independent of the screen locations and without the need to compute the data offsets. The procedure to arrange the data buffer is as follows:

Step 1

Enter the name of the desired map and select the "Modify Map" function on the UMAP Main Menu.

UMAP prompts you with the UMAP Modify Map Menu.

Step 2

Select the "Rearrange Data Buffer" function on the Modify Map Menu.

Note:
If the map has overlapping data fields or fields with negative data offsets, UMAP recomputes the data offsets and retains the previous ordering.

UMAP displays the Arrange Data Buffer screen which lists the current buffer arrangement and the arrange data buffer operations.

Step 3

You can perform any of the listed operations.

Step 4

To write the map to the SD Files and return to the Modify Map Menu, press CLEAR.

Step 5

To return to the UMAP Main Menu, press CLEAR a second time.

Note that in this procedure, if there are fields overlapping or fields that have negative data offsets as a result from modifying the map, UMAP will recompute the data buffer offsets. If overlapping fields and/or fields with negative data offsets are required, you can modify the data offsets on a field-by-field basis using the Attribute Update screen. This function enforces the normal practice of placing all data buffer locations after the calling buffer parameter.

The Arrange Data Buffer screen lists the variable data fields as they currently exist in the data buffer, giving the field name, field type, and field length. Note that the gaps between the fields of the data buffer are displayed as implicit pad fields.

The Arrange Data Buffer screen, shown in the following figure, enables you to perform six data buffer operations. To select an operation, enter any character in the field preceding the desired function. Note that an underscore in the following figure indicates a data entry field.

Note:
Most operations require the fields to have field names.

13:33:32     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                 -- Arrange Data Buffer for Map TESTF4 --                 U2MD

  Move        before        .                    Pad   0 bytes before       .
  Move        after         .                    Pad   0 bytes after        .
  Align binary fields.                           Remove all padding.

       A 0007

Using the Arrange Data Buffer screen causes UMAP to process one operation at a time. After each operation, the data buffer screen is redisplayed.

The arrange data buffer operations are described in the following table.

Operation Instructions Result
Move xxxxxx before yyyyyy Enter the names of the fields to be moved. All existing filler bytes (i.e., padding) will be retained in their respective places.
Move xxxxxx after yyyyyy Enter the names of the fields to be moved. All existing filler bytes(i.e., padding) will be retained in their respective places.
Align binary fields Enter any character in the input field. The data buffer fields will be shifted in order to ensure the alignment of binary fullword and halfword fields. Note that the number of filler bytes between fields is not reduced.
Pad nnn bytes before xxxxxx Enter the number of filler bytes to be added to the data buffer immediately preceding the field xxxxxx. A negative nnn will reduce an existing pad by nnn bytes. Note that other filler bytes are not affected.
Pad nnn bytes after xxxxxx Enter the number of filler bytes to be added to the data buffer immediately following the field xxxxxx. A negative nnn will reduce an existing pad by nnn bytes. Note that other filler bytes are not affected.
Remove all padding Enter any character in the input field. The data buffer offsets are recomputed so that no filler bytes remain between the data buffer fields. Note that non-aligned binary halfwords and fullwords may result.

Note:
Because there is no explicit definition of filler bytes within a map, the addition of padding will cause an error if you attempt to add filler to the end of a data buffer.

Alternative Method

There is another method to reorder the data fields in a large map in an arbitrary sequence. The procedure is listed below.

Step 1

Assign the data buffer offset for each field (all or just variable) on the Attribute Update Screen.

Step 2

Then use the Modify Map Menu "Rearrange Data Buffer" function to detect overlapping fields and recompute the data buffer offsets while retaining the desired sequence of the fields.

Save Map into Library

The "Save Map into Library" function enables you to save the map in a map library in order to:

  • Enable the use of the map by an application program;

  • Create a backup.

The procedure for this function is as follows:

Step 1

Enter the mapname on the UMAP Main Menu and select the "Modify Map" function.

UMAP prompts you with the Modify Map Menu.

Step 2

Select the "Save Map into Library" function on the UMAP Modify Map Menu.

UMAP displays the map on the screen so that you can verify that you selected the correct map.

Step 3

You can now either:

  • Press CLEAR to abort the function and return to the UMAP Modify Map menu, or:

  • Press ENTER to save the map in the map library.

    VSE: an object-module is created and saved. A linkjob is submitted to build the phase. The job has the name of the map and runs in class 0. If you want to change the defaults set applymod 36. The JOB and LST card will be displayed and you can modify them. A ULIB REF is necessary to activate the new/modified map.

    UMAP saves your map in the designated map library, delete the associated SD file, and return you to the UMAP Main Menu.

On VSE, UMAP uses the official Librarian interface, which does not permit cataloguing phases. Therefore UMAP builds the object module and submits a link job for the map. By default this link job uses the name of the map as a job name. The installation can set Applymod 36 in order to allow users to change the JOB and LST cards before the job is submitted. In order to activate the changed/new map, you have to issue a ULIB REFresh command.

Dynamic Test

The "Dynamic Test" function enables you to experiment with a selected map before using the map under application program control. You can enter an MRCB, FCT, and DATA BUFFER and then see how the map would react using the WRTMC and READM functions.

The test procedure is as follows:

Step 1

Enter the map name on the UMAP Main Menu and select the "Modify Map" function.

UMAP prompts you with the Modify Map Menu.

Step 2

On the UMAP Modify Map Menu, select the "Dynamic Test" function.

UMAP retrieves the selected map and displays a sequence of the following (press ENTER repeatedly):

  • The MRCB/FCT screen;

  • One or more data buffer screens;

  • The selected map.

Step 4

To return to the UMAP Modify Map Menu, press CLEAR once.

Step 5

To return to the UMAP Main Menu, press CLEAR a second time.

With Com-plete mapping support, your map is formatted by a Write Mapped Conversational (WRTMC) call using information from:

  • The map;

  • The MRCB you specified on the MRCB/FCT screen;

  • The data buffer you specified on the DATA BUFFER screen(s);

  • The Field Control Table you specified on the MRCB/FCT screen.

    The function reads the contents of the screen using a Mapped Read (READM), which modifies information in:

  • The data buffer fields;

  • The MRCB;

  • The Field Control Table (FCT).

    Each screen in the test cycle is described below.

MRCB/FCT Screen

The MRCB/FCT screen, shown in the following figure, displays the MRCB and FCT to be used during a Write Mapped Conversational call and a Read Mapped call.

One field that is not part of the MRCB or FCT is the "Use FCT?" field. Entering a character in this field causes the FCT to be included in the parameter lists for the Write Mapped Conversational call and the Read Mapped call of your map. Note that a character entered in this field also causes the "FCTE Count" of the MRCB to be set to 20.

13:34:24     TID    13           COM-5.1.           User ID ADMIN     09/26/97
                             -- Test Map --                               U2MC
           MRCB AREA                                  FCT AREA
Mapname .............:     TEST                 Use FCT?
Map Count ...........:        0                 FCT Entries:
FCTE Count ..........:        0                 nnnnnnifffccs nnnnnnifffccs
FCTE Format..........:        E
Write Option ........:
Read Option .........:
TCC Codes ...........:
Cursor Out ..........:   MAPNAM
Cursor In ...........:
Return Code .........:        0
Enter Code ..........:       00
Fields Read .........:        1
Field Errors ........:        0
Feedback Length .....:      154                      (nnnnnn=field-name
                                                      i     =input-flag
                                                      fff   =fdc
                                                      cc    =color
Feed Back Area                                        s     =symbol-set)

The "FCTE Format" field allows you to specify the FCT format. The valid choices are described in the following table:

Abbreviation Format FCTE Length
blank or "S" short 6
"L" long 10
"E" extended 13

Note that the Modify Map Menu "Dynamic Test" function does not edit the FCT format field. The contents of this field are edited by Com-plete mapping at the time of your map's WRTMC call.

Note:
If you enter invalid data, UMAP abends the same way that any application program would abend.

The format of the FCT entries is described in Field Control Table (FCT) of the Com-plete Application Programming documentation.

Data Buffer Screen

The Data Buffer screen lists each variable field defined on your map in the format shown in the following figure.

13:35:17     TID    13           COM-5.1.          User ID ADMIN     09/26/97
DATA  RR/CC FIELD  T         VALUE                                       HEX?
OFFS         NAME  Y DISPLAY  AND  HEX
 0000 09 02        A
                   Z

The Data Buffer screen displays:

  • The hex option field;

  • The field data buffer offsets;

  • The location of the field on the screen, in row and column format;

  • The field name;

  • The field type;

  • The field data buffer areas;

  • The hex representation of numeric fields.

You may enter data into the data buffer.

Note that numeric fields allow you to enter the largest value according to the internal data length.

Alphanumeric fields are truncated to forty characters. Note that, in order to reduce buffer storage requirements and remove overlapping fields, the data fields will appear in buffer sequence even though the data offsets have actually been altered.

By default, the contents of a numeric field are used in the display of the hex representation of the numeric field. When you specify the hex option, the contents of the hex representation are translated into the numeric data buffer locations for display on your mapped screen.

Warning:
The above translation is not edited for valid hex codes.

User Map

You are then presented with your formatted map written with a Write Mapped Conversational call, using the MRCB from the MRCB/FCT screen, data from the data buffer screen, and (optionally) the FCT from the MRCB/FCT screen.

You can now enter data on this screen that, in turn, will be reflected in the MRCB, data buffer, and FCT.

The cycle is repeated with the MRCB/FCT screen and the data buffer screens displaying the results of the Read Mapped call.

To terminate the Modify Map Menu "Dynamic Test" function and return to the UMAP Modify Map Menu, press CLEAR.

Note:
The "Dynamic Test" function does very little editing. A faulty map or MRCB that would abend a user routine also abends the "Dynamic Test" function.