C H A P T E R 16 - Accessing VSAM Files From External Programs

C H A P T E R 16

Accessing VSAM Files From External Programs

This chapter describes how Sun MTP supports the C-ISAM interface and how to execute C programs that are not defined as region resources. The topics include:

C-ISAM Interface

Accessing VSAM Files Using C Programs

C-ISAM Interface

C-ISAM is an interface that enables C language batch and online programs to access a region's VSAM files. This section contains:

A list of all the supported C-ISAM functions

Things to consider when using the C-ISAM interface in online and batch environments

Information about how Sun MTP handles recovery and rollback

Functions whose implementation differs from the C-ISAM standard

Error codes and error code handling

Note - Refer to the C-ISAM Programmer's Manual for information about using the
C-ISAM interface.

Supported Functions

The C-ISAM functions support both fixed- and variable-length records.

TABLE 16-1 Supported C-ISAM Functions
Function	KSDS	RRDS	ESDS
`isopen(filename, ISINPUT);`	OK	OK	OK
`isopen(filename, ISOUTPUT);`	OK	OK	OK
`isopen(filename, ISINOUT [+ISAUTOLOCK\|+ISMANULOCK]);`	OK	OK	OK
`filename` must be the dataset name that is known to Sun MTP; up to eight characters. Sun MTP handles the mapping of this dataset name to the full path and file name.
`isclose(isfd);`	OK	OK	OK
`isstart(isfd,keydesc,length,rec,ISEQUAL);`	OK	OK	E102
`isstart(isfd,keydesc,length,rec,ISGREAT);`	OK	OK	E102
`isstart(isfd,keydesc,length,rec,ISGTEQ);`	OK	OK	E102
`isstart(isfd,keydesc,length,rec,ISFIRST);`	OK	OK	E102
`keydesc` is a required argument, but it is ignored by Sun MTP for VSAM files. This is automatically handled by Sun MTP.
`isread(isfd, record, ISNEXT [+ISLOCK]);`	OK	OK	OK
`isread(isfd, record, ISPREVIOUS [+ISLOCK]);`	OK	NOT OK	E102
`isread(isfd, record, ISEQUAL [+ISLOCK]);`	OK	OK	E102
`isread(isfd, record, ISGTE [+ISLOCK]);`	OK	OK	E102
`isread(isfd, record, ISGREAT [+ISLOCK]);`	OK	OK	E102
`isread(isfd, record, ISFIRST [+ISLOCK]);`	OK	OK	E102
`iswrite(isfd, record);`	OK	OK See Note	OK
`isrewrite(isfd, record);` **Using `KEY`	OK	OK	E102
`isrewcurr(isfd, record);`	OK	OK	OK
`isdelete(isfd, record);` **Using `KEY`	OK	OK	E102
`isdelcurr(isfd);`	OK	OK	E102
i`srelease(isfd)`	OK	OK	OK
`isindexinfo(isfd, buffer, idx_number);`	OK	OK	OK
Limitation - Only one index is allowed per dataset name. To support alternate indexes, provide a different dataset name for each index, even though it is accessing the same file. The file is opened using the dataset name that represents the desired index and then the `isindexinfo` command is issued using that `isfd`.
`isindexinfo(isfd, buffer, 0);`	OK	OK	OK
Limitation - Reports the number of keys (only 0 or 1 allowed for VSAM) and the maximum record size for the dataset. Zero is returned in the `indexsize` field, and the number of files and spanned files, from 1-8, is returned in the `nrecords` field, because Sun MTP does not directly support the index node concept, nor does it have ready access to the number of records.

Note - (For RRDS files only) The C-ISAM interface does not specify that the global variable isrecnum be set in the program before writing the record to indicate the record number to use for new record. VSAM requires this value, or it requires that the file be positioned immediately in front of the empty record.

C-ISAM interface users are required to set the isrecnum global variable to the desired record number or position it to the proper place in the file and set isrecnum to zero.

Batch and Online Considerations

The Sun MTP C-ISAM interface is implemented to operate in one of two environments:

Online: Third-party software that executes through a parent process.

Batch: Any batch program that executes using Sun MBM or the Sun MTP standard batch facility. See Chapter 15.

For most functions, the user does not need to be aware in which environment the program is running. However, to properly use isbegin, iscommit, and isrollback, you must consider these factors:

Online

The query or query/update is considered as outside the scope of a transaction.

Since the files remain open during the query/update, iscommit and isrollback are allowed. When the last file is closed, an implicit COMMIT is executed by the C-ISAM interface and the changes are made permanent. Rollbacks are not permitted after the last file of a query is closed. If the functions isrollback or iscommit are used after the last file is closed, an error condition results.

The function isbegin is allowed, but it has no effect on the files, and a normal successful return is indicated.

Batch

Programs, queries or query/updates that run in the batch environment, are considered as running under the scope of a transaction. The interface executes an implicit isbegin.

The user does not have to execute an isbegin, but the execution of an isbegin is allowed.

The execution of iscommit and isrollback is allowed, even after all the files are closed. An implicit COMMIT is issued by Sun MTP once the batch job terminates, even if an iscommit was executed by the user.

Note - A single batch job might execute multiple steps (programs) before the implicit COMMIT takes effect.

Recovery and C-ISAM

When using C-ISAM, Sun MTP handles recovery and rollback. Therefore, it is not necessary to create or use C-ISAM log files. The C-ISAM interface provides functions for third-party software that includes calls to islogopen and islogclose. These functions return with a successful indicator when the function is called.

Sun MTP does not support roll forward recovery using after images.

Functions Different From the C-ISAM Standard

The C-ISAM interface adheres to all Sun MTP requirements. It requires a region to be executing. Because data files are defined and created within the region, functions such as iserase and isbuild are not valid.

The isbuild function is implemented as follows:

int isbuild(filename, reclen, buffer, keydesc, mode)

It calls isopen passing the filename and mode arguments that were passed to it. The other three arguments are ignored. This call is treated like the normal isopen function. filename must already exist and be defined in the region.

The following functions are implemented and return a status of SUCCESSFUL even though they do nothing but return:

`iserase`	`islogopen`
`isbegin`	`islogclose`
`islock`	`isunlock`

Functions Unique to Sun MTP

Sun MTP supports two functions that are not part of the C-ISAM standard.

int isgetpath(char *buffer, int size, char*dataset)

Receives a dataset name and returns the full path name including the file name for that dataset to the specified buffer. The buffer size must be specified with the size argument. A value of -1 is returned if an error occurs. The global variable iserrno contains the specific error code. If the dataset is not part of the Sun MTP region, iserrno contains the value 111 (ENOREC). If the buffer is not big enough to handle the full path name, a value of 98 (MAXFILESEXC) is returned in iserrno.

int isconn()

Used only by third-party software that needs to connect to the Sun MTP region's shared memory before the normal open/close functions are invoked. It is only available to batch jobs.

If an online job tries to execute this function, a -1 is returned, and iserrno contains the value 95 (BTCHONLY95).

This function can be called by a process only once. Any additional calls return a value of -1, and iserrno contains the value 1.

Error Codes

C-ISAM functions only return an integer code. A return code greater than or equal to zero indicates that the function executed successfully. If the return code is negative, the function failed. To determine the reason for failure, examine the global error variable, iserrno.

Four types of errors are returned:

1. Error code ENOENT if file does not exist

2. Sun MTP system errors, Codes 90 through 99

TABLE 16-2 C-ISAM/Sun MTP Interface Errors
Sun MTP System Error	Code	Description
`#define SNDMSG90`	90	System error sending message to release TP server
`#define RCVMSG91`	91	System error receiving `ACK` message from Sun MTP
`#define STRTCISAM`	92	C-ISAM must run under Sun MTP control for a VSAM file
`#define SNDMSG93`	93	System error on initial message, Sun MTP not active
`#define RCVMSG94`	94	System error receiving `XUANUM` message from Sun MTP
`#define BTCHONLY95`	95	Function is only available to batch processes
`#define VERSIONERR`	96	C-ISAM and Sun MTP versions do not agree
`#define FCBERR`	97	System error, FCB in error on call to `valfcb`
`#define MAXFILESEXC`	98	Maximum number of files exceeded
`#define INVALIDIX`	99	Invalid index number on a call to `isindexinfo`

3. VSAM error codes that map directly to C-ISAM error codes as defined in the
C-ISAM Programmer's Manual; from 100 through 171. The control errors, such as EOF and No record found matching Key, are mapped to C-ISAM error codes.

TABLE 16-3 VSAM Errors
VSAM Error	Code	Description
`#define EDUPL`	100	Duplicate record
`#define ENOTOPEN`	101	File not open
`#define EBADARG`	102	Invalid Argument - Not supported by this Rec Type
`#define EENDFILE`	110	End of file reached
`#define ENOREC`	111	No record found
`#define ENOCURR`	112	No current record
`#define JOBSEXCEED`	129	Number of interactive C-ISAM jobs exceeded

4. VSAM error codes that do not map to C-ISAM errors are returned as the integer equivalent of the VSAM error codes defined as Micro Focus File Status Codes.

Example: A code returned in iserrno is error code 2. This error code is returned on a read next of a dataset that is an Alternate Key Dataset, and for which there exists at least one other record with the same duplicate key.

The record is correctly returned, but the status of -1 is returned and iserrno contains a 2 as a warning to the user that records with duplicate keys exist in this Alternate Key Dataset.

This follows the same logic that occurs when a user reaches the end of file on a read next.

Note - The COBOL variables isstat1, isstat2, isstat3, and isstat4 are not set because they are only used by COBOL programs.

Accessing VSAM Files Using C Programs

This section describes how to access VSAM files using C programs that do not use the CICS API. These C programs are not defined as resources within a region.

Sun MTP supports the execution of C language programs that access VSAM files with the C-ISAM interface. Before executing these C programs, you must compile them. You can only execute the programs on a system running the same version of Sun MTP as the system where the programs were compiled.

See Supported Functions.

Compiling the C Language Program

1. Set the UNIKIX environment variable to the Sun MTP version where this program will execute.

2. Include the isam.h header file in your C program.

This file is located in the $UNIKIX/src/CICS_structures directory.

3. Execute the following command, either on the command line or in a script file, to compile the program and create the executable.

$ cc input-filename.c -o output-filename $UNIKIX/lib/libbcisam.a

4. Make sure that there are execute permissions on the file.

To Execute the C Program

1. Verify that the Maximum query jobs field in the region's VCT contains a value of 1 or greater.

This value specifies the number of programs that can execute at the same time.

2. At the command prompt, set the KIXCISAM environment variable to the full path name and file name of the C language executable.

For example:

$ export KIXCISAM=/finance/src/cprogs/myprog

3. Start and connect to the region whose VSAM files the program will access.

4. At the command prompt, execute the kixcisam utility.

$ kixcisam

This utility runs the program defined by the KIXCISAM environment variable and monitors its execution. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for additional information about kixcisam.