IBM MVS/OS390 Software installation guide. Cobol II, LE edition for OS390/VSE with CICS.
Since November 2002 Hopewiser have simplified the software load process for IBM customers. To this end all IBM software releases are now produced directly from our in house IBM platforms. This allows release of software in a simple form from any of our IBM platforms directly to our customers using standard tools. Current in house IBM systems include VSE,OS390,MVS,OS400. Preferred release media is 3490 however releases are also supported on 3480, 9-Track, DAT and CDROM. All current IBM solutions are COBOL LE, COBOL II compliant.
Hopewiser produce several packaged software solutions for many varied platforms. The release contents will depend on the options and solution purchased. Hopewiser’s flagship product, ATLAS, can be supplemented with additional products such as the Name Analyser, Deduplicator, Voters Roll lookup etc. Each released product is self-contained on a single distribution medium and will arrive separately.
Most of Hopewiser’s products require access to a Hopewiser database. For example ATLAS requires the PAF files to be present. (PAF = Postal Address File). Database files are supplied separately and updated periodically as base information changes. PAF files for UK addresses are updated quarterly, other products are similarly updated as required. Database updates do not require any software changes.
All of Hopewiser’s IBM products are installed in an identical manner. Please see the relevant section of Appendix A for Product specific information.
Installation requires no more than a copy of the product to your system. System changes are not required however if you have purchased CICS options there are some optional entries to CICS tables that are described later.
Installation media is created in IEBCOPY format for MVS/ZOS users or LIBRARY BACKUP for VSE uses . There are 3 batch PDS/Sublibraries followed by an optional 4 CICS PDS/Sublibraries.
The following JCL can be used to load the released product on an OS390/ZOS platform. This JCL is available via Email on request or from our Website WWW.HOPEWISER.COM or WWW.HOPEWISER.COM.AU and will require slight modification to suit your particular needs/site configuration. VSE users can restore the release tape by using LIBRARY RESTORE from the operations menu.
Example JCL shows ATLAS PDS with CICS option but can be used with any of Hopewiser’s IBM product range by simply altering the letters ATL (lines 3,14) to a 3 or 4 character name of your choice.
000001 //P390AILD JOB (0000),'HPW PDS LOAD',NOTIFY=&SYSUID,CLASS=A,MSGCLASS=8 000002 //********************************************************************** 000003 //* 000004 //CPDS PROC ODS=,BK=,LR=,ID=,PS=,F=,DST=TESTTP.ATL,VOL=OS3PAD 000005 //BCOBOL EXEC PGM=IEFBR14 000006 //PDS DD DSN=&DST&ODS, 000007 // DCB=(DSORG=PO,RECFM=&F,BLKSIZE=&BK,LRECL=&LR), 000008 // UNIT=SYSDA,VOL=SER=&VOL, 000009 // DISP=(NEW,CATLG,DELETE), 000010 // SPACE=(CYL,(5,5,80)) 000011 //* 000012 //IEBCOPY EXEC PGM=IEBCOPY 000013 //SYSPRINT DD SYSOUT=* 000014 //SYSUT2 DD DSN=&DST&ODS,VOL=SER=&VOL,UNIT=SYSDA,DISP=SHR 000015 //SYSUT1 DD DSN=HPW.RELEASE.&ID,DISP=(NEW,KEEP),UNIT=570, 000016 // VOL=(PRIVATE,RETAIN,SER=ATL24A),LABEL=(&PS,SL) 000017 //SYSUT3 DD DSN=TEMP1,UNIT=SYSDA,VOL=SER=WORK01,DISP=(NEW,DELETE), 000018 // SPACE=(CYL,(5,2)) 000019 //SYSIN DD DUMMY 000020 // PEND 000021 //********************************************************************** 000022 //BRTN EXEC CPDS,ODS=BRTL.EXAM,BK=3120,LR=80,ID=EXAM,PS=1,F=FB 000023 //BRTC EXEC CPDS,ODS=BRTL.COBOL,BK=3120,LR=80,ID=BATCH.RTLCOB,PS=2,F=FB 000024 //BRTL EXEC CPDS,ODS=BRTL.LOAD,BK=8192,LR=0,ID=BATCH.LOAD,PS=3,F=U 000025 //BRTO EXEC CPDS,ODS=BRTL.OBJ,BK=3120,LR=80,ID=BATCH.OBJ,PS=4,F=FB 000026 //CRTC EXEC CPDS,ODS=CRTL.COBOL,BK=3120,LR=80,ID=CICS.RTLCOB,PS=5,F=FB 000027 //CRTM EXEC CPDS,ODS=CRTL.MAP,BK=3120,LR=80,ID=CICS.MAP,PS=6,F=FB 000028 //CRTL EXEC CPDS,ODS=CRTL.LOAD,BK=8192,LR=0,ID=CICS.LOAD,PS=7,F=U 000029 //CRTO EXEC CPDS,ODS=CRTL.OBJ,BK=3120,LR=80,ID=CICS.OBJ,PS=8,F=FB ****** **************************** Bottom of Data ****************************
JCL Description.
| Line numbers | Description | Action Required for your site |
|---|---|---|
| 000001 - 000003 | Job Card |
Line 000001 Notify, Class, Msgclass should be altered to reflect your preferences |
| 000004 - 000010 | Create and catalogue new PDS |
Line 000004 DST= Change TESTTP.ATL to a prefix of your choice. Eg for Voters roll in your test system, DST could be:- DST=MYTEST.VROL Please limit the extension (the items after the . ) to a maximum of 4 characters. Line 000004 VOL = Change VOL=SER=OS3PAD to reflect you required destination device |
| 000011 - 000020 | Populate PDS |
Line 000014 UNIT = Change UNIT = 570 to be a valid device for the supplied media type. Line 000015 SER = Update for tape label supplied. Line 000016 VOL=SER= Set volume ID for temporary storage space |
| 000021 - 000029 | Exec statements one for each PDS supplied | Delete lines 000026 – 000029 if the CICS option has not been purchased. |
Please see Appendix A for a description of PDS and members for your software solution.
Using ‘Restore Library Objects’ ( 3-7-2 from Main Menu)
SVR$LRS1 RESTORE VSE LIBRARY FROM TAPE
Enter the required data and press ENTER.
LIBRARY NAME................. RELEASB Name of library to be restored.
Use * for entire backup file.
Press PF5 to finish the selection.
SUBLIBRARY NAME.............. ________ Enter name for sublibrary selection
MEMBER NAME.................. ________ Enter name for member selection
MEMBER TYPE.................. ________ Enter type for member selection
Does the backup file have an identification (mnemonic-id)?
Use * to restore the complete tape.
IDENTIFICATION............... ATL24A__ ________
NEWNAME...................... 2 1 to restore under a new name,
else 2
TIME STAMP................... 2 1 to keep the old date,
else 2
LIST......................... 1 1 for a listing, else 2
OLD FORMAT................... 2 1 for libraries in old form,
else 2
PF1=HELP 2=REDISPLAY 3=END 5=PROCESS
There are normally two release libraries on a software release tape. RELEASB & RELEASC. ReleasC is only present where CICS options have been purchased.
Restore the Libraries as in the example above changing only the IDENTIFICATION to that of the supplied tape.
Please now refer to Appendix A for further description of the products.
The following relates to Hopewiser ATLAS only.
Atlas requires the PAF database to operate. This currently consists of 14 files that must be logically assigned to allow Atlas execution. Please ensure the following DDNAMES are available to ATLAS at runtime. Alter PREFIX to reflect your chosen storage location.
DDNAMES required for ATLAS
MVS/ZOS users
//CATLPDAT DD DSN=PREFIX.ATLAS.PDAT, DISP=SHR //CATLALFA DD DSN=PREFIX.ATLAS.ALFA, DISP=SHR //ATLTOWN DD DSN=PREFIX.ATLAS.TOWN, DISP=SHR //ATLTOWN1 DD DSN=PREFIX.ATLAS.TOWN.PATH1, DISP=SHR //ATLTOWN2 DD DSN=PREFIX.ATLAS.TOWN.PATH2, DISP=SHR //ATLDIST DD DSN=PREFIX.ATLAS.DIST, DISP=SHR //ATLDIST1 DD DSN=PREFIX.ATLAS.DIST.PATH1, DISP=SHR //ATLDIST2 DD DSN=PREFIX.ATLAS.DIST.PATH2, DISP=SHR //CATLADDR DD DSN=PREFIX.ATLAS.ADDR, DISP=SHR //CATLPCIX DD DSN=PREFIX.ATLAS.PCIX, DISP=SHR //CATLHOUS DD DSN=PREFIX.ATLAS.HOUS, DISP=SHR //CATLOCI XDD DSN=PREFIX.ATLAS.OCIX, DISP=SHR //CATLSTRT DD DSN=PREFIX.ATLAS.STRT, DISP=SHR //CATLPREM DD DSN=PREFIX.ATLAS.PREM, DISP=SHR
VSE Users
// DLBL CATLPDA,’PREFIX.ATL.PDAT ',,VSAM,CAT=SYSWK2 // DLBL CATLALF,’PREFIX.ATL.ALFA',,VSAM,CAT=SYSWK2 // DLBL ATLTOW1,’PREFIX.ATL.TOWN.PATH1',,VSAM,CAT=SYSWK2 // DLBL ATLTOW2,’PREFIX.ATL.TOWN.PATH2',,VSAM,CAT=SYSWK2 // DLBL ATLTOWN,’PREFIX.ATL.TOWN',,VSAM,CAT=SYSWK2 // DLBL ATLDIS1,’PREFIX.ATL.DIST.PATH1',,VSAM,CAT=SYSWK2 // DLBL ATLDIS2,’PREFIX.ATL.DIST.PATH2',,VSAM,CAT=SYSWK2 // DLBL ATLDIST,’PREFIX.ATL.DIST',,VSAM,CAT=SYSWK2 // DLBL CATLADD,’PREFIX.ATL.ADDR',,VSAM,CAT=SYSWK2 // DLBL CATLPCI,’PREFIX.ATL.PCIX',,VSAM,CAT=SYSWK2 // DLBL CATLHOU,’PREFIX.ATL.HOUS',,VSAM,CAT=SYSWK2 // DLBL CATLOCI,’PREFIX.ATL.OCIX',,VSAM,CAT=SYSWK2 // DLBL CATLSTR,’PREFIX.ATL.STRT',,VSAM,CAT=SYSWK2 // DLBL CATLPRE,’PREFIX.ATL.PREM',,VSAM,CAT=SYSWK2
DLBL statements, you will need to modify SYSWK2 and the file prefix to reflect your chosen storage location.
Below follows definitions required by CICS to execute ATLAS. You may then make definitions to CICS using CEDA and CEMT or modify your CICS startup to include PCT,FCT entries. VSE systems will also require the DLBL entries above.
PPT/PCT/FCT entries for ATLAS
To run Atlas or any of the demo programs, PCT and PPT entries for them AND the mapsets HPWM22 &
HPWM22A need to be entered in to the tables for CICS. The load modules and Mapsets must be placed into
the load library for the CICS system and the database files must be defined to CICS.
PCT Entries
DFHPCT TYPE=ENTRY, TRANSID=ATLA, PROGRAM=EH22CICS
PPT Entries
DFHPPT TYPE=ENTRY,PGMLANG=COBOL,PROGRAM=EH22CICS
DFHPPT TYPE=ENTRY,MAPSET=HPWM22
FCT Entries
DFHFCT TYPE=DATASET,DATASET=CATLPDAT,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.PDAT, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLALFA,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.ALFA, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLTOWN,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.TOWN, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLTOWN1,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.TOWN.PATH1,FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLTOWN2,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.TOWN.PATH2, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLDIST,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.DIST, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLDIST1,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.DIST.PATH1, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=ATLDIST2,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.DIST.PATH2, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLADDR,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.ADDR, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLPCIX,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.PCIX, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLHOUS,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.HOUS, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLOCIX,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.OCIX, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLSTRT,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.STRT, FILSTAT(ENABLED,OPENED)
DFHFCT TYPE=DATASET,DATASET=CATLPREM,
ACCMETH=VSAM, SERVREQ=(BROWSE,READ), DISP=SHR,
DSNAME=PREFIX.ATLAS.PREM, FILSTAT(ENABLED,OPENED)
Required DFHFCT entries for VSE systems - note 7 char Dataset name
Vse FCT entries are as above however VSE uses 7 byte filenames thus the names above are shortened as below
DFHFCT TYPE=DATASET,DATASET=CATLPDA,
DFHFCT TYPE=DATASET,DATASET=CATLALF,
DFHFCT TYPE=DATASET,DATASET=ATLTOWN,
DFHFCT TYPE=DATASET,DATASET=ATLTOW1,
DFHFCT TYPE=DATASET,DATASET=ATLTOW2,
DFHFCT TYPE=DATASET,DATASET=ATLDIST,
DFHFCT TYPE=DATASET,DATASET=ATLDIS1,
DFHFCT TYPE=DATASET,DATASET=ATLDIS2,
DFHFCT TYPE=DATASET,DATASET=CATLADD,
DFHFCT TYPE=DATASET,DATASET=CATLPCI,
DFHFCT TYPE=DATASET,DATASET=CATLHOU,
DFHFCT TYPE=DATASET,DATASET=CATLOCI,
DFHFCT TYPE=DATASET,DATASET=CATLSTR,
DFHFCT TYPE=DATASET,DATASET=CATLPRE,
Libraries provided can and should be copied/named in accordance with your site naming conventions. Future releases will have the same library/PDS names and could potentially overwrite your current system if you use our naming convention.
IBM MVS/ZOS customers
Menu Options View Utilities Compilers Help
------------------------------------------------------------------------------
DSLIST - Data Sets Matching HPW.RELEASE Row 1 of 8
Command ===> Scroll ===> CSR
Command - Enter "/" to select action Message Volume
-------------------------------------------------------------------------------
HPW.RELEASE.BATCH.LOAD *Batch Load Modules (Dynamic)OS3PAC
HPW.RELEASE.BATCH.OBJ *Batch Object Code (static) OS3PAC
HPW.RELEASE.BATCH.RTLCOB *Example source / copybooks OS3PAC
HPW.RELEASE.CICS.LOAD *Cics Demo Programs OS3PAC
HPW.RELEASE.CICS.MAP *Map source for Demo progs OS3PAC
HPW.RELEASE.CICS.OBJ *Cics Object Code OS3PAC
HPW.RELEASE.CICS.RTLCOB *Example source / copybooks OS3PAC
HPW.RELEASE.EXAM *Clists,example loads OS3PAC
***************************** End of Data Set list ****************************
IBM VSE Customers
LIB=RELEASB * Batch System
SUBLIB=RELEASB.LOAD REPLACE=YES *Batch Phases
SUBLIB=RELEASB.OBJ REPLACE=YES *Batch Object Code
SUBLIB=RELEASB.RTLCOB REPLACE=YES *Batch Source/copybooks
LIB=RELEASC * CICS System
SUBLIB=RELEASC.LOAD REPLACE=YES *Cics Phases
SUBLIB=RELEASC.OBJ REPLACE=YES *Cics Object Code
SUBLIB=RELEASC.MAP REPLACE=YES *Source to Demo Map
SUBLIB=RELEASC.RTLCOB REPLACE=YES *Source Example/copybooks
AH22INTR
This is a module used to demonstrate the facilities of ATLAS. This program is intended for use under TSO, and is executed by the Clist AH22INTR found in EXAM Pds. In order to provide a working programming example the source code to this program is available in the BRTL.COBOL dataset. The Clist will require some minor modification to reflect your chosen storage location.
Running the Harness
This ATLAS Enquiry facility utilises both the Postcode to Address (AH21) and Address to Postcode (AH23) modules. It also uses the optional gazetteers providing more extensive searching capability.
The harness has the same functionality as the CICS example program AH22CICG documented below. In TSO/BATCH the demo program starts by asking for a postcode input, pressing enter moves to Addr-line-1, Addr-line-2, District, Town and finally State/County. You may need to press enter more than once to advance to the next line. Try some of the examples documented in the AH22CICS section below. a A free format address is expected however take care to enter address items to the expected input line when using gazetteer functions.
AH22CICG
is the main program which allows address input for postcoding, or for postcode index search . Source to this program is available in the CRTL.COBOL dataset. Note the calls to AH23CODE etc. The calling application calls ATLAS in the same way as does a BATCH program, just add DFHEIBLK and DFHCOMMAREA as the first two parameters to each call e.g.
CALL 'AH23CODE'
USING DFHEIBLK DFHCOMMAREA
ATLAS-GLOBAL-DATA
MATCH-INPUT-ADDRESS
MATCH-OUTPUT-ADDRESS
MATCH-CONTROL.
AH22CICS
Same program as above but simplified by removing Gazetteer functionality. Use this program if you have not purchased Gazetteers or for simple reference of source code.
AH22CIDS
Exactly as AH22CICS but demonstrating DYNAMIC CICS calls using EXEC CICS function.
The ATLAS interactive harness AH22CICG
AH22CICG Postcode to Address / Address to Postcode /Gazetteer
The program AH22CICG provides interactive access to the ATLAS modules. The Program is invoked by transaction on the CICS system.
On entry into the program the user is presented with an Input Screen with the cursor Positioned at the beginning of the first line. This screen provides access to ATLAS Modules.
To access the various ATLAS modules, follow the instructions given below. In all cases, refer to the appropriate sections of the ATLAS Programmer's Reference Guide for an interpretation of the details returned.
Throughout this harness…
To terminate current function press F3.
To clear the screen, press F12
and to exit press F3 then F4.
To utilise the Rapid Addressing facility in Australia, Hopewiser require the postcode and the first three characters of the street name plus the premise number after a /.
For Example
Uk Postcode: WA158DG/187 Australia Postcode: 3000 COL/101
The harness will return a list of all PAF entries that match that input. The structure of the returned information includes sub-premise details first, i.e. Floor, Flat, Lot and Suite, followed by Premise Number, Street, Town, State and Postcode. The / may be omitted for a list of all premises at that postcode. Should the user enter a postcode key that is not on PAF then the message "Postcode not on file" is returned.
A search can also be made for a specific DPID (Delivery Point Identifier), for example enter the following;
Uk Postcode WA158DG@1FJ Australia Postcode: 3000 COL@32773078
By providing an input address to Atlas in free format, Atlas will analyse and return match information for that input.
As an example enter: 187 hale road altringham ches
You should get output like this… note the spelling correction of AltrinGham to AltrinCham and CHES to CHESHIRE. This occurs for common mis-spellings only.
ATLAS Hopewiser Ltd 2002 Address Postcode/ Postcode Index/ Gazetteer
PostcodeId:
Address: 187 hale road altringham ches Gaz prem-id
Gaz thoro-id
Gaz district
Gaz town
Gaz county
Postcode : WA15 8DG1FJ Para: 01
DBK-Key : WA158DG1FJ 0187HAL
Dedup-Key: 00200033HLRD 0187
Name1 :
Name2 : HOPEWISER LTD
Housename:
Premises : 187
Street : HALE ROAD
Qualifier:
District : HALE
Town : ALTRINCHAM
County(Y): CHESHIRE
Any reason for failure of a full match is provided by the Postcode Status, identifying the level at which the match failed, i.e. Premise, street etc. (Refer to the ATLAS Programmer Reference Manual for a full description of each status code).
By providing partial address information you can search the database for the required address
Listing Premises
Address: * Gaz prem-id
COLLIN* Gaz thoro-id
Gaz district
MELBOURNE Gaz town
Gaz county
return a list of all premises/sub-premises on all thoroughfares starting with the characters 'COLLIN' in Melbourne.
Listing Streets
Address: Gaz prem-id
MCI* Gaz thoro-id
Gaz district
BENDIGO Gaz town
Gaz county
return a list of all thoroughfares beginning with the characters MCI in BENDIGO,
Listing Districts
Address: Gaz prem-id
Gaz thoro-id
* Gaz district
MELBOURNE Gaz town
VIC Gaz county
return a list of all districts in Melbourne, Victoria
Listing Towns
Address: Gaz prem-id
Gaz thoro-id
Gaz district
M* Gaz town
VIC Gaz county
In the example the harness will return a list of all the towns in the state of Victoria beginning with the character M
Listing States/Counties
Address: Gaz prem-id
Gaz thoro-id
Gaz district
Gaz town
* Gaz county
return a list of all states/counties
Note: The District, Town and State gazetteers can be combined to say search for * Wildcard districts in *wildcard towns in a * wildcard state.