Preparing the Supra Environment

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

Customize the LINKEDIT JCL

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.

Modify the following LINKEDIT JCL to conform to site standards and submit it for execution. The JCL listed below displays the GENESUPR JCL that is available at qualif.HOME.DATA: 

//*        Job Card Goes Here                                         
//*                                                                   
//* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
//*Purpose: Linkedit SUPRA API routines into Supra Adapter          * 
//*         This is required if you run applications that connect   * 
//*         to SUPRA database.                                      * 
//*                                                                 * 
//*Substitutions:                                                   * 
//*         In the SET statements, supply the values for 'supra',   * 
//*         'target' and 'home' according to description.           * 
//*                                                                 * 
//*    target library must be placed ahead of home library in       * 
//*    STEPLIB concatenation of IRUNJCL.                            * 
//* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
//        SET  SUPRA=<SUPRA LINKLIB object library>                   
//        SET  TARGET=<Library to receive relink modules>             
//        SET  HOME=<Installation HOME.LOAD library>                  
//LKED    EXEC PGM=IEWL,PARM='MAP,XREF'                               
//SUPRA   DD   DISP=SHR,DSN=&SUPRA                                    
//SYSLMIN DD   DISP=SHR,DSN=&HOME             
//SYSLMOD DD   DISP=SHR,DSN=&TARGET           
//SYSUT1   DD   UNIT=SYSDA,SPACE=(100,(50,50))
//SYSPRINT DD   SYSOUT=*                      
//SYSLIN   DD   *                             
  INCLUDE SUPRA(CSVILUV)                      
  INCLUDE SYSLMIN(FSP000)                     
  MODE AMODE(64),RMODE(24)                    
  ENTRY FSP000                                
  NAME FSP000(R)                              
/*

where:

SET SUPRA=<SUPRA LINKLIB object library>

Specifies the fully-qualified name of the SUPRA linklib library that contains the CSVILUV module.

SET TARGET=<Library to receive relink modules>

Specifies the fully-qualified name of the load library receiving the relink module.

SET HOME=<Installation HOME.LOAD library>

Specifies the fully-qualified name of the server installation HOME.LOAD load library.

Customize the Server IRUNJCL JCL

If, during ISETUP installation, you selected Yes for Supra Adapter, the IRUNJCL will already contain the STEPLIB allocations for Supra. If you missed that at install time, you can manually add these allocations to the server IRUNJCL.

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

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 sign-on 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)

Utilize the Security Exit

To utilize the security exit, perform the following steps.

    Procedure
  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.HOME.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.HOME.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 fully-qualified name of the library containing the FSPEXT object code.

    qualif. HOME.LOAD

    Is the adapter load library.

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