Preparing the Supra Environment

How to:

Prior to starting the server, it is necessary to perform the following preconfiguration procedures when preparing the environment on z/OS.


Top of page

x
Procedure: How to Customize the LINKEDIT JCL

To customize the LINKEDIT JCL:

  1. After executing ISETUP, the JCL will be generated to LINKEDIT the supplied Adapter for Supra module with the Supra stub called CSVILUV. The CSVILUV module is supplied by the Supra vendor, Cincom, and usually resides in the Supra LINKLIB library.

    This required step allows the Adapter for Supra module to communicate with the Supra Central PDM.

  2. Modify the following LINKEDIT JCL to conform to site standards and submit it for execution. The JCL listed below displays the GENEFSP JCL that is generated
    //LINK1    EXEC PGM=IEWL,PARM='XREF,LET,LIST,MAP,SIZE=1024K'
    //SYSLIB   DD  DUMMY
    //SYSPRINT DD  SYSOUT=*
    //SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(10,1))
    //SUPRA    DD  DSN=cincom.LINKLIB,DISP=SHR
    //SYSLMOD  DD  DSN=qualif.TOTAL.LOAD,DISP=SHR
    //MAINTAIN DD  DSN=qualif.TOTAL.DATA,DISP=SHR
    //SYSLIN   DD *
      INCLUDE SUPRA(CSVILUV)
      INCLUDE SYSLMOD(FSP000)
      INCLUDE MAINTAIN(FSP000)
      NAME FSP000(R)
    /*
    //

    where:

    qualif

    Is the high-level qualifier for the server production libraries.

    cincom.LINKLIB

    Is the name of the Supra load library supplied by Cincom that contains the CSVILUV module.

    qualif.TOTAL.LOAD

    Is the name of the adapter load library.

    qualif.TOTAL.DATA

    Is the name of the adapter data library.

    Upon successful completion of the LINKEDIT JCL, the adapter module will be ready for use with the server.


Top of page

x
Procedure: How to Customize the Server EDASTART JCL

To customize the server EDASTART JCL, add the Supra load libraries to STEPLIB in the server's EDASTART JCL for Supra access.

Note: The Supra DBMS has three load libraries: LINKLIB, INTERFLM, and ENVLIB. These load libraries must be concatenated to ddname STEPLIB.


Top of page

x
Procedure: How to Allocate CSIPARM

You must allocate ddname CSIPARM to the data set that contains the CSIPARM definition, which in turn points to the Central PDM you are accessing. Contact your Supra DBA for the name of the file

//CSIPARM) DD('cincom.CSIPARM(CONNECT)'),DISP=SHR

where:

cincom

Is the high-level qualifier for the Supra libraries supplied by Cincom.


Top of page

x
Procedure: How to Set the CSISYSIN Parameters

The Adapter for Supra multi-session facility provides multi-session capability for server tasks to access the Supra Physical Data Manager (PDM) using the Call Database facility or the Relational Data Manager (RDM). It connects with the PDM on the first access by a task. The connecting task is used solely as the connection task and is not usable for other operations. The number of task and concurrent operations supported during the session is controlled by input parameters specified in the data set allocated to ddname CSISYSIN.

There is no security provided by the multi-session adapter. However, the multi-session facility does provide a security exit that can be used to control user access to the database resource. This security exit is identified with the "SECURITY =" keyword described in the next section.

The parameters used for connecting the multi-session adapter to the Central PDM is allocated to ddname CSISYSIN in the server JCL as follows:

//CSISYSIN DD DSN=qualif.TOTAL.DATA(SUPRCNFG),DISP=SHR

The options available are listed below; xx denotes a value to be supplied by the user. Keywords must start in column 1 and each must be specified on a separate input statement. An asterisk (*) in column 1 indicates a commented line.

Keyword

Description

THREADS=xx

Number of concurrent requests that can be issued to the PDM. If this number is too small, a TFUL status may result. See the Supra PDM Administrator Guide for more information.

TASK=xx

Maximum number of tasks that can be signed on to the PDM at any one time, including two tasks used for the Autostart facility and for adapter tracking. Therefore, if TASK=10, up to 8 users can be signed on. If this value is exceeded, a CFUL or MFUL status may result. The MFUL status is from the multi-session adapter and indicates that the task tables are full. A CFUL is from the PDM and indicates the same for the PDM.

SECURITY=xxxxxxx

Name of the user written security module that will validate access of users to the PDM data resources. If provided, it must reside in a library accessible from the multi-session adapter.

DEBUG=xxx

Diagnostic facility that provides console messages for problem tracing. Refer to Adapter Tracing for details.

END

Ending statement for the parameters. The period is required.



x
Procedure: How to Configure the Adapter Batch Autostart Facility

When using the Multi-Session Facility for Supra with the server, the first task that issues a request to the Central PDM will be used by the multi-session adapter to establish a permanent connection between the Central PDM and the server. The initial request, if executed from a server client, would tie up that client until the server was shut down. To avoid this scenario, use the Batch Autostart Facility to initialize and establish the connection between the server and Central PDM regions.

Certain parameters in the EDAPROF profile can interfere with the operation of the Batch Autostart Facility. If the service block associated with the Autostart facility (GATEKEPR) executes properly, but no connection is made to Supra, there may be a conflict between your profile and the Autostart facility. To bypass the profile, use the MSOINFO subroutine at the top of your profile to avoid executing the rest of the profile.

The following sample code uses Dialogue Manager to request information about SERVICE and branch out of the profile if appropriate:

-SET &REQ = 'SERVICE ';
-SET &ANS = '        ';
-TSO RUN MSOINFO,&REQ,&ANS
-IF &ANS = 'GATEKEPR' GOTO END

Note: If you bring up the server before the Supra PDM is up, the Autostart connection will not be established. Also, if the PDM is recycled, the Autostart connection will be broken. To connect under these circumstances, use the server console to restart the service block associated with the Autostart task (SERVICE=GATEKEPR).

Note: If you bring up the server before the Supra PDM is up, the Autostart connection will not be established; also, if the PDM is recycled, the Autostart connection will be broken. To connect under these circumstances, use the server console to restart the service block associated with the Autostart task (SERVICE=GATEKEPR).


Top of page

x
Procedure: How to Define the GATEKEPR Service Block

The server configuration file must be modified to include an additional service block. This service block is used by the server to execute an exec at startup time which will run as a background task and establish the link between the server and the PDM. The syntax for adding the additional service block is

SERVICE = GATEKEPR
BEGIN
   PROGRAM = TSCOM3
   NUMBER_READY = 1
   MAXIMUM = 1
   RUNCOUNT = 5
   AUTOSTART = BATCH
PROFILE = baseapp/supprof
END

where:

SERVICE

Identifies and names a service. The name that you choose should be unique and from one to eight characters in length. The keywords and values that follow the SERVICE keyword in each service block define the type of service to be provided. GATEKEPR is the recommended name.

PROGRAM

This parameter should always be set to TSCOM3.

NUMBER_READY

Is the number of instances of this service to be preloaded by the server. This parameter should always be set to 1.

MAXIMUM

Is the number of instances of this service allowed by the server. This parameter should always be set to 1.

RUNCOUNT

Specifies the number of attempts to connect to the central PDM. There is no default value, therefore you must specify a value to prevent the server from continually attempting to access Supra data.

PROFILE

Identifies the file containing a simple request against the Central PDM. The result of this request is the establishment of a multi-session communications link between the server and the Central PDM. Any simple request against a Supra data source can be used for establishing the link.

Note: All parameters must start in column 1 in the configuration file. Any line starting with an asterisk (*) will be considered a comment.

To summarize, the following items are required to implement the Batch Autostart Facility:


Top of page

x
Procedure: How to Install the Adapter for Supra Security Exit (optional)

The Adapter for Supra has a security exit, FSPEXT, that allows the user to obtain the account name and account password from a user defined source. The account name and account password are then passed to the adapter and used for login to the Central PDM.

When you issue a request against the Supra database, the adapter calls the FSPEXT function with standard IBM calling conventions, and passes it these parameters:

USR

Passed to function (Server Logon User ID)

8 Bytes Alpha

ACCNT

Returned from function

16 Bytes Alpha

ACCNTP

Returned from function

16 Bytes Alpha

The function returns ACCNT and ACCNTP to the adapter which uses them as parameters to the signon call it issues. The adapter calls the user exit if the password is not available from other sources (for example, the SET command or an Access File). The exit is loaded as a module using a LOAD macro from ddname USERLIB, TASKLIB, or STEPLIB in that order. It is called in AMODE 31. The syntax for the call to the FSPEXT function is:

CALL FSPEXT(USR,ACCNT,ACCNTP)


x
Procedure: How to Utilize the Security Exit

To utilize the security exit you must:

  1. Write the function using COBOL or Assembler. The function name must be FSPEXT. An example of the FSPEXT function written in Assembler follows.
    * SAMPLE EXIT FOR Supra ADAPTER
     
          EJECT
    FSPEXT  CSECT
          USING FSPEXT,R15       TEMPORARY ADDRESSABILITY
          B     PROC             JUMP AROUND THE ID INFORMATION
    * ID INFORMATION
          DC    CL8'FSPEXT '     PROG NAME
          PRINT NOGEN
    PROC STM    R14,R12,12(R13)
          LR    R12,R15
          DROP  R15
          USING FSPEXT,R12
          ST    R13,SAVAR+4
          MVC   8(4,R13),=A(SAVAR)
          LA    R13,SAVAR
    *
    *     INSERT THE CODE TO FETCH THE ACCOUNT /PASSWORD
           L     R2,4(R1)
           MVC   0(16,R2),=CL16'EXITACCOUNT     '
           L     R2,8(R1)
           MVC   0(16,R2),=CL16'EXITPASS        '
    *
           L     R13,SAVAR+4
           LM    R14,R12,12(R13)
           BR    R14
    ************************************************************
           SAVAR  DS    18F
            R1    EQU   1
            R2    EQU   2
            R9    EQU   9
            R10   EQU   10
            R11   EQU   11
            R12   EQU   12
            R13   EQU   13
            R14   EQU   14
            R15   EQU   15
    *
                 END
  2. LINKEDIT the object module into the 'qualif.TOTAL.LOAD' library with AMODE(31). For example
    //LINK     EXEC PGM=IEWL,PARM='LET,NCAL,SIZE=(1024K),LIST'
    //OBJLIB   DD   DSN=objlib,DISP=SHR
    //SYSLMOD  DD   DSN=qualif.TOTAL.LOAD,DISP=SHR
    //SYSUT1   DD   UNIT=SYSDA,SPACE=(CYL,(10,1))
    //SYSPRINT DD   SYSOUT=*
    //SYSLIN   DD   *
      INCLUDE OBJLIB(FSPEXT)
      ENTRY FSPEXT
      MODE AMODE(31)
      NAME FSPEXT(R)
    /*
    //

    where:

    objlib

    Is the name of the library containing FSPEXT object code.

    qualif.TOTAL.LOAD

    Is the adapter load library.

  3. If you LINKEDIT the object module into a load library other than 'qualif.TOTAL.LOAD', concatenate the load library from Step 2 to the STEPLIB DD in your server JCL.

iWay Software