Post Installation Activities

Restrictions

Chapter 5: Server Functionality

Mainframe Access Product Suite servers provide record-by-record read-write access to data on an MVS mainframe from applications running on network attached workstations. These client applications are standard COBOL applications using COBOL I/O statements.

Mainframe Access Product Suite operates in two separate environments on the mainframe, either as a MVS application or as a CICS transaction. The CICS server provides record-by-record access to VSAM datasets that can be shared with other CICS transactions. The MVS server provides record-by-record access to VSAM and sequential datasets as well as members of partitioned datasets (PDS). The MVS server also provides Library Services Connectivity (LSC) support for access of source code and test data files.

This chapter gives details of the record-by-record access support in each environment. The Library Services Connectivity chapter gives details of what is supported by that function.

5.1 Dataset Allocation

Dataset allocation is the mechanism whereby file references in client applications are associated with MVS datasets. Allocation does not imply creation of datasets. In most cases datasets will be created before they are accessed by MFA. This is always the case for the CICS environment. In the VTAM environment, it is possible to dynamically invoke VSAM Access Method Services to create either a VSAM or non-VSAM file just before it is opened.

5.1.1 Allocating Datasets in the CICS Environment

VSAM datasets used by MFA in the CICS environment can be pre-allocated by including MVS JCL "DD" statements in the CICS start-up jobstream, or allocated dynamically by including a DSNAME in the CICS resource definition of the file. Datasets that are to be accessed in the CICS environment must be defined to CICS as file resources. An entry is also required in the CICS Server Database Reference File for each filename that either does not conform to CICS filename conventions or for which a dynamic association of workstation filename to CICS filename is desired.

VSAM datasets must exist prior to being accessed through the CICS server. No provision exists in the CICS environment for dynamically creating datasets.

Connecting from a workstation-based COBOL application to a host-based dataset through the CICS server can involve multiple filename mappings. Table 1 indicates the required and optional mappings that take place on the workstation and Table 2 indicates the mappings that occur on the CICS host. You must ensure that the required definitions are in place before attempting to access VSAM datasets through the CICS server.

Table 1: Filename Mapping Occurring on the Workstation

Note: Logical filename and physical filename are the terms used by the External File Mapper. For workstation-only applications, these correspond, roughly, to DDNAME and workstation (PC) filename. When used with the CICS server, this is merely a translation that can be further modified on the server (or host).

Table 2: Filename Mappings Occurring on the Host (CICS)

Note: An entry in the Database Reference File is required if the filename passed from the workstation does not conform to CICS file naming conventions.

Example

The following extracts from a COBOL application, MFEXTMAP.DAT file, Database Reference File and CICS start-up JCL provide an example of dataset allocation in the CICS environment.

In the COBOL application:

SELECT TRANSACTION-FILE ASSIGN ACCTFIL INDEXED
.
.
OPEN I/O TRANSACTION-FILE

in the MFEXTMAP.DAT file:

ACCTFIL  G:\TX\SAMPREGN\FILES\USR\ACCTFIL

in the Database Reference File:

/F G:\TX\SAMPREGN\FILES\USR\ACCTFIL /AF MFAACCT

and in the CICS start-up JCL:

//MFAACCT DD DSN=ACCOUNT.MASTER.FILE,DISP=SHR

5.1.2 Allocating Datasets in the MVS Environment

In the MVS environment datasets can either be pre-allocated via MVS JCL "DD" statements (Job Step allocation) or dynamically allocated by the MVS server. In general, datasets must already exist on the mainframe before they can be accessed via the MVS server from a workstation; however, the MVS server makes special provision for creating both VSAM and non-VSAM datasets by invoking VSAM Access Method Services before the dataset is accessed.

Connecting from a workstation-based COBOL application to a host-based VSAM dataset through the MVS server can involve multiple filename mappings. Table 1 indicates the required and optional mappings that take place on the workstation. These mappings apply to both the CICS and MVS environments because the activities involved take place on the workstation prior to communication with the host system. Table 3 indicates the mappings that occur on a MVS host. You must ensure that the required definitions are in place before attempting to access datasets through the MVS server.

5.1.2.1 Table 3: Filename Mapping Occurring on Host (MVS)

Notes:

1. An entry in the FSTAB is required if the filename passed from the workstation does not conform to either MVS DDNAME or DSNAME naming conventions.
2. DD statements must be included in the start-up jobstream if the filename passed from the workstation, after any FSTAB translation, does not resolve to an MVS DSNAME.

Pre-allocated datasets require that dataset definition (DD) statements be included in the MVS server start-up jobstream. Access to pre-allocated datasets is requested whenever the Client passes a DDNAME to the MVS server or when the server translates the workstation filename to a DDNAME using FSTAB. For details of FSTAB, see Configuring MFA in the Installation chapter.

Dynamic dataset allocation occurs whenever a host dataset name (DSNAME) is passed to the MVS server from the workstation or when server translates the workstation filename to a dataset name (DSNAME) using FSTAB. For details of FSTAB, see Configuring MFA in the Installation chapter.

The MVS server uses the following criteria to determine if the filename passed to it should be interpreted as a DDNAME or as a DSNAME.

1. If the name passed from the workstation (or the value resulting from FSTAB translation) is from 1-8 characters with no embedded period(s), then the value is interpreted as a DDNAME, unless it starts with a $, where it is used as the member name in the VCTL dataset.
2. If the name passed from the workstation (or the value resulting from FSTAB translation) is from 3-44 characters with at least one embedded period, then the value is assumed to be a DSNAME.
3. All other cases, and values that meet test 2 (above) but do not conform to MVS dataset naming conventions result in allocation errors.

Example
The following extracts from a COBOL application, MFEXTMAP.DAT file and FSTAB entry provide an example of dataset allocation in the MVS environment.

In the COBOL application:

SELECT TRANSACTION-FILE ASSIGN ACCTFIL INDEXED
RECORD KEY IS ACCT-KEY
.
.
OPEN I/O TRANSACTION-FILE

In MFEXTMAP.DAT:

ACCTFIL G:\TX\SAMPREGN\FILES\USR\ACCTFIL

In FSTAB:

   FSTAB 'G:\TX\SAMPREGN\FILES\USR\ACCTFIL',              X
         DSN=ACCOUNT.MASTER.FILE

The above example dynamically allocates an existing VSAM file. There is no need to specify the dataset in the MVS server start-up JCL.

5.1.3 Partitioned Dataset (PDS) Considerations

Client applications can be connected to MVS Partitioned Dataset (PDS) members by referring to the PDS member name either on the workstation or on the host. On the workstation, a PDS member reference can be specified in the program, in an environment variable or in the MFEXTMAP.DAT file. In each case, the reference takes the form:

MVS.DATASET.NAME(MEMBER)

or:

DDNAME(MEMBER)

Example
An example of a COBOL program reference to a PDS member using a dataset name is shown below.

SELECT anyname ASSIGN 'CSI01.FSHOST.DIST.INSTLIB(VERIFY)'

An example using a DDNAME would be:

SELECT anyname ASSIGN 'VSAMCTL(TSTALLOC)'

A PDS member can be referenced on the host through MVS JCL (pre-allocation) or by allocating it dynamically using FSTAB translation. An example FSTAB entry specifying a PDS member is shown below:

   FSTAB 'workstation-name',           X
         DSN=mvs.dataset.name,         X
         MEM=member

5.1.4 Sequential Dataset Considerations

MVS sequential datasets to be created as output must be pre-allocated unless one of the following situations applies:

1. The sequential file is being created as a member of an existing PDS.
2. Access Method Services is used to create the file (see below).

SYSOUT files can be pre-allocated or you can specify a filename of the form SYSOUTx to dynamically allocate them. You should replace the value x with a single letter or numeric digit specifying the SYSOUT class. The filename can be specified in your source program, an environment variable, the MFEXTMAP.DAT file or be the result of FSTAB translation.

5.1.5 VSAM Alternate Indexes

VSAM alternate indexes can be pre-allocated or allocated dynamically. Pre-allocation is accomplished via MVS JCL; dynamic allocation via FSTAB. If you pre-allocate the base VSAM cluster, you must pre-allocate the alternate indexes. If you specify the base cluster in FSTAB, you must specify the alternate indexes there as well.

The following naming convention must be used when pre-allocating alternate indexes. Alternate index DDNAMEs must take the form ddnamen, where ddname is the DDNAME of the base VSAM cluster and n is a single numeric digit beginning with 1 and incrementing for each additional alternate index. If ddname is 8 characters, the last character must be replaced with the single digit. Numbers must be assigned in the order in which they are defined in the ALTERNATE RECORD KEY clauses in client COBOL programs. The MVS server currently limits the number of pre-allocated alternate indexes that can be specified in this manner to 9.

As an example, if the DDNAME used for the base VSAM cluster is specified as ACCOUNTS, then the first alternate index must be ACCOUNT1, the second ACCOUNT2 and so on.

Dynamic allocation of alternate indexes is accomplished by using the FSTAB macro to associate alternate indexes with a primary (base) cluster. When using FSTAB, the alternate index names specified are the VSAM path names defined in the VSAM catalog. The MVS server does not impose any additional naming conventions for these beyond what VSAM and MVS require. Alternate index references in the FSTAB entry must be in the same order as specified in the ALTERNATE RECORD KEY clauses in the client COBOL programs.

Example
An FSTAB entry with alternate indexes is shown below:

   FSTAB 'ACCT.FIL',                       X
         DSN=ACCOUNT.MASTER.FILE,          X
         AIX=(ACCOUNT.MASTER.BY.REGION,    X
         ACCOUNT.MASTER.BY.SALESMAN,       X
         ACCOUNT.MASTER.BY.CUSTOMER)

The MVS server dynamically allocates the alternate index file as required.

To ensure consistent behavior between COBOL applications running on the workstation and client COBOL applications accessing VSAM datasets through the MVS server, alternate indexes should always be defined to VSAM as being part of the UPGRADE set.

As an alternative to specifying a static set of alternate indecies with a VSAM file in the FSTAB, you may now define this same information in a more dynamic method by using members in the VSAMCTL library to create dynamic FSTAB entries for VSAM files which have alternate indexes. Each member in the VSAMCTL library defines a VSAM file and its indexes. Only one VSAM file can be specified in each member. The control records within a member are 80 bytes long and begin with a keyword followed by its value. All member names for this facility must begin with a '$' or whatever keyboard character maps to a X'5C'.

The keywords are VSAM= and AIXn=, when n is a value from 1 to 9. Following VSAM= is the MVS VSAM dataset name. This record must be the first record in the member. The keywords AIX1 through AIX9 identify the alternate index PATH files. They must be specified in the same order as in the COBOL program.

For example:

FILE-CONTROL.
SELECT CLAIM-FILE
ASSIGN TO PATCLMX
ORGANIZATION IS INDEXED
ACCESS IS RANDOM
RECORD KEY IS PATIENT-CLIAM-NUMBER
ALTERNATE RECORD KEY IS MEDICARE DUPLICATES
ALTERNATE RECORD KEY IS MEDICAID-KEY DUPLICATES
ALTERNATE RECORD KEY IS PRIVATE-INS-KEY DUPLICATES
ALTERNATE RECORD KEY IS PATIENT-NAME
ALTERNATE RECORD KEY IS CONTROL-NUMBER
ALTERNATE RECORD KEY IS PAYMENT-ID
STATUS IS VSAM-FILE-STATUS.

As an FSTAB entry:

FSTAB 'PATCLMX',
      DSN=CSI01V.PATCLM.PATIENT.BILLING,
      AIX=(CSI01V.PATCLM.BY.MEDICARE.PATH,
           CSI01V.PATCLM.BY.MEDICAID.PATH,
           CSI01V.PATCLM.BY.INS.POLICY.PATH,
           CSI01V.PATCLM.BY.NAME.PATH,
           CSI01V.PATCLM.BY.CONTROL.PATH,
           CSI01V.PATCLM.BY.PAYMENT.PATH)

As a VCTL library member:

VSAM=CSI01V.PATCLM.PATIENT.BILLING
AIX1=CSI01V.PATCLM.BY.MEDICARE.PATH
AIX2=CSI01V.PATCLM.BY.MEDICAID.PATH
AIX3=CSI01V.PATCLM.BY.INS.POLICY.PATH
AIX4=CSI01V.PATCLM.BY.NAME.PATH
AIX5=CSI01V.PATCLM.BY.CONTROL.PATH
AIX6=CSI01V.PATCLM.BY.PAYMENT.PATH

Assume that the name of the VCTL member for the above control statements is $PATCLM6, then the MFEXTMAP.DAT entry would be:

PATCLMX ($PATCLM6)

Note, the parentheses are required because FHREDIR uses the $ as a special name indicator.

The above FSTAB and VCTL member are functionally equivalent.

5.1.6 Processing of Datasets

Dataset allocation is the mechanism whereby file references in client applications are associated with MVS datasets. With few exceptions, datasets are expected to exist when opened by client applications. A dataset being opened by a client application need not already exist if one of the following conditions is met:

1. The dataset is pre-allocated in the MVS server start-up jobstream using a disposition of NEW.
2. The filename is specified as SYSOUTx. See Sequential Dataset Considerations.
3. The dataset opened by the client is mapped to a member of an existing PDS. In this case, the member need not already exist. See Partitioned Dataset (PDS) Considerations.
4. The MFA MVS Server invokes VSAM Access Method Services to create the file prior to completing the open. This approach is called preprocessing or dynamic allocation of new datasets and can be applied to sequential and partitioned datasets as well as VSAM files.

To preprocess datasets using Access Method Services or the dynamic allocation MVS Supervisor Call (SVC99), you must establish a PDS with 80 byte records, either blocked or unblocked. The PDS must be specified in a DD statement in the MVS server start-up jobstream and use the DDNAME VSAMCTL. The members of this PDS contain the Access Method Services (IDCAMS) or TSO commands you wish to have invoked to preprocess your datasets. This dataset and its JCL statement is created by the installation procedure.

Your applications can refer to the members of the VSAMCTL PDS by specifying filenames of the form @member for VSAM files and #member for non-VSAM datasets. As before, this form of file reference can be specified in your client application, in an environment variable, in the MFEXTMAP.DAT file or be the result of FSTAB translation. Regardless of the method used to specify the file reference, the MVS server dynamically invokes Access Method Services or SVC99, passing it the contents of the referenced PDS member when the client application performs either a COBOL OPEN or a DELETE FILE for the specified file. A COBOL OPEN performs the specified Access Method Services functions and then opens the file referenced by the Access Method Services commands. DELETE FILE simply causes the Access Method Services functions to be performed without further processing.

You must create the members of the VSAMCTL PDS, placing the desired Access Method Services commands in 80 byte card images. Members can consist of any Access Method Services command, or series of commands that is valid in your environment. This includes the TSO ALLOCATE command which can be used to create non-VSAM datasets.

Example
An example of using Access Method Services to preprocess a dataset is given below.

In your COBOL application:

SELECT TRANSACTION-FILE ASSIGN '@TRANFIL'
.
.
OPEN OUTPUT TRANSACTION-FILE

VSAMCTL PDS member @TRANFIL:

DELETE TRANS.ESDS PURGE CLUSTER
SET MAXCC EQ 0   /* allow dataset to not exist */
DEFINE CLUSTER (NAME(TRANS.ESDS) -
RECORDS(2000, 1000) -
VOLUMES(VSAM01) -
NONINDEXED -
RECORDSIZE(128 128)

This example creates, then opens a VSAM Entry Sequenced Dataset (ESDS) for output processing.

Access Method Services output is written to the FSMSGA message file defined during installation. You should check the FILE STATUS to ensure that 00 has been returned by Access Method Services. You can include a SET MAXCC EQ 0 if required.

Any IDCAMS control statements can be used. Therefore a REPRO statement could be used to load the VSAM file prior to its use. Also alternate indexes and path file can be created in this manner.

Please refer to the IBM document, Access Method Services for the Integrated Catalog Facility (SC26-4906) for details on the IDCAMS control statements.

Example
An example of using SVC99 to preprocess a dataset is given below.

In your COBOL application:

SELECT TRANSACTION-FILE ASSIGN '#MYLIB'
.
.
DELETE TRANSACTION-FILE

VSAMCTL PDS member #MYLIB:

DELETE    DATASET(CSI01.MY.LIBRARY)
ALLOCATE  DATASET(CSI01.MY.LIBRARY)
          CATALOG
          UNIT(9345)
          VOLUME(LIBS01)
          CYLINDERS
          PRI(005)
          SEC(001)
          DIR(075)
          EXPDT(97120)

This example creates a PDS library.

SVC99 output is written to the FSMSGA message file defined during installation. You should check the FILE STATUS to ensure that your commands were properly processed.

The following commands and options are be used by the SVC99 function to process non-VSAM datasets. Required coding for each command or option is shown in uppercase letters. All lowercase letters are optional.

To delete a non-VSAM dataset use the following command. The command and file name must be on the same line. The dataset name (xxxxxxxx) may optionally be enclosed within quotes.

DELete    DAtaset(xxxxxxxx)  or  DSname(xxxxxxxx)

To allocate a non-VSAM dataset code use the following command and options. The command and file name must be on the same line. The dataset name (xxxxxxxx) may optionally be enclosed within quotes.

ALLOCate  DAtaset(xxxxxxxx)  or  DSname(xxxxxxxx)

The following command options are available:

5.2 Line Sequential Files

MVS

Line Sequential files are only supported by the MVS server.

The MVS server provides special file handling for line sequential files. For file types other than line sequential, all data passed between workstations and the server is assumed to use the EBCDIC code set. COBOL applications on the workstation must be coded with the Micro Focus COBOL Compiler directive CHARSET(EBCDIC) in order to properly handle the EBCDIC coded files on the host.

Because they can contain embedded formatting codes that are only meaningful in the ASCII code set, line sequential files on the workstation are always coded in ASCII, regardless of the CHARSET directive. While this arrangement is the most sensible for applications running solely on the workstation, mainframes generally expect data to be stored in EBCDIC. As a consequence, the MVS server provides translation between ASCII and EBCDIC when processing line sequential files, so that these files, while read or written in ASCII by the client application, are stored in EBCDIC on the host. In addition, the MVS server attempts to convert most line sequential formatting to the closest equivalent on the host.

For line sequential output files, records are translated from ASCII to EBCDIC as they are received by the host. COBOL WRITE controls such as BEFORE/ AFTER ADVANCING are translated into carriage control characters before the records are stored on the host.

For line sequential input files, records are translated from EBCDIC to ASCII as they are sent to the client. Carriage control characters are stripped out and the equivalent number of blank lines inserted.

5.3 MF/370 Support

As well as supporting the normal COBOL programs by compiling them with the CALLFH"FHREDIR" Compiler directive, MF/370 assembler programs are supported by issuing the command:

SET MF370EFH=FHREDIR

before the assembly is run.

5.4 Action Codes Supported

The operations that the record-by-record service can perform are defined by action codes. For each COBOL I/O operation, there is an equivalent action code. In addition, the record-by-record service has some special functions which cannot be performed using COBOL syntax.

This section lists the action codes that the record-by-record service supports. It also documents any deviations from normal Fileshare Version 2 processing.

Normal COBOL I/O operations are identified by x'FA' in the first byte of the action code. The second byte indicates the operation, as shown in the following table. The operation codes are in hexadecimal format.

See the Callable File Handler in the Programmer's Guide to File Handling for full details on action codes.

File Types are abbreviated as follows:

Operation codes for line sequential files and byte stream processing are not supported for the CICS server.

Operation codes for lock processing are supported to the extent that the CICS server can simulate the lock behavior under CICS. Multiple locks cannot be obtained (although uncommitted write operations to CICS protected resources do result in the records being locked until a commit or rollback request is processed).

Table 4: Action Codes Supported

5.4.1 Special Action Codes

Special operations are identified by x'00' in the first byte of the action code. The second byte contains the operation code. Refer to your Programmer's Guide to File Handling for a description of these operation codes.

Table 5: Special Action Codes Supported

Table 6: Special Action Codes Not Supported

5.5 File Control Description (FCD) Changes

The File Control Description (FCD) is a 100 byte area that describes a file. The structure of the FCD is explained in your Programmer's Guide to File Handling.

The following changes/additions have been added to support record-by-record functionality of the Mainframe Access Product Suite; all offsets are in decimal.

Table 7: FCD Modifications for MFA

For functionality that the servers do not support, a file status of 9/100 is returned.

5.6 CICS Server Enhancements Over IBM VS COBOL II

Because the CICS server executes under CICS, certain enhancements to native COBOL processing are possible. The most notable of these is the ability to support COMMIT and ROLLBACK processing (transaction processing) for CICS protected resources.

The possible enhancements are:

• COMMIT and ROLLBACK processing.
  
  See Commit and Rollback Processing below for a description of the relationship between the Micro Focus COBOL COMMIT and ROLLBACK verbs and the CICS SYNCPOINT command.
  
  
• Support for CICS servers.
  
  See Support for Multiple Servers below for a description of how the Mainframe Access Product Suite permits multiple servers to be executing within the same CICS region.
  
  
• Opening the Path of a KSDS for Output Processing.
  
  See Opening the Path of a KSDS for Output Processing below for details on how the CICS server differs from IBM VS COBOL II with regard to these requests.

5.6.1 Commit and Rollback Processing

The CICS server supports COMMIT and ROLLBACK action codes and issues the corresponding CICS SYNCPOINT and CICS SYNCPOINT ROLLBACK commands as necessary. On the client side, Fileshare Version 2 transmits the COMMIT and ROLLBACK requests to the CICS server if the requesting program has defined the file using the WITH ROLLBACK clause.

For more information on COMMIT and ROLLBACK, see your Language Reference.

For protected CICS resources (those defined to CICS in the FCT with appropriate journalling and recovery parameters), the COMMIT request commits all outstanding updates and the ROLLBACK request causes the records with outstanding updates to revert to their former state. For unprotected resources, issuing a COMMIT or ROLLBACK request has no effect on the data updated in the file. For both types of resources, all outstanding record locks are automatically released when either COMMIT or ROLLBACK is issued.

5.6.2 Support for Multiple Servers

The CICS Mainframe Access environment permits multiple CICS servers to execute within the same CICS region (see Figure 1). Each CICS server must have a unique transaction ID and that transaction ID must consist of three unique characters followed by 'F' (e.g. BETF). Each CICS server executing within a single CICS region behaves as a unique file access provider; thus, programs compiled for transaction processing accessing multiple servers in the same CICS region is permissible.

Figure 5-1: Multiple MFA CICS Servers

You may want to consider adding additional CICS servers when:

• A large number of files need to be defined to the CICS server.
• More than 255 users need to be connected simultaneously to a CICS server (a user is a single client program requesting services of that MFA server).
• You want to impose security on the files available to a CICS server. You may want to associate files with one level of security with one server and files with more relaxed security with another.
• You only have one CICS region and want to segregate test files from production files.

To create another CICS server within the same CICS region:

1. Select a unique transaction ID that is four characters long and ends in 'F' and then define that transaction ID to CICS. (You can use the BETF transaction ID as a model when creating the new one).
2. Create a complete set of CICS server files. The files must all have a 4 character prefix that matches the name of the transaction ID selected in step 1. You must create the following files: xxxxDBR, xxxxMSG, xxxxTRC, and xxxxFCD, where xxxx is the CICS transaction code you intend to use. To create these files, edit the $CICVSAM JCL found in the INSTLIB install library, changing all references to BETF to xxxF, where xxxF is the CICS transaction code you intend to use. Then, run this job to create the required datasets.
3. Add entries to the database reference file (xxxxDBR) that associate PC filenames with the CICS filenames that the new CICS server supports. When adding these entries, keep in mind that modification of the Key Definition File affects all CICS servers defined for that CICS region.

5.6.3 Opening the Path of a KSDS for Output Processing

The IBM VS COBOL II run-time system returns a status code of '39' (program and file attributes are in conflict) when a program attempts to open a path to a KSDS (as opposed to opening the base cluster) for output processing. If, instead, the program were to open the same file for EXTEND processing, the IBM VS COBOL II run-time system would honor the request.

Post Installation Activities

Restrictions