Map Usage Example
This appendix describes a series of steps in map usage through OIVP, which is installed when the OSC system is installed.
1. Introduction
OIVP(OpenFrame Online Installation Verification Procedure) is a program to check the installation and configuration of the OpenFrame system for proper operations of its functions.
The following map usage steps are described in this appendix.
|
For details on the OIVP program, refer to OpenFrame OSC Administrator’s Guide. |
2. Writing Map and Application Source Code
First, the source code for the map and the application that will use the map must be written.
The following example shows the COBOL source code for OIVPMAIN, the main program of OIVP.
ID DIVISION.
PROGRAM-ID. OIVPMAIN.
AUTHOR. BSKIM.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-TRANS-ID PIC X(4) VALUE 'OIVP'.
01 WS-MAPSET-NAME PIC X(7) VALUE 'OIVPMS1'.
01 WS-MAP-NAME PIC X(7) VALUE 'OIVPM01'.
01 WS-RESPONSE-CODE PIC S9(8) COMP.
01 WS-COMMUNICATION-AREA PIC X(1).
01 WS-FIRST-TIME-FLAG PIC S9(4) COMP.
88 FIRST-TIME VALUE 0.
01 WS-ERROR-MESSAGE.
05 PIC X(35) VALUE '** OSC ERROR -- CONTACT HELP DESK '.
05 PIC X(35) VALUE '-- REPORT THIS INFORMATION ** '.
05 PIC X(9) VALUE SPACE.
05 WS-ERROR-LINE1.
10 PIC X(14) VALUE ' EIBTRNID = '.
10 WS-EIBTRNID PIC X(4).
10 PIC X(61) VALUE SPACES.
05 WS-ERROR-LINE2.
10 PIC X(14) VALUE ' EIBRSRCE = '.
10 WS-EIBRSRCE PIC X(8).
10 PIC X(57) VALUE SPACES.
05 WS-ERROR-LINE3.
10 PIC X(14) VALUE ' EIBRESP = '.
10 WS-EIBRESP PIC ZZZZZZZ9.
10 PIC X(57) VALUE SPACES.
05 WS-ERROR-LINE4.
10 PIC X(14) VALUE ' EIBRESP2 = '.
10 WS-EIBRESP2 PIC ZZZZZZZ9.
10 PIC X(57) VALUE SPACES.
05 PIC X(79) VALUE ALL '*'.
COPY OIVPM01.
01 DEFINITIONS-OF-EIBAID-FIELD PIC X(1).
88 ENTER-KEY VALUE ''''.
88 CLEAR-KEY VALUE '_'.
88 PF1-KEY VALUE '1'.
88 PF2-KEY VALUE '2'.
88 PF3-KEY VALUE '3'.
88 PF4-KEY VALUE '4'.
88 PF5-KEY VALUE '5'.
88 PF6-KEY VALUE '6'.
88 PF7-KEY VALUE '7'.
88 PF8-KEY VALUE '8'.
88 PF9-KEY VALUE '9'.
88 PF10-KEY VALUE ':'.
88 PF11-KEY VALUE '#'.
88 PF12-KEY VALUE '@'.
* DEFINITION OF INFORMATION
01 WS-DATE-TIME-AREA.
05 DCA-DATE PIC X(8).
05 DCA-TERM PIC X(4).
05 DCA-TIME.
10 DCA-TIME-HRS PIC z9.
10 DCA-COLON PIC X(1).
10 DCA-TIME-MIN PIC 9(2).
10 DCA-TIME-AMPM PIC X(3).
* DEFINITION OF RESOURCES
01 FILE01 PIC X(8) VALUE 'OIVPFILE'.
01 TDQ01 PIC X(8) VALUE 'OIV1'.
01 TSQ01 PIC X(8) VALUE 'OIVPTSQ'.
01 ITEM01 PIC S9(4) COMP VALUE 1.
01 LEN PIC S9(4) COMP VALUE 4.
01 LEN1 PIC S9(4) COMP VALUE 8.
01 START-KEY PIC S9(8) COMP VALUE 0.
* DEFINITION OF PEOPLE
01 DATALEN PIC S9(4) COMP VALUE 104.
01 PEOPLE-INFO-GET.
02 WS-KEY PIC S9(8) COMP.
02 WS-DATA.
05 WS-NAME PIC X(10).
05 WS-DEPARTMENT PIC X(15).
05 WS-PHONE PIC X(15).
05 WS-EMAIL PIC X(20).
05 WS-ADDRESS PIC X(40).
LINKAGE SECTION.
01 DFHCOMMAREA PIC X(1).
PROCEDURE DIVISION.
0000-MAIN.
PERFORM 5100-ALWAYS-TEST.
EVALUATE TRUE
WHEN FIRST-TIME
PERFORM 0100-FIRST-TIME
WHEN ENTER-KEY
PERFORM 0200-MENU
WHEN OTHER
PERFORM 9100-INVALID-KEY
END-EVALUATE.
PERFORM 5300-RETURN-TRANS-ID.
0100-FIRST-TIME.
MOVE LOW-VALUES TO OIVPM01O.
MOVE 'ENTER APPROPRIATE CODE OR ID' TO MSGO.
PERFORM 5200-INFO.
PERFORM 7200-SENDMAP.
0200-MENU.
PERFORM 7100-RECEIVEMAP.
EVALUATE CODEI
WHEN 'BROS'
PERFORM 0300-BROWSE
WHEN 'INQR'
PERFORM 0400-INQUIRY
WHEN 'INSR'
PERFORM 0500-INSERT
WHEN 'UPDT'
PERFORM 0600-UPDATE
WHEN 'DELT'
PERFORM 0700-DELETE
WHEN OTHER
PERFORM 9200-INVALID-CODE
END-EVALUATE.
0300-BROWSE.
EXEC CICS STARTBR
FILE(FILE01)
RIDFLD(START-KEY)
KEYLENGTH(LEN)
RESP(WS-RESPONSE-CODE)
END-EXEC.
IF WS-RESPONSE-CODE NOT EQUAL DFHRESP(NORMAL)
MOVE 'DATA DOES NOT EXIST' TO MSGO
PERFORM 7250-SENDMAP-DATA
PERFORM 5300-RETURN-TRANS-ID
END-IF.
EXEC CICS START
TRANSID('OIBR')
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC.
PERFORM 5300-RETURN-TRANS-ID.
0400-INQUIRY.
MOVE IDENI TO WS-KEY.
PERFORM 0800-CHECK-DATA.
EXEC CICS ENQ
RESOURCE('OIVPTDQW')
LENGTH(8)
END-EXEC.
EXEC CICS WRITEQ TD
QUEUE(TDQ01)
FROM(PEOPLE-INFO-GET)
LENGTH(DATALEN)
END-EXEC.
EXEC CICS DEQ
RESOURCE('OIVPTDQW')
LENGTH(8)
END-EXEC.
EXEC CICS START
TRANSID('OIIQ')
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC
PERFORM 5300-RETURN-TRANS-ID.
0500-INSERT.
EXEC CICS START
TRANSID('OIIS')
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC
PERFORM 5300-RETURN-TRANS-ID.
0600-UPDATE.
MOVE IDENI TO WS-KEY.
PERFORM 0800-CHECK-DATA.
EXEC CICS WRITEQ TS
QUEUE(TSQ01)
FROM(WS-KEY)
LENGTH(LEN1)
ITEM(ITEM01)
END-EXEC.
EXEC CICS START
TRANSID('OIUP')
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC.
PERFORM 5300-RETURN-TRANS-ID.
0700-DELETE.
MOVE IDENI TO WS-KEY.
PERFORM 0800-CHECK-DATA.
EXEC CICS WRITEQ TS
QUEUE(TSQ01)
FROM(WS-KEY)
LENGTH(LEN1)
ITEM(ITEM01)
END-EXEC.
EXEC CICS START
TRANSID('OIDE')
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC.
PERFORM 5300-RETURN-TRANS-ID.
0800-CHECK-DATA.
EXEC CICS READ
FILE(FILE01)
RIDFLD(WS-KEY)
KEYLENGTH(LEN)
INTO(PEOPLE-INFO-GET)
LENGTH(DATALEN)
RESP(WS-RESPONSE-CODE)
END-EXEC.
EVALUATE WS-RESPONSE-CODE
WHEN DFHRESP(NORMAL)
CONTINUE
WHEN DFHRESP(NOTFND)
MOVE LOW-VALUES TO OIVPM01O
MOVE 'ID ERROR' TO MSGO
PERFORM 7200-SENDMAP
PERFORM 5300-RETURN-TRANS-ID
END-EVALUATE.
5100-ALWAYS-TEST.
MOVE EIBAID TO DEFINITIONS-OF-EIBAID-FIELD.
IF CLEAR-KEY
PERFORM 5400-QUIT.
MOVE EIBCALEN TO WS-FIRST-TIME-FLAG.
5200-INFO.
EXEC CICS LINK
PROGRAM ('OIVPINFO')
COMMAREA (WS-DATE-TIME-AREA)
LENGTH (LENGTH OF WS-DATE-TIME-AREA)
END-EXEC.
MOVE DCA-DATE TO DATEO.
MOVE DCA-TERM TO TERMO.
MOVE DCA-TIME TO TIMEO.
5300-RETURN-TRANS-ID.
EXEC CICS
RETURN TRANSID (WS-TRANS-ID)
COMMAREA (WS-COMMUNICATION-AREA)
LENGTH (LENGTH OF WS-COMMUNICATION-AREA)
END-EXEC.
5400-QUIT.
EXEC CICS START
TRANSID('OIQU')
AFTER SECONDS(5)
TERMID(EIBTRMID)
RESP(WS-RESPONSE-CODE)
END-EXEC.
EXEC CICS RETURN
END-EXEC.
* PERFORM 5300-RETURN-TRANS-ID.
7100-RECEIVEMAP.
EXEC CICS RECEIVE
MAP(WS-MAP-NAME)
MAPSET(WS-MAPSET-NAME)
INTO(OIVPM01I)
RESP(WS-RESPONSE-CODE)
END-EXEC.
EVALUATE WS-RESPONSE-CODE
WHEN DFHRESP(NORMAL)
CONTINUE
WHEN DFHRESP(MAPFAIL)
MOVE 'NO CODE OR ID ENTERED' TO MSGO
PERFORM 7250-SENDMAP-DATA
PERFORM 5300-RETURN-TRANS-ID
WHEN OTHER
PERFORM 9999-ABORT
END-EVALUATE.
7200-SENDMAP.
EXEC CICS SEND
MAP(WS-MAP-NAME)
MAPSET(WS-MAPSET-NAME)
FROM(OIVPM01O)
ERASE
CURSOR
END-EXEC.
7250-SENDMAP-DATA.
EXEC CICS SEND
MAP(WS-MAP-NAME)
MAPSET(WS-MAPSET-NAME)
FROM(OIVPM01O)
DATAONLY
END-EXEC.
9100-INVALID-KEY.
MOVE LOW-VALUES TO OIVPM01O.
MOVE 'INVALID KEY ENTERED' TO MSGO.
PERFORM 7250-SENDMAP-DATA.
9200-INVALID-CODE.
MOVE LOW-VALUES TO OIVPM01O.
MOVE 'INVALID CODE ENTERED' TO MSGO.
PERFORM 7250-SENDMAP-DATA.
9999-ABORT.
MOVE EIBTRNID TO WS-EIBTRNID.
MOVE EIBRSRCE TO WS-EIBRSRCE.
MOVE EIBRESP TO WS-EIBRESP.
MOVE EIBRESP2 TO WS-EIBRESP2.
EXEC CICS SEND TEXT
FROM(WS-ERROR-MESSAGE)
ERASE
ALARM
FREEKB
END-EXEC.
EXEC CICS
RETURN
END-EXEC.
The next example shows the source code of map OIVPM001, which is used by OIVP.
OIVPMS1 DFHMSD TYPE=&SYSPARM, X
LANG=COBOL, X
MODE=INOUT, X
CTRL=FREEKB, X
STORAGE=AUTO, X
TIOAPFX=YES
OIVPM01 DFHMDI SIZE=(24,80), X
LINE=1, X
COLUMN=1
DATE DFHMDF POS=(1,2), X
LENGTH=8, X
ATTRB=(NORM,PROT,FSET)
TERM DFHMDF POS=(1,74), X
LENGTH=4, X
ATTRB=(NORM,PROT,FSET)
TIME DFHMDF POS=(2,2), X
LENGTH=8, X
ATTRB=(NORM,PROT,FSET)
DFHMDF POS=(1,24), X
LENGTH=33, X
ATTRB=(NORM,PROT), X
HILIGHT=BLINK, X
INITIAL='** WELCOME TO OPENFRAME ONLINE **'
DFHMDF POS=(3,2), X
LENGTH=77, X
ATTRB=(NORM,PROT), X
OUTLINE=OVER
DFHMDF POS=(3,80), X
LENGTH=1, X
ATTRB=(DRK,PROT)
DFHMDF POS=(4,17), X
LENGTH=46, X
ATTRB=(NORM,PROT), X
COLOR=RED, X
INITIAL='** OSC INSTALLATION VERIFICATION PROCEDURE **'
DFHMDF POS=(7,23), X
LENGTH=5, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='CODE '
CODE DFHMDF POS=(7,29), X
LENGTH=4, X
ATTRB=(NORM,UNPROT,IC), X
COLOR=BLUE, X
HILIGHT=REVERSE
DFHMDF POS=(7,34), X
LENGTH=1, X
ATTRB=(DRK,PROT)
DFHMDF POS=(7,43), X
LENGTH=4, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='ID '
IDEN DFHMDF POS=(7,48), X
LENGTH=8, X
ATTRB=(NORM,UNPROT,NUM), X
COLOR=BLUE, X
HILIGHT=REVERSE
DFHMDF POS=(7,57), X
LENGTH=1, X
ATTRB=(DRK,PROT)
DFHMDF POS=(10,22), X
LENGTH=36, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='BROS Browse data <BROS>'
DFHMDF POS=(11,22), X
LENGTH=36, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='INQR Inquiry data by ID <INQR,ID>'
DFHMDF POS=(12,22), X
LENGTH=36, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='INSR Insert data <INSR>'
DFHMDF POS=(13,22), X
LENGTH=36, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='UPDT Update data by ID <UPDT,ID>'
DFHMDF POS=(14,22), X
LENGTH=36, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='DELT Delete data by ID <DELT,ID>'
MSG DFHMDF POS=(21,2), X
LENGTH=76, X
ATTRB=(BRT,PROT), X
COLOR=YELLOW
DFHMDF POS=(23,2), X
LENGTH=77, X
ATTRB=(NORM,PROT), X
OUTLINE=OVER
DFHMDF POS=(23,80), X
LENGTH=1, X
ATTRB=(DRK,PROT)
DFHMDF POS=(24,29), X
LENGTH=49, X
ATTRB=(NORM,PROT), X
INITIAL='CopyRight(c) 2007, Tmaxsoft, All Rights ReserveX
d.'
DFHMSD TYPE=FINAL
END
3. Creating the Maps
The following example assumes that the MAPDIR key of the GENERAL section of osc.{servername} subject in the specified region’s application server configuration file is not configured. Therefore, the $OPENFRAME_HOME/osc/region/OSCOIVP1/map directory, which is the default directory, is used instead. This example also assumes that the map source code is located in the $OPENFRAME_HOME/osc/map directory.
Map source codes must be compiled with the mscasmc and mscmapc tools. The next example shows how OIVPM001.map is compiled. After preparing a deployment directory for the map files, the map files are generated and automatically deployed (with the [-r] option) to the location designated for the OSCOIVP1 region.
$ cd $OPENFRAME_HOME/osc/region/OSCOIVP1/map
$ mkdir physical
$ mkdir symbolic
$ cd symbolic
$ mkdir OIVPMS1
$ cd $OPENFRAME_HOME/osc/map
$ mscasmc OIVPM001.map
[MSCASMC] input map : OIVPM001.map
[MSCASMC] file[OIVPM001.map.atm] create ok.
$ mscmapc -r OSCOIVP OIVPM001.map.atm
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
* input map : OIVPM001.map.atm
* copybook :
[/home/oframe/OpenFrame/osc/region/OSCOIVP1/map/symbolic/OIVPMS1/OIVPMS1.cpy] create.
* binary image :
[/home/oframe/OpenFrame/osc/region/OSCOIVP1/map/physical/OIVPMS1.phy]
create.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$4. Job Compilation
The OIVPMAIN program shown in Writing Map and Application Source Code is preprocessed with the osccobprep and osccblpp tools. After that, it is compiled into the shared object format with the COBOL compiler.
The following example shows how to preprocess and then compile the program using MF-COBOL.
$ osccobprep –f .cpy –p
$ OPENFRAME_HOME/osc/region/OSCOIVP1/map/symbolic/OIVPMS1 OIVPMAIN.cob
$ osccblpp osccobprep_OIVPMAIN.cob
$ mv osccblpp_osccobprep_OIVPMAIN.cob OIVPMAIN.cbl
$ cob64 –zav –U –o OIVPMAIN.so OIVPMAIN.cbl
cob64 -C nolist -zav -U -o OIVPMAIN.so OIVPMAIN.cbl
* Micro Focus Server Express V4.0 revision 000 Compiler
* Copyright (C) 1984-2005 Micro Focus International Ltd. URN RXCAB/AA0/00000J
* Accepted - verbose
* Accepted - nolist
* Compiling OIVPMAIN.cbl
* Total Messages: 0
* Data: 7328 Code: 4825
* Micro Focus Server Express V4.0.00 Code generator
* Copyright (C) 1984-2005 Micro Focus International Ltd. All rights reserved.
* Accepted - verbose
* Generating osccblpp_osccobprep_OIVPMAIN
* Data: 7728 Code: 19664 Literals: 1472 Dynamic: 638976
Cobol program "cics_receive_map" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_writeq_td" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_writeq_ts" undefined. Assuming it will be dynamically loaded.
Cobol program "_Uia64_step" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_return" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_send_text" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_send_map" undefined. Assuming it will be dynamically loaded.
Cobol program "handle_exception" undefined. Assuming it will be dynamically loaded.
Cobol program "_Uia64_get_reg" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_startbr" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_entry" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_enq" undefined. Assuming it will be dynamically loaded.
Cobol program "_U_dyn_register" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_link" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_deq" undefined. Assuming it will be dynamically loaded.
Cobol program "_Uia64_init_local" undefined. Assuming it will be dynamically loaded.
Cobol program "_U_dyn_cancel" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_read" undefined. Assuming it will be dynamically loaded.
Cobol program "cics_start" undefined. Assuming it will be dynamically loaded.
Cobol program "_Uia64_getcontext" undefined. Assuming it will be dynamically loaded.5. OSC SD Registration
Before testing the map, resources that are used in the OSC application server must be registered to the OSC SD data set. The resources to be registered include TERMINAL, which defines a terminal used for testing; TYPETERM, which defines the terminal type; and OIVP TRANSACTION and OIVPMAIN PROGRAM, which are described previously.
The following example shows the list of resources (TERMINAL, TYPETERM, TRANSACTION, and PROGRAM) defined for OIVP testing.
DEFINE TERMINAL(TIVP)
GROUP(OIVP)
TYPETERM(TTRMOIVP)
NETNAME(TERMOIVP)
INSERVICE(YES)
DEFINE TYPETERM(TTRMOIVP)
GROUP(OIVP)
AUDIBLEALARM(YES)
COLOR(YES)
HILIGHT(YES)
IOAREALEN(512,4096)
KATAKANA(YES)
OUTLINE(YES)
PROGSYMBOLS(YES)
SOSI(YES)
TERMMODEL(2)
UCTRAN(NO)
DEVICE(3270)
USERAREALEN(128)
LOGONMSG(NO)
DEFINE PROGRAM(OIVPMAIN)
GROUP(OIVP)
LANGUAGE(COBOL)
DEFINE TRANSACTION(OIVP)
GROUP(OIVP)
PROGRAM(OIVPMAIN)
TWASIZE(255)
RESSEC(YES)
ADD GROUP(OIVP) LIST(OIVPLIST)
The defined macros are registered to the system with oscsdgen as follows:
$ oscsdgen -r OSCOIVP1 oivp.dat
6. TN3270 Emulator Settings
Before connecting to the OSC application server, the terminal emulator must be configured.
The following example shows how to set connection settings through PCOM (IBM Personal COMmunication), which is one of the terminal emulators provided by OSC.
-
Go to [PCOM] and click [Communication]> [Configuration]. When the Customize Communication dialog appears, click the [Link Parameters…] button.
Emulator Connection Settings (1) -
When the Telnet3270 dialog appears, fill in the 'Host Name or IP Address', 'LU or Pool Name', and 'Port Number' fields and click [OK].
In the following example, the gateway address is 192.168.14.88 and port number is 14100.
Emulator Connection Settings (2)
7. Testing the Maps
Check the generated maps directly by using the TN3270 emulator.
-
Once the connection to the server is established, the startup screen appears. Clear the screen by pressing the proper key (the default is the <Break> key). This key can be configured as one of the emulator’s keyboard settings.
OSC Server Start Screen -
After the screen is cleared, enter the name of the OIVP transaction registered in OSC SD Registration.
OIVP Transaction Input Screen -
The map made in Writing Map and Application Source Code will appear.
Test Screen