XVSAM programming interface

XVSAM can be used to access data by on-line as well as by batch programs, written in COBOL or C language.

COBOL interface

For on-line programs, XCICS takes care to interface XVSAM whenever a file operation is required by user programs.

For COBOL batch programs, the XVSAM access interface has been embedded into a proprietary COBOL External File Handler (EFH), which provides the connection with the XVSAM interface. Almost no change is required to let your batch COBOL programs run access XVSAM files.

The only required modification involves the COBOL SELECT clause that should be modified in the ASSIGN clause as follows:

In IBM COBOL VS

ASSIGN TO SYSnnn-DA-disktype-S-name

it becomes in MicroFocus COBOL:

ASSIGN TO EXTERNAL name

The linkage between the name supplied in the SELECT clause and the XVSAM data set takes places at the moment of the program’s run by means of the setenv (C-shell) command or export (Korn-shell) command, which correspond to the VSE DLBL or MVS DD statements:

I.e.

IBM VSE

DLBL NAME  filename,VSAM,CAT=catalog

IBM z/OS

NAME  DD DSN=filename,CAT=catalog

Becomes in UNIX csh:

setenv vsam_NAME "filename,cat=catalog"

or

setenv dlbl_NAME "filename,cat=catalog,type=vsam"

C language interface

XVSAM can be accessed from any program written in C language by using the xvsamapi function: source code must include xvsamapi.h and use xvsamapi() entry point.

The object code has to be linked, dynamically or statically, with the XVSAM libraries, libxvsam6.a or libxvsam6.so.

xvsamapi function

The xvsamapi function has the following prototype:

int xvsamapi ( char ident [11],
   int cop,
   int isfd,
   char catalog [45],
   char cluster [45],
   int mode,
   int lock,
   int nkey,
   int *length,
   long *rrn,
   unsigned char *iobuf );

where:

ident is a null-terminated character identification string. Actually user programs should use the string “VSUS210” for right identification.

cop is an operation code. The set of all supported operation codes is defined in xvsamapi.h include file (see appendix A).

isfd is a Xvsam6 file handler. The xvsamapi returns a handler for all open file operations and wait for it for all other operations on files. NULL can be passed for non open file operations because Xvsam6 uses isfd parameter for the file identification.

catalog is the name of the XVSAM Catalog, where are stored all user data files.

cluster is the name of the file on which an open file operation should be performed.

mode is the C-ISAM mode for open, read and start. Xvsam6 adds two new modes for read: XVSAMLESS for “read less then” and XVSAMLTEQ for “read less or equal”.

lock is the C-ISAM lock parameter for open or read.

nkey is the key number for read.

length is a pointer on integer containing the record length.

rrn is a pointer on long containing the relative record number (for RRDS files)

iobuf is a pointer on the data record.

The “xvsamapi” function returns the isfd file handler on open file operation and the undefined value on all other operations.

The “xvsamapi” function sets the value of the iserrno variable to 0, to one of the C-ISAM errors or to one of Xvsam6 errors which are defined in xvsamapi.h include file.

The “xvsamapi” function prepares the string to pass to the next xvsamIO layer. This string has a machine-independent format so it can be send and received via socket by any other server. It gives the possibility to split application and data on two different physical devices, for increasing data security.

Linking libraries

It is possible to link any of the normal (libxvsam6.a) or shared (libxvsam6.so) versions of Xvsam6 library to user programs. The Xvsam6 utilities use the shared version, so the LD_LIBRARY_PATH environment variable should point also to the directory containing the libxvsam6.so library.