Using ITPUIOX to handle customer specific file I/O

Answer

ITPUIOX File I/O User Exit

ITPUIOX is a WSIM message generation exit (EXIT MODULE=ITPUIOX) providing users with the ability to write their own file handling routine that can interface with WSIM.

This exit is written in assembler and has been coded to allow a user to pass information to and from WSIM via data save areas. It is highly recommended that the pre-written code in this exit not be modified as it will affect the ability for information to be transferred between WSIM and the exit. Where code can be changed or added is indicated by comment fields and it is strictly up to the user as to what is coded in these sections.

ITPUIOX Syntax and Use

The syntax for ITPUIOX is as follows:

EXIT MODULE=ITPUIOX, PARM=(file_request rc_counter [data_sa#])

Where:

file_request is one of the following:

OPEN Open the data set
READ Read a record
WRITE Write a record
CLOSE Close the data set

rc_counter, the return code counter name, is one of the following:

DC1-4095
NC1-4095

The counter should contain the return code after each file request completes. The following codes are currently set in ITPUIOX but can be changed and additional return codes can be added:

0 OK

5 This exit is not set up to handle the required file request

6 Data save area id outside range of 1 – 255

7 One of the required parameters is missing


These codes are generated by the Exit interface routine and are passed through to the WSIM script that called ITPUIOX:

0 OK

4 Invalid request code

8 Invalid control block passed (Word 1) for request type.

12 Incorrect data length specified.

16 Insufficient storage available for request.

20 Unable to supply requested information for one of the following reasons:

• The referenced static save area is not allocated, the referenced dynamic save area is empty (not allocated), or the requested save area cannot be found.
• The referenced NTWRK or DEV user area does not exist.
• The referenced LINE counters do not exist.
• The referenced LINE name does not exist.
• The referenced LINE value does not exist.
• The referenced TERM does not exist.
• The referenced AID byte does not exist for a non-display terminal.
• The referenced session number does not exist.
• The referenced attribute table does not exist.
• You referenced a LU7 Format Table and this is not a LU7.
• The referenced LU2 PTN does not exist.

24 Save area number zero was specified for an allocate, free, or increase network or device save area request.

28 The specified network or device save area could not be found for a free or increase request.

32 The device save area was allocated statically using the SAVEAREA operand in the WSIM network definition and cannot be allocated, freed, or increased.

36 The save area size value specified for a network or device save area allocate or increase request is invalid. The value must be within the range of 1-32767.

40 No save area storage was available for a network or device save area allocate or increase request.


data_sa#, the data save area name, is one of the following:

1-255
For OPEN this save area contains the MVS data set name or DDNAME = ddname keyword.
For WRITE, this save area contains the record data to be written.
For READ, this save area will contain the record read from the data set.
For CLOSE, this save area is not required.

The following are examples of the ITPUIOX syntax:

MSGTXT Language Example

DATASAVE AREA=254,TEXT=(MYMVS.FILE)
EXIT MODULE=ITPUIOX,PARM=(OPEN DC55 254)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR

DATASAVE AREA=254,TEXT=(RECORD 1 DATA)
EXIT MODULE=ITPUIOX,PARM=(WRITE DC55 254)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR

EXIT MODULE=ITPUIOX,PARM=(CLOSE DC55)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR


DATASAVE AREA=254,TEXT=(MYMVS.FILE)
EXIT MODULE=ITPUIOX,PARM=(OPEN DC55 254)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR

EXIT MODULE=ITPUIOX,PARM=(READ DC55 254)
WTO (FIRST RECORD READ = $RECALL,254$)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR

EXIT MODULE=ITPUIOX,PARM=(CLOSE DC55)
IF WHEN=IMMED,LOC=DC55,COND=NE,TEXT=0,THEN=B-ERROR


STL Language Example

constant data_sa# '254'
constant rc_counter# 'DC55'

allocate file_data data_sa#
allocate file_rc rc_counter#

file_data = 'MYMVS.FILE'
file_rc = 999
userexit('ITPUIOX', 'OPEN' rc_counter# data_sa#)
if file_rc <> 0 then call error

file_data = 'Record 1'
userexit('ITPUIOX', 'WRITE' rc_counter# data_sa#)
if file_rc <> 0 then call error

userexit('ITPUIOX', 'CLOSE' rc_counter#)
if file_rc <> 0 then call error

file_data = 'MYMVS.FILE'
userexit('ITPUIOX','OPEN' rc_counter# data_sa#)
if file_rc <> 0 then call error

userexit('ITPUIOX','READ' rc_counter# data_sa#)
say 'Record 1 =' file_data
if file_rc <> 0 then call error

userexit('ITPUIOX','CLOSE' rc_counter# )
if file_rc <> 0 then call error

Additional information

Adding to or modifying the file request field

The file request field can be resized and additional information passed via this field. e.g. OPEN could become OPENI for Open dataset for input only, OPENO for opening a dataset for output only or OPENDB for getting access to a database. To do this you may need to increase the size of the SAREQST field to more than 5 characters and then add additional comparisons for the SAREQST field.

Additional file requests can also be set up but these are at the user's discretion e.g. DELREC to delete a record from a dataset or database. To carry out this sort of change a user may need to resize the SAREQST field which currently only allows 5 characters for the file request parameter, add additional tests for the new file request and then write code to handle the new file request.

Compile and link edit of ITPUIOX

This exit uses standard compile and link JCL with the following SYSIN cards for the link step

MODE RMODE(24),AMODE(31)
ENTRY ITPUIOX
NAME ITPUIOX(R)

Other options and information

Besides the ability to access and update save areas the Exit Interface Routine gives you access to other information and functionality within WSIM. The additional information that is available could be included in the data output to a file or to control further what information is either read from or written to an external file. If you want to understand how to use the Exit Interface Routine or access additional functionality through that interface you will need to read section 1.18 of the WSIM V1R1 User Exit manual.

An example of using ITPUIOX with a KSDS VSAM file.

The attached document "ITPFIOX.SRC" contains an example of how to modify the exit to access a Key Sequenced VSAM file. This code is a model only as it contains the bare minimum for error checking and only handles a dataset that is pre-allocated. It also does not deal with duplicate keys or other potential issues that can occur with VSAM file handling.

To test this code the following example STL script was used. The first set of statements opens the VSAM file for input and then does a keyed read for two records and closes the file. The next set opens the VSAM file for output and writes out a new record and closes it. The last set opens the VSAM file for input, sets the key to the one just written out and reads the record and then closes the file.

constant rc_counter# 'DC55'
constant data_sa# '254'
allocate file_data data_sa#
allocate file_rc rc_counter#

file_data = 'DDNAME=TEMPFIOX'
file_rc = 999
say 'USER OPEN performed'
userexit('ITPUIOX', 'OPENI' rc_counter# data_sa#)
if file_rc <> 0 then call error

file_data = 'RECOR2'
file_rc = 999
say 'USER READ performed'
userexit('ITPUIOX', 'READ' rc_counter# data_sa#)
say 'Record 1 =' file_data
if file_rc <> 0 then call error

file_data = 'RECOR3'
file_rc = 999
say 'USER READ performed'
userexit('ITPUIOX', 'READ' rc_counter# data_sa#)
say 'Record 1 =' file_data
if file_rc <> 0 then call error

file_rc = 999
say 'USER CLOSE performed'
userexit('ITPUIOX', 'CLOSE' rc_counter#)
if file_rc <> 0 then call error

file_data = 'DDNAME=TEMPFIOX'
file_rc = 999
say 'USER OPEN performed'
userexit('ITPUIOX', 'OPENO' rc_counter# data_sa#)
if file_rc <> 0 then call error

file_data = 'RECOR6, This is a new record'
file_rc = 999
say 'USER WRITE performed'
userexit('ITPUIOX', 'WRITE' rc_counter# data_sa#)
say 'Record 1 =' file_data
if file_rc <> 0 then call error

file_rc = 999
say 'USER CLOSE performed'
userexit('ITPUIOX', 'CLOSE' rc_counter#)
if file_rc <> 0 then call error

file_data = 'DDNAME=TEMPFIOX'
file_rc = 999
say 'USER OPEN performed'
userexit('ITPUIOX', 'OPENI' rc_counter# data_sa#)
if file_rc <> 0 then call error

file_data = 'RECOR6'
file_rc = 999
say 'USER READ performed'
userexit('ITPUIOX', 'READ' rc_counter# data_sa#)
say 'Record 1 =' file_data
if file_rc <> 0 then call error

file_rc = 999
say 'USER CLOSE performed'
userexit('ITPUIOX', 'CLOSE' rc_counter#)
if file_rc <> 0 then call error