API changes

Version 6 and higher versions

The tableBASE API introduced with Version 6, known as TBLBASE, can be used in CICS, batch, IMS TM, and DB2-SPAS operating environments. tableBASE programs that use this stub can be ported from one environment to another without requiring any stub relinking.

VTS user access

In Version 5, the VTS product had its own settings for SWITCHES. Starting with Version 6 the VTS product does not have its own SWITCHES settings; it inherits the settings from the interface corresponding to the application being run— Batch, IMS, CICS, DB2, etc. The default settings for the SWITCHES in Version 5 VTS was NNNNN, while the default settings for the Batch, IMS, CICS and DB2 interfaces differ from these values (refer to the installation chapters applicable to the interface). Therefore an application from Version 5 that may have not abended when the VTS-TSR was down (due to a 1072 error) may now abend starting with Version 6, unless the SWITCHES setting is changed from the default value to N. Other differing settings may cause other behavioral differences unless changed from their Version 5 default values.. These differences can normally be resolved by adding a TBOPT override to the application JCL (see tableBASE run-time options).

Release 5.0

From a programming viewpoint, the primary area of difference between releases is the API. Improvements have been made and parameters added or changed. The current TABLEBASE API was introduced with Release 5.0 and is designed to be used in all tableBASE environments – batch, CICS, IMS TM, and DB2-SPAS—using either a local TSR or a shared VTS-TSR.

Prior to Release 5.0, there were two “generations” of API. The older generation did not support a TB-PARM parameter and used a shorter COMMAND-AREA. This generation used the names TBCALL, TBCALLC, TBCALLV, and TBCALLI for the API; the names varied based on the environment in which tableBASE ran. The other generation used a TB-PARM parameter, but it had fewer fields than the current TB-PARM. Again, there was a separate API – TBASE, TBASEC, and TBASEV – for each environment, and the COMMAND-AREA contained fewer fields than that used by TBLBASE.

While your older programs will run unchanged with Release 5.0 and above, you should not mix interfaces in the same program, for example, TBLBASE (Release 5.0 and above) and TBCALLC (pre-Release 5.0).

The following section contrasts the older COMMAND-AREA and TB-PARM parameters provided in earlier (pre 5.0) releases of tableBASE with the later versions.

COMMAND-AREA

In extending the COMMAND-AREA for Release 5.0, we simply added fields at the end and kept the first twenty-eight bytes unchanged. Here is the older COMMAND-AREA.

 01  xxxx-COMMAND-AREA-R4.
     05  xxxx-COMMAND            PIC XX            VALUE SPACES.
     05  xxxx-TABLE              PIC X(8)          VALUE xxxx.
     05  xxxx-FOUND              PIC X             VALUE SPACES.
     05  xxxx-INDIRECT-OPEN      PIC X             VALUE LOW-VALUES.
     05  RESERVED                PIC X             VALUE LOW-VALUES.
     05  xxxx-ABEND-STATUS       PIC X             VALUE SPACES.
     05  xxxx-ERROR              PIC S9(4          COMP VALUE +0.
     05  xxxx-COUNT              PIC S9(8)         COMP VALUE +0.
* The LOCK-LATCH must be specified for Online environments and VTS.
     05 xxxx-LOCK-LATCH          PIC X(8)          VALUE SPACES. 
And, here is the COMMAND-AREA for later releases of Version 5 and higher versions.

 01 xxxx-COMMAND-AREA.
    05  xxxx-COMMAND                       PIC XX   VALUE SPACES.
    05  xxxx-TABLE                         PIC X(8) VALUE xxxx.
    05  xxxx-FOUND                         PIC X    VALUE SPACES.
    05  xxxx-INDIRECT-OPEN                 PIC X    VALUE LOW-VALUES.
    05  RESERVED                           PIC X    VALUE LOW-VALUES.
    05  xxxx-ABEND-OVERRIDE                PIC X    VALUE SPACES.
    05  xxxx-ERROR                         PIC S9(4)COMP VALUE +0.
    05  xxxx-COUNT                         PIC S9(9)COMP VALUE +0.
*   The LOCK must be specified for Online environments and VTS.
    05  xxxx-LOCK-LATCH                    PIC X(8) VALUE SPACES.
*   Release 5.x command area extension
    05  xxxx-ROW-OVERRIDE-LENGTH           PIC S9(9)COMP VALUE +0.
    05  xxxx-ROW-ACTUAL-LENGTH             PIC S9(9)COMP VALUE +0.
    05  xxxx-FG-KEY-LENGTH                 PIC S9(4)COMP VALUE +0.
    05  xxxx-FUNCTION-ID                   PIC S9(4)COMP VALUE +0.
    05  xxxx-FUNCTION-AREA                 PIC X(28)VALUE LOW-VALUES.
    05  xxxx-DATE-AREA                     REDEFINES XXXX-FUNCTION-AREA.
        10  xxxx-DATE                      PIC X(8).
    05  RESERVED                           PIC X(19).
*   START-TBUOW is new with Version 7.
    05  xxxx-START-TBUOW                   PIC X VALUE LOW-VALUES.
    05  xxxx-ABS-GEN-NO                    PIC S9(4) COMP VALUE +0.
    05  xxxx-ERROR-SUBCODE                 PIC S9(4) COMP VALUE +0.

TB-PARM

As mentioned above, the TBCALL series of APIs do not use the TB-PARM parameter at all. The TBASE series of APIs uses a shorter TB-PARM parameter than does TBLBASE. This shorter TB-PARM is as follows:

01 TB-PARM-R4.
   10 TB-PARM-ID                           PIC X(2)  VALUE 'TB'.
   10 TB-FUNCTION                          PIC S9(4) VALUE +0.
   10 TB-RESERVED                          PIC X(4)  VALUE LOW-VALUES.
   10 TB-SUBSYSTEM                         PIC X(4)  VALUE LOW-VALUES.
   10 TB-RESERVED                          PIC X(8)  VALUE LOW-VALUES.
   10 TB-DATE                              PIC (8). 

Not only is it shorter than the TB-PARM used with the current TBLBASE API, the above TB-PARM parameter also has a different format. Each field is described below.

  1. TB-PARM-ID (2 bytes)

    The literal ‘TB’ identifies this parameter as a TB-PARM communications area. (The Release 5.0 version of the TB-PARM parameter contains an identifying ‘5’ in byte 5 for use by TBLBASE only; anything else in byte 5 indicates a previous release TB-PARM-R4 format for use by TBLBASE or any TBASEx interface).

  2. TB-FUNCTION (halfword binary)

    This field, when set to 0, indicates that the CALL does normal processing. When set to 1, it identifies the CALL as subject to Date-Sensitive Processing. In Release 5.0 and above, this field is now part of the COMMAND-AREA and is known as FUNCTION-ID.

  3. TB-RESERVED (4 bytes)

    This field is reserved for internal use and should be set to low values at initialization.

  4. TB-SUBSYSTEM (4 bytes)

    This field names the VTS subsystem for the target TSR. This should be set to low values or spaces to indicate a local (non-VTS) TSR. This field will be found in a different location in the Release 5.0 version of TB-PARM.

  5. TB-RESERVED (8 bytes)

    This field is reserved for internal use and is expected to be set to low values initially.

  6. TB-DATE (8 bytes)

    This field contains the application date to be used for Date-Sensitive Processing with TBASE. It is entered in YYYYMMDD format. For the TBLBASE API, this information appears in the Release 5.0 extended command area parameter, not in TB-PARM. It is known as xxxx-DATE (see previous section, COMMAND-AREA).