Example project with linked remote resources

The following describes an example COBOL project with linked remote resources. It uses a SESAM database and accesses it with ESQL/COBOL. Sources do not have an extension as suffix of their element names. Sources needing different treatment are thus stored in different libraries.

The contents of files and configuration settings are provided as plain text rather than screen shots, so you can drag and drop from this help page.

Alternatively you can click here to let Eclipse create the project for you. You must then select a connection to a BS2000 system, and you can specify another name for the project. Furthermore check the ESQL and SESAM configuration and adjust them if necessary. Note, the pair consisting of DBH name and configuration name must be unique on your system.

This example project expects the following products and/or subsystems on the BS2000 system:

SDF-P as of V2.4

COBOL2000 as of V1.5

ESQL-COBOL as of V3.0

SESAM/SQL as of V6.0

JV as of V15.0

Creating the project resources on BS2000

We start with creating resources on the BS2000 system. We open the BS2000 Explorer view, connect to the BS2000 system, and create the following PLAM libraries, see Creating new BS2000 files:

demo2.tools	for command procedures
demo2.copybook	for copy elements
demo2.hello	for the main COBOL program
demo2.dbaccess	for ESQL/COBOL programs accessing the data base

Within these libraries we create the following elements:

Command procedure demo2.tools/j/cobol

/BEGIN-PARAMETER-DECLARATION  "Compile a COBOL source"
/    DECLARE-PARAMETER  LIB (TYPE = STRING)  "source library"
/    DECLARE-PARAMETER  SRC (TYPE = STRING)  "source element"
/END-PARAMETER-DECLARATION
/ASSIGN-SYSLST *LIB-ELEM(&LIB, &SRC, P)
/SET-FILE-LINK COBLIB, DEMO2.COPYBOOK
/START-COBOL2000-COMPILER                                         -
/    SOURCE          = *LIBRARY-ELEMENT (&LIB, &SRC),             -
/    MODULE-OUTPUT   = *LIBRARY-ELEMENT (LIB = &LIB),             -
/    COMPILER-ACTION = *MODULE-GENERATION (MODULE-FORMAT = *LLM), -
/    TEST-SUPPORT    = *AID,                                      -
/    LISTING         = *PARAMETERS (SOURCE = *YES (INSERT-ERROR-MSG = *YES), OUTPUT = *SYSLST)
/SET-JOB-STEP
/ASSIGN-SYSLST *PRIMARY
/EXIT-PROCEDURE

The /SET-JOB-STEP command guarantees that the procedure returns with exit code 0 even if the compiler encounters syntax errors.

Command procedure demo2.tools/j/esql

/BEGIN-PARAMETER-DECLARATION    "Compile an ESQL/COBOL source"
/    DECLARE-PARAMETER  LIB (TYPE = STRING)  "ESQL input library"
/    DECLARE-PARAMETER  SRC (TYPE = STRING)  "ESQL input element"
/END-PARAMETER-DECLARATION
/SET-FILE-LINK SESAMOML, $TSOS.SYSLNK.SESAM-SQL.080
/SET-FILE-LINK SESCONF,  DEMO2.CONF
/START-ESQLCOB                                                       -
/    SOURCE             = *LIB-ELEM(&LIB, &SRC),                     -
/    SOURCE-PROPERTIES  = (CATALOG =       DEMO2,                    -
/                          SCHEMA  =       DEMO2_SCHEMA,             -
/                          AUTHORIZATION = D0USER),                  -
/    INCLUDE-LIBRARY    = ($TSOS.SYSLIB.ESQL-COBOL.030.INCL-V2,      -
/                          DEMO2.COPYBOOK),                          -
/    PRECOMPILER-ACTION = (DATABASE-CONTACT = YES,                   -
/                          SQL-ENTRY-NAME = &SRC),                   -
/    HOST-PROGRAM       = *LIB-ELEM(&LIB..COB, &SRC),                -
/    MODULE-LIBRARY     = *LIB-ELEM(&LIB, &SRC..SQL)
/SET-JOB-STEP
/ASSIGN-SYSLST *LIB-ELEM(&LIB, &SRC, P)
/SET-FILE-LINK COBLIB, DEMO2.COPYBOOK
/START-COBOL2000-COMPILER                                            -
/    SOURCE          = *LIB-ELEM(&LIB..COB, &SRC),                   -
/    MODULE-OUTPUT   = *LIBRARY-ELEMENT (LIB = &LIB),                -
/    COMPILER-ACTION = *MODULE-GENERATION (MODULE-FORMAT = *LLM),    -
/    TEST-SUPPORT    = *AID,                                         -
/    LISTING = *PARAMETERS (SOURCE = *YES (INSERT-ERROR-MSG = *YES), -
/                           OUTPUT = *SYSLST)
/SET-JOB-STEP
/ASSIGN-SYSLST *PRIMARY
/EXIT-PROCEDURE

The ESQL precompiler generates the COBOL source in a library &LIB..COB. Listings and LLMs are generated in the same library as the precompiler input, &LIB

The /SET-JOB-STEP commands guarantee that the procedure returns with exit code 0 even if the compiler encounters syntax errors.

Note, you probably need to adjust the versions of SESAM-SQL and ESQL-COBOL to those installed on your BS2000 server.

Command procedure demo2.tools/j/bind

/REMARK Binds the application
/START-BINDER
//START-LLM-CREATION INTERNAL-NAME = HELLO, -
//    INCLUSION-DEFAULTS = *PARAMETERS (TEST-SUPPORT = *YES)
//INCLUDE-MODULES MODULE-CONTAINER = -
//    *LIBRARY-ELEMENT(LIBRARY = DEMO2.HELLO, ELEM = HELLO)
//INCLUDE-MODULES MODULE-CONTAINER = -
//    *LIBRARY-ELEMENT(LIB = $TSOS.SYSLNK.SESAM-SQL.080, ELEM = SESMOD)
//RESOLVE-BY-AUTOLINK LIBRARY = -
//    ($TSOS.SYSLNK.CRTE, DEMO2.DBACCESS)
//SAVE-LLM LIBRARY = DEMO2, OVERWRITE = *YES, -
//    MAP = *NO, TEST-SUPPORT = *YES
//END
/EXIT-PROCEDURE

This procedure does neither contain a /SET-JOB-STEP command nor a //STEP statement. Possible errors will be reported to the caller with an exit code different from 0.

Note, you probably need to adjust the version of SESAM-SQL to that installed on your BS2000 server.

Command procedure demo2.tools/j/clean

/REMARK Clean derived resources
/START-LMS
//DELETE-ELEM ELEM = *LIB(LIB = DEMO2.HELLO, ELEM = *ALL, TYPE = P)
//STEP
//DELETE-ELEM ELEM = *LIB(LIB = DEMO2.HELLO, ELEM = *ALL, TYPE = L)
//STEP
//DELETE-ELEM ELEM = *LIB(LIB = DEMO2.DBACCESS, ELEM = *ALL, TYPE = P)
//STEP
//DELETE-ELEM ELEM = *LIB(LIB = DEMO2.DBACCESS, ELEM = *ALL, TYPE = L)
//END
/SET-JOB-STEP
/DELETE-FILE DEMO2.DBACCESS.COB
/SET-JOB-STEP 
/DELETE-FILE DEMO2 
/SET-JOB-STEP
/EXIT-PROCEDURE

The //STEP statements and the /SET-JOB-STEP commands guarantee that this procedure returns with exit code 0 even if the elements or libraries should not exist. Note, the following libraries will be created during builds and are thus derived resources:

demo2.dbaccess.cob	for COBOL programs generated by the ESQL precompiler
demo2	for the executable program generated by the binder

Enter job demo2.tools/j/start-dbh-new

/LOGON
/START-SESAM-DBH
//SET-DBH-OPTIONS -
//  DBH-IDENTIFICATION = *PARAMETERS(CONFIGURATION-NAME = Z, -
//                                   DBH-NAME = X),-
//  ADMINISTRATION = *PARAMETERS( ADMINISTRATOR = *ANY(PASSWORD='ADM'))
//ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 = *NONE
//END
/LOGOFF

Job to start data base handler ZX with no catalog.

Enter job demo2.tools/j/start-dbh-demo2

/LOGON
/START-SESAM-DBH
//SET-DBH-OPTIONS -
//  DBH-IDENTIFICATION = *PARAMETERS(CONFIGURATION-NAME = Z, -
//                                   DBH-NAME = X),-
//  ADMINISTRATION = *PARAMETERS( ADMINISTRATOR = *ANY(PASSWORD='ADM'))
//ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 = *CATALOG(-
//       CATALOG-NAME=DEMO2)
//END
//END
/LOGOFF

Job to start data base handler ZX with catalog demo2.

Command procedure demo2.tools/j/start-dbh

/REMARK Checks whether the data base handler is already running
/REMARK If db not yet created, creates it
/REMARK If dbh not yet running, starts it 
/IF (IS-CAT-JV (JV = 'SESAM.SESDBH.ZX'))
/    IF (SUBSTR(JV('SESAM.SESDBH.ZX'), 35, 11) EQ 'DBH-STARTED')
/        EXIT-PROCEDURE
/    END-IF
/END-IF
/IF NOT IS-CATALOGED-FILE (FILE = 'DEMO2.CATALOG')
/    ENTER-JOB FROM-FILE = (LIB = DEMO2.TOOLS, ELEM = START-DBH-NEW)
/    WAIT-EVENT UNTIL = *JV (                                     -
/        CONDITION  = ((SESAM.SESDBH.ZX,35,11) = 'DBH-STARTED'),  -
/        TIME-LIMIT = 300)
/    ADD-FILE-LINK LINK-NAME = SESCONF,  FILE-NAME = DEMO2.CONF
/    ADD-FILE-LINK LINK-NAME = SEEINPUT, FILE-NAME = DEMO2.SCHEMA
/    START-SESAM-UTILITY-MONITOR
/ELSE
/    ENTER-JOB FROM-FILE = (LIB = DEMO2.TOOLS, ELEM = START-DBH-DEMO2)
/    WAIT-EVENT UNTIL = *JV (                                     -
/        CONDITION  = ((SESAM.SESDBH.ZX,35,11) = 'DBH-STARTED'),  -
/        TIME-LIMIT = 300)
/END-IF
/EXIT-PROCEDURE

Command procedure demo2.tools/j/run

/REMARK Runs the built application
/SET-FILE-LINK SESAMOML, FILE-NAME = $TSOS.SYSLNK.SESAM-SQL.080
/SET-FILE-LINK SESCONF,  FILE-NAME = DEMO2.CONF
/START-EXECUTABLE-PROGRAM (LIBRARY = DEMO2, ELEMENT = HELLO), TEST-OPTIONS = *AID
/EXIT-PROCEDURE

Note, you probably need to adjust the version of SESAM-SQL to that installed on your BS2000 server.

Command procedure demo2.tools/j/stop-dbh

/REMARK Stop dbh
/ADD-FILE-LINK LINK-NAME = SESCONF, FILE-NAME = DEMO2.CONF
/START-SESAM-ADMINISTRATION
//START-DBH-ADM C'ADM'
//STOP-DBH *DEL
//END
/EXIT-PROCEDURE

Database configuration file demo2.conf

CNF=Z
NAM=X
NVT
NOTYPE
SEE-ADMIN=ADM
SEE-AUTHID=D0USER
SEE-CATALOG=DEMO2
SEE-SCHEMA=DEMO2_SCHEMA
SEE-STOGROUP=D0STOGROUP

Database schema creation file demo2.schema

SQL CREATE CATALOG DEMO2 CATALOG_SPACE SHARE NO DESTROY -
                   USER D0USER, (*, *, *) 
SQL COMMIT
SQL CREATE SCHEMA DEMO2.DEMO2_SCHEMA AUTHORIZATION D0USER -
    CREATE TABLE  FLINTSTONES -
        (FIRST_NAME CHAR(10), - 
         LAST_NAME  CHAR(10) PRIMARY KEY)
SQL COMMIT
END

COBOL copybook element copybook/s/person

       01 person.                    
           05 first-name PICTURE X(10).
           05 last-name  PICTURE X(10).

COBOL source program hello/s/hello

       PROGRAM-ID. hello.
       ENVIRONMENT DIVISION.          
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           TERMINAL IS std-terminal.
                
       DATA DIVISION.                 
       WORKING-STORAGE SECTION.       
       COPY PERSON. 
                      
       PROCEDURE DIVISION.
           CALL "INIT-DB".
           MOVE "Flintstone" TO last-name OF person.
           CALL "SELECT-FROM-DB"  USING person. 
           DISPLAY "Hello " first-name OF person UPON std-terminal.
           STOP RUN. 
                     
       END PROGRAM hello.

ESQL/COBOL source program dbaccess/s/init

       PROGRAM-ID. init-db.
       ENVIRONMENT DIVISION.          
       CONFIGURATION SECTION.
                
       DATA DIVISION.                 
       WORKING-STORAGE SECTION.
       
       EXEC SQL BEGIN DECLARE SECTION END-EXEC  
       EXEC SQL
           INCLUDE PERSON
       END-EXEC      
       01 SQLSTATE    PICTURE X(5).
       EXEC SQL END   DECLARE SECTION END-EXEC 
       EXEC SQL
           INCLUDE SQLCA
       END-EXEC
                      
       PROCEDURE DIVISION.
           MOVE "Fred"        TO first-name.
           MOVE "Flintstone"  TO last-name. 
           EXEC SQL
               INSERT INTO DEMO2.DEMO2_SCHEMA.FLINTSTONES
                   VALUES (:first-name, :last-name)    
           END-EXEC
           
           MOVE "Barney"      TO first-name.
           MOVE "Rubble"      TO last-name.
           EXEC SQL
               INSERT INTO DEMO2.DEMO2_SCHEMA.FLINTSTONES 
                   VALUES (:first-name, :last-name) 
           END-EXEC
           
           EXEC SQL COMMIT WORK END-EXEC
           EXIT PROGRAM. 
                     
       END PROGRAM init-db.

ESQL/COBOL source program dbaccess/s/select

 
       PROGRAM-ID. select-from-db.
       ENVIRONMENT DIVISION.          
       CONFIGURATION SECTION.
                
       DATA DIVISION. 
       
       WORKING-STORAGE SECTION.
       EXEC SQL BEGIN DECLARE SECTION END-EXEC       
       01 output-first-name PICTURE X(10).
       01 input-last-name   PICTURE X(10).
       01 SQLSTATE          PICTURE X(5).
       EXEC SQL END   DECLARE SECTION END-EXEC 
       EXEC SQL
           INCLUDE SQLCA
       END-EXEC 
                       
       LINKAGE SECTION.      
       COPY PERSON.
                      
       PROCEDURE DIVISION USING person. 
           MOVE last-name OF person TO input-last-name. 
           EXEC SQL
               SELECT FIRST_NAME INTO :output-first-name 
                   FROM DEMO2.DEMO2_SCHEMA.FLINTSTONES
                   WHERE LAST_NAME = :input-last-name
           END-EXEC          
           MOVE output-first-name TO first-name OF person.
           EXIT PROGRAM.
       END PROGRAM select-from-db.

Creating the project demo2

Now we switch to the Resource perspective and create a new Remote Build Project demo2, see BS2000 Remote Build Projects.

Linked folders

Within the project we create linked folders as follows (see Linked resources):

Folder	Linked to
tools	demo2.tools/j/
copybook	demo2.copybook/s/
hello	demo2.hello/s/
dbaccess	demo2.dbaccess/s/

Defining commands

Pre-build command startdbh

/CALL-PROCEDURE (LIB = DEMO2.TOOLS, ELEM = START-DBH)

See BS2000 Remote Build Projects how to configure this command as pre-build command for project demo2. In case of problems (e.g. the database handler could not be successfully started) the called procedure will return with an exit code other than 0. Such exit codes should be treated as bad causing the build to fail. Thus the default setting of 0 as expected good exit code is all right.

The database handler is used by the ESQL precompiler to check embedded SQL statements. Therefore, the database handler is started (if not yet running) as pre-build action. Another option would be to call this procedure in the demo2.tools/j/esql compile procedure.

Compile command procedure COBOL - demo2

/CALL-PROC (LIB = DEMO2.TOOLS, ELEM = COBOL), (LIB = &{src-full-lib-name}, SRC = &{src-elem-name})

The called procedure returns with exit code 0 even if the compiler encountered syntax errors, so the default setting of expected exit codes is all right.

Compile rule COBOL - demo2

Name:	COBOL - demo2
Source file type:	PLAM library elements
Source pattern:	::$.demo2.hello/s/*
Listing expression:	&{src-full-lib-name}/p/&{src-elem-name}
Command:	COBOL - demo2

This compile rule must then be configured to be the first of two selected for project demo2, see BS2000 Remote Build Projects.

Compile command procedure ESQL - demo2

/CALL-PROC (LIB = DEMO2.TOOLS, ELEM = ESQL), (LIB = &{src-full-lib-name}, SRC = &{src-elem-name})

The called procedure returns with exit code 0 even if the compiler encountered syntax errors, so the default setting of expected exit codes is all right.

Compile rule ESQL - demo2

Name:	ESQL - demo2
Source file type:	PLAM library elements
Source pattern:	::$.demo2.dbaccess/s/*
Listing expression:	&{src-full-lib-name}/p/&{src-elem-name}
Command:	ESQL - demo2

This compile rule must then be configured to be the second of two selected for project demo2, see BS2000 Remote Build Projects.

Command procedure bind - demo2

/CALL-PROC (LIB = DEMO2.TOOLS, ELEM = BIND)

See BS2000 Remote Build Projects how to configure this command as post-build command for project demo2. In case of problems the called procedure will return with an exit code other than 0. Such exit codes should be treated as bad causing the build to fail. Thus the default setting of 0 as expected good exit code is all right.

Command procedure clean - demo2

/CALL-PROC (LIB = DEMO2.TOOLS, ELEM = CLEAN)

See BS2000 Remote Build Projects how to configure this command for project demo2. The called procedure always returns with exit code 0, so the default setting of expected exit codes is all right.

Command procedure run - demo2

/CALL-PROC (LIB = DEMO2.TOOLS, ELEM = RUN)

See Run and Debug Configurations how to configure this command for project demo2.