Maps

Using Online Mapping

Do not use any apostrophes in the error message text on the Extended Edit Screen. The map will get errors when the mapping compiler is used to migrate the map to production.

Do not use the INSERT and DELETE CHARACTER keys to modify your map layout. Use the space bar, or type over the existing characters to make changes.

If you want to insert a variable field into the middle of what used to be a literal field, put a '%' over the literal field to change its length then insert a field mark or '%' to start the variable field.

If you copy a map, do a FINISH or GENERATE immediately, before trying to make any changes to the map. This adds the map to IDD instead of leaving it in the queue area. Changes are not allowed until the map exists in IDD.

Terminating a MAPC Session

When you start a new MAPC session, a queue record is built to hold all the modifications you make to the map. How you end the session informs MAPC what to do with the changes you made, i.e., what to do with the queue record.

The CLEAR key or SUSPEND option will save the changes in the queue record before leaving MAPC. The next time you enter MAPC with the same map name, your previous changes and queue record will be in effect, and you can continue making further changes. The SUSPEND option is preferred over CLEARing out of MAPC.

The FINISH option updates the IDD with your changes, deletes the session's queue record, and leaves MAPC. It does not create a new map load module. (Use GENERATE to create a new map load module.)

The QUIT option deletes the session's queue record before leaving MAPC. The map is not changed in any way.Be sure to use this option if you are just looking at a map with no intention of changing it.

If you mis-key the map name and a new map is added as a result, you must delete the new map. Otherwise, an entry remains in the dictionary for the incorrect name.

Decompiling A Map

Use SPF Option DB.4 to decompile, compile, and generate a map.

Designing A Map

This is a picture of the required format of a screen: 

  sysDnnnn                      UNIVERSITY OF NEW MEXICO         mm/dd/yy 
  sysMnnn                                title of application
                                                subtitle of function

                                                 (contents of screen)

  reserved line for message
  list of function keys

The upper left corner contains the dialog and map names.

Help screens should be available in case the user gets stuck. Use dialogs UNMD5000 and UNMD5050 to create and execute generic help screens.

Avoid cramming as many fields as possible onto one screen, unless, of course, that's what the user requested.

Balance the screen so that it is pleasing to the eye. Avoid making it lopsided. Line up data-entry fields so that they are easily located by the user.

Building a Map Vertically for Repeating Rows

When creating a map sometimes it becomes necessary to repeat rows of unique fields. The following procedure will assist the the map programmer in dividing the rows into columns and building the screen vertically instead of horizontally. For example in student records a listing of all the classes and their detail associated with a particular student may be created as follows: 

Student id: xxxxxxxxx Name: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
Call #  Course               Sec   Hrs 
99999 xxxxxxxxxxxxx 999 99v9

where there may be several call # of classes the student has enrolled for.

The procedure listed below will build columns of call numbers, then course descriptions, then a column of section numbers and then of hours as the programmer specifies. By exiting the session after each column build, time may be saved and that is very important.

Creating Columns For New Data Fields In Maps

While in the fields edit screen of the MAPC Utility, enter a column of field markers where desired. When the column is complete hit enter. Hit enter a second time to initialize the FIELD SELECTION SCREEN.

While in the FIELD SELECTION SCREEN, choose an ACTION of E for edit to enter the element association in the FIELD EDIT SCREEN. Hit enter twice again, once to set the ACTION and then to exit this screen and engage the next.

We are back again in the FIELD EDIT SCREEN. Enter the element name associated with the column. Define any specific characteristics of the elements in the column (unprotected or skip for example). Hit enter once which sets the element details and locates the record name.

Leave the field edit screen by using the PF3 key. This will return you to the FIELDS SELECTION SCREEN. Now change the ACTION code to a C, for copy, and the occurs choice to Y for columns. Hit enter twice again to set the choices and to exit this screen. You will now return to the FIELD EDIT SCREEN.

Hitting enter one time associates the element and record specifications to the column. Leave this screen again by pressing PF3 - returning again to the FIELDS SELECTION SCREEN.

Now choose an ACTION of F, hit enter and as the session ends, the column will be complete, adding the elements to the map. (The option to leaving the edit screen using PF3 is to add each column member individually by hitting enter after each prompt. Then you may continue the session without having to reenter the map name. )

Pageable Mapping Hints

(copied from CA PTF #87-08-1103, modified with Release 12)

Paging Storage

Question
In the MAPC statement there is a parameter: PAGING STORAGE IS. The default is 10k of PAGING STORAGE. Is there a need to increase any of the pools (storage, program, reentrant)?
Answer
NO, PAGING STORAGE is a limit to the amount of the SCRATCH area that can be allocated to each paging session. So if the PAGING STORAGE is 100K and the page size of the scratch area is 4K at run time, the maximum amount of PAGING STORAGE that will be allocated is 100K or 25 SCRATCH PAGES.
Question
If I say "PAGING STORAGE IS 100K" will 100K be allocated to the paging session?
Answer
NO, the PAGING STORAGE is allocated by the run time system on an as-needed basis. So if one paging session needs only 5K of PAGING STORAGE that is all that paging session gets.
Question
How to determine the amount of paging storage needed for the applications that we are currently executing?
Answer
There are a couple of methods:
  1. Allocate the "Xk" of PAGING STORAGE and if that is not meeting the needs of the users allocate "Yk" until the proper amount is allocated.
  2. Use the "CULLINET SYSTEM SOFTWARE IDMS-DC/UCF MAPPING FACILITY" manual, Revision 0. 0Release 10.0December 1985 doc# TDDC-0310-10000, pages E-1 thru E-5 titled Calculating Pageable Map Storage.
    One small note to be observed on page E-2 under Amount of Storage per Detail Occurance the second bullet:
    The number of variable fields in the detail occurance multiplied by 18 (18 is the number of bytes of overhead for each variable field). That statement is valid for tapes earlier than C8509M. As of the C8509M tape the number of bytes per field has been changed to 30 to support extended attributes (color. ....).
  3. **** Use EXTREME CAUTION with this method ****
    To try different values for PAGING STORAGE without cycling the cv: Do a dcmt d mem csa. At offset x '384' is the address of the MAPC character table (OLMDS dsect the field name is CSAOLMCA). Display memory at that address. This is the RUNTIME MAPPING CONTROL BLOCK, see OLMDS, at offset x '8' is the field OLMPGSTR, max amount of storage per paging session in HEX. Vary memory at that location to the new amount of PAGING STORAGE to be used by the runtime system.

    NOTE: The above method is TEMPORARY and to make the allocation of PAGING STORAGE permanent modify the MAPC statement of the sysgen to whatever you changed OLMPGSTR to.

Question
How are PAGEABLE MAPS different from non-pageable maps?
Answer
In a few ways:
  1. Pageable maps are not automatically mapped in for you when the dialog's response process begins executing as non-pageable maps are. With a pageable map the header and footer areas of the map are treated the same as a non-pageable map (they are mapped in by the runtime system) but that is all. To get the detail lines of the pageable map GET DETAIL commands MUST BE ISSUED BY THE DIALOG. ALSO TO BE NOTED IS THE CURRENCY ISSUE. PAGEABLE MAPS use the scratch area thus when the ENTER response PROCESS TAKES CONTROL IT MUST ESTABLISH CURRENCY BY EXECUTING A GET DETAIL FIRST to get the first modified detail occurance.
  2. With a non-pageable map the entire map must be defined in MAPC. With a pageable map only the header, footer and one detail line is defined. :NOTE. Here is also the difference as far as the size of the map load modules. It will be noticed that the load module for a pageable map is smaller than a non-pageable map. It is because of what is defined in MAPC. For a non-pageable map the entire map is defined as for a pageable map only the header, footer, and 1 detail line is defined.
  3. With non-pageable maps the data can be moved to the map any time prior to the DISPLAY statement of the dialog. With pageable maps (until release 10. 2) the header and footer areas must be totally built prior to the first PUT DETAIL command.

To place column totals in the header or footer of a pageable map the amount must be accumulated before the first PUT DETAIL is issued. At the time of the first PUT DETAIL the header and footer areas of the pageable map are mapped out by the runtime system. This also goes for a message that is to be displayed in the header or footer of the pageable map even if the message field is $MESSAGE. If using $MESSAGE at least the first PUT DETAIL must contain the message, if using AGR-MESSAGE or any other variable field name the move 'xxxxx' to message must be done prior to the first PUT DETAIL.

References to release 10. 2have been made for accumulating totals. In release 10. 2there will be a new dialog option AUTO DISPLAY (Y/N). This option is for the automatic mapout of the first page of a pageable map. If NO is selected the first page of the pageable map is not automatically displayed when the first detail of the second page is put out. If YES is selected the processing is the same as always, the first page is displayed when the first detail of the second page is put.

If using $MESSAGE on a pageable map the first time page 1 is displayed the message will be displayed but, if page 1 is re-displayed within the same paging session, the message is not displayed. If the application requires that the message remain on the map, use a variable field for that message and include $MESSAGE for other messages.

Automatic Editing and Pageable Maps

In the dialog generator (ADSC) on the RESPONSE PROCESS DEFINITION screen is a field "EXECUTE ON EDIT ERRORS (YES/NO)". This is used for the header and footer section of a pageable map only, it has no affect on the detail occurances of the pageable map. If EXECUTE ON EDIT ERRORS is NO then the dialog will not retain control until there are no edit errors in the header/footer of the map.

Editing for the detail occurances of a pageable map are done when a GET DETAIL is done for the detail line. The dialog will have to check for edit errors (IF ANY FIELD IN ERROR). Also to remember, if automatic editing detects an error that data is NOT moved into the record buffer of the dialog, so extra care must be taken.

Dialog Options For Pageable Maps

Apaging request occurs when the terminal operator presses a control key associated with paging forward or backward or modifies the $PAGE field. In a map paging session, the runtime system displays the same page, displays another page, or looks for a response to execute.

Paging Type:
NOWAIT, On a paging request, it always displays the page requested. On a non-paging request, if MDT is set the same page is redisplayed if no MDT is set it looks to execute a response.
Good for browse, or scrolling thru screens then updating all changes at once.

WAIT, On a paging request with no MDT set, it executes the page request. Otherwise, it looks to execute a response.
By tying a "FWD" or "BWD" response to PF7/PF8, this is good for scrolling through and updating details as you go through.

RETURN, Always looks for a response to execute.
It is up to the programmer to direct paging requests. This mode gives complete control to the programmer.
Paging Mode:
UPDATE, Terminal operator can modify map data fields.

BROWSE, Terminal operator cannot modify map data fields.
Backpage:
YES, Allows the user to page forward and backward.

NO, As the user pages from page 1 to page 2 the runtime system deletes page 1 thus paging backward is not allowed.
Auto Display:
YES, Enables automatic display of the first page.
NO, Disables automatic display of the first page. This gives control to the programmer.

Programming Problems:

When the user sees page 1 of a pageable map displayed they hit the PF8 to page forward, but to get the second page it takes 3 minutes. The dialog does not abort or issue any messages. Why does it take so long to see page 2?

The program probably has the while loop set up like this:

OBTAIN FIRST <REC-NAME> WITHIN <AREA-NAME>.
WHILE NOT DB-END-OF-SET
REPEAT.
PUT DETAIL.
OBTAIN NEXT...
END.
DISPLAY.

In the above example the set has 10,000,000 records in it. The dialog will read all 10,000,000 records before it falls out of the loop even though there is only enough paging storage for 20 records to be displayed.

To improve response time in the above example the following should be coded:

OBTAIN FIRST <REC-NAME> WITHIN <SET-NAME>.
WHILE NOT $MAXIMUM-DETAILS-PUT
REPEAT.
PUT DETAIL.
OBTAIN NEXT...
IF DB-END-OF-SET
EXIT.
END.
DISPLAY.

The field $MAXIMUM-DETAILS-PUT ($MDP) along with many other interesting map paging status conditions can be found in the ADS/ONLINE Reference manual in section 5 under Map Paging Status Conditions. The field $MDP tells the program that they have just filled paging storage.

How Can I Take 10K of Paging Storage and Make It Look Like 100K?

Use the following outline:


  1. Create a global record for the application (or if not within an adsa application the same method can be used. Just use a queue or scratch record instead of an application global record) that contains the following:
    PAGE-NUMBER
    SUBSCRIPT
    PAGE-SWITCH (values 1=forward, 2=backward, 3=initialize)
    DBKEY-TABLE (occurs 100 times)

  2. In the premap process look at the PAGE-SWITCH:
    If PAGE-SWITCH = 3, initialize the global record and start a new session.

    If PAGE-SWITCH = 1, add 1 to SUBSCRIPT to look at the next entry in the DBKEY-TABLE for paging forward.

    If PAGE-SWITCH = 2, subtract 1 from SUBSCRIPT to look at the previous entry in the DBKEY-TABLE for paging backward.

    In the processing for the premap it must keep track of the records read (a count) and only produce a certain number of pages. For example, create only 2 pages of the pageable map. Then save the dbkey in the DBKEY-TABLE in SUBSCRIPT + 1. This is the starting dbkey for the next paging session.

  3. The DIALOG PAGING OPTION must be RETURN, thus forcing a PF7 and PF8 response for the dialog.
    The PF7 process will have set the PAGE-SWITCH to 2 (page backward) then execute next function to itself.
    The PF8 process will have to set the PAGE-SWITCH to 1 (page forward) then execute next function to itself.


table of contents prev page next page