VSAM-CICS Connector Guide
The VSAM CICS Adapter
The VSAM connector can access and communicate with VSAM CICS thanks to the mediation of the VSAM CICS adapter installed on the Mainframe station. The adapter is a specially written COBOL program that reads and parses the format of the VSAM file.
In runtime, the adapter receives a data request, searches for records that satisfy it in the VSAM file, and returns them to the data-consuming service. Because a single VSAM file contains multiple record types (e.g., account, customer, loan), the records returned are parsed according to their type by different assets.
The CICS VSAM connector enables you to create VSAM modules configured to work with a specified VSAM file in design time. Because a single VSAM file can contain multiple record types, add a unique asset for each record type.
For each asset that you add, specify the record type in the --indicator-value property.
Prerequisites
- The CICS COBOL adapter: For installation instructions, click here.
- The VSAM CICS adapter: For installation instructions, click here.
Create VSAM CICS assets
1. Create VSAM CICS module
First, create the VSAM CICS module.
[module-name]> ol create module vsam --connector vsam-cics
[module-name]$ ol create module vsam --connector vsam-cics
The prepackaged vsam-records asset is generated under the assets directory in your module folder. You will need to use it later.
2. Test the connection to the VSAM-CICS remote data source
Run ol test connection to establish and verify the connection to VSAM-CICS. For information on the connection properties used in the command refer to the Properties section below.
[module-name]> ol test connection --base-url http://192.86.32.238 --uri-map /dev/latest --record-offset 8 --record-length 4 --file-name aavsam3 --hdrFlag01 1
[module-name]$ ol test connection --base-url http://192.86.32.238 --uri-map /dev/latest --record-offset 8 --record-length 4 --file-name aavsam3 --hdrFlag01 1
3. Add an entity-type asset to the module
Because a single VSAM file contains multiple record types, add a unique entity-type asset for each record type.
For each asset you add, specify the record type and the local copybook file that describes the record type data structure.
The vsam-user copybook file (CPY):
01 id PIC X(6).
01 VSAMREC.
03 VSAMKEY PIC X(6).
03 EMPTY PIC X(2).
03 VSAM-REC-TYPE PIC X(4).
03 VSAM-PAYLOAD-U.
05 EMPTY PIC X(1).
05 VSAMFAM1 PIC X(15).
05 VSAMNAM1 PIC X(10).
05 VSAMADR1 PIC X(24).
05 VSAMSTA1 PIC X(15).
05 VSAMCOD1 PIC X(3).
05 VSAMPST1 PIC X(5).
Add the entity-type asset to the module. Use vsam-user as the source-path and set the record-indicator-key.
[module-name]> ol add --source-path ./vsam-user.cpy --indicator-value E4A28599
[module-name]$ ol add --source-path ./vsam-user.cpy --indicator-value E4A28599
4. Test the asset
Before the asset you added in the previous step can be tested, you need to have records from the VSAM file at your disposal. This task is performed by the prepackaged vsam-records asset that contains input fields with instructions to the VSAM adapter.
- Open assets/sort2-operation/test_data/case-1/in.json:
{
"cicsFileName" : "AAVSAM3",
"recordsToRead" : 3,
"opCode" : "RM",
"msgLvl" : "",
"remoteFlag" : " ",
"ffu1" : "",
"key" : "",
"recordLength" : 0,
"keyOffset" : 0,
"keyLength" : 0,
"maxRecordLength" : 0,
"fileType" : "",
"rbaType" : "",
"ffu2" : "",
"extra" : ""
}
-
Set the cicsFileName key to the vsam file name.
-
Set the other keys in the file.
keyOffset and keyLength defaults to the --record-offset and --record-length property values unless you set them here to a value other than zero.
- Run ol test asset for the vsam-records asset:
[module-name]> ol test asset vsam-records[module-name]$ ol test asset vsam-records
The following output is displayed:
{
"responseCode" : 0,
"responseCode2" : 0,
"returnCode" : 0,
"recordsReturned" : 3,
"returnMessage" : "MANY READS OK",
"outputKeyOffset" : 1,
"outputKeyLength" : 6,
"outputRecordLength" : 150,
"outputFfu1" : "",
"readRecords" : 4,
"outputFileType" : "KSDS",
"outputRbaType" : "",
"forwardKey" : "8PDw8PTwQEBAQEBAQEBAQEBAQEBAQEBAQEBA...",
"ffu3" : "",
"records" : [ {
"vsamrec" : {
"vsamkey" : "000010",
"vsamRecType" : "User",
"vsamPayloadU" : {
"vsamfam1" : "Alebert",
"vsamnam1" : "John",
"vsamadr1" : "134 St Park Street",
"vsamsta1" : "California",
"vsamcod1" : "CA",
"vsampst1" : "96154",
"@_clazz_name_@" : "VsamPayloadU"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamrec.Vsamrec"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamuser.VsamUser"
}, {
"vsamrec" : {
"vsamkey" : "000020",
"vsamRecType" : "User",
"vsamPayloadU" : {
"vsamfam1" : "Bradford",
"vsamnam1" : "Billie",
"vsamadr1" : "222 Baker Boulevard",
"vsamsta1" : "Baltimore",
"vsamcod1" : "MD",
"vsampst1" : "35702",
"@_clazz_name_@" : "VsamPayloadU"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamrec.Vsamrec"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamuser.VsamUser"
}, {
"vsamrec" : {
"vsamkey" : "000030",
"vsamRecType" : "User",
"vsamPayloadU" : {
"vsamfam1" : "Carson",
"vsamnam1" : "Cameron",
"vsamadr1" : "333 Crenshaw Blvd.",
"vsamsta1" : "Cupertino",
"vsamcod1" : "CA",
"vsampst1" : "96154",
"@_clazz_name_@" : "VsamPayloadU"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamrec.Vsamrec"
},
"@_clazz_name_@" : "com.openlegacy.entity.vsamuser.VsamUser"
} ]
}
Properties
--source-path (required)
The path to a local data-source copybook (CPY) file. The path is used by the CLI ol add command to access the file and parse it to extract its metadata.
--source-path ./user-info-new.cpy
--indicator-value
The indicator value identifies the record type of each record in the file. A VSAM file can contain multiple record types (e.g., account, customer, credit card).
--indicator-value E4A28599
--record-offset
The starting position of the record indicator value in the record
--record-offset 8
--record-length
The number of characters reserved in the record for the record indicator
--record-length 4
--file-name
The name of the VSAM file on the CICS-COBOL machine containing the VSAM records
--file-name aavsam3
--hdr-flag01
[HDR_FLAG01_COMMAREA, HDR_FLAG01_CONTAINER] (default: HDR_FLAG01_CONTAINER)
--hdr-flag01 HDR_FLAG01_CONTAINER
--base-url (required)
The vsam-cics host address
--base-url 192.86.32.238
--uri-map (required)
The Mainframe CICS adapter URI map
--uri-map prod/latest
--code-page
The output file code page (default: CP037)
--code-page 037
--port
The data source port (default: 12345)
--port 13200
--user
The vsam-cics username
--user demo
--password
The vsam-cics password
--password 12345
--timeout
Maximum period of time (in milliseconds) calling the CICS program (default: -1)
--timeout 5000
--idle-timeout
Maximum period of time (in milliseconds) for pool connection before it is closed (default: 0)
--idle-timeout 8000
Updated 4 months ago