Installing a batch application involves running the application through a DB2 Server for VSE preprocessor. The preprocessor output must be compiled (or assembled), and the object decks must be link-edited. Refer to Figure 52 for generic JCL for these tasks.
Figure 52. Creating an Object Deck and Phase for a Batch Program (Multiple User Mode) Notes:
// MYPROG program name
*
// DLBL IJSYSPH,'PREPROCESSOR.OUTPUT',0 *-- PREPROCESSOR output
// EXTENT SYSPCH,........ *--
ASSGN SYSPCH,.... *-- SYSPCH assignment
*
// LIBDEF ....... *-- Library definitions
*
// ASSGN SYSxxx,... *-- Preprocessor workfiles
*
// DLBL SQLGLOB,....,DISP=(OLD,KEEP) *-- SQLGLOB parm file
// DLBL SQLBIND,....,DISP=(OLD,KEEP) *-- BIND output file
// DLBL BINDWKF,.... *-- BIND work file
*
// EXEC ARIPRPx,SIZE=AUTO,PARM='USERID=SQLDBA/SQLDBAPW,PREPNAME=MYPROG,*
KEEP,....... ' *-- Invoke DB2 for VSE PREPROCESSOR
*
* MYPROG input here if SYSRDR and SYSIPT assigned to same device
*
/*
CLOSE SYSPCH,00D *-- Close SYSPCH
*
// DLBL IJSYSIN,'PREPROCESSOR.OUTPUT',0 *-- Input File
// EXTENT SYSIPT,........ *--
ASSGN SYSIPT,.... *--
*
// OPTION CATAL ...... *--
ACTION MAP *--
PHASE MYPROG,* *--
// EXEC compiler *-- Compile
INCLUDE ARIPRDID *-- DB2 for VSE Resource
Adapter stub
INCLUDE ..... *-- Include runtime routines
*
// EXEC LNKEDT *-- Link Edit
CLOSE SYSIPT,00C *-- Reset SYSIPT
/*
/&
Compiler references & Library definitions
Two steps are required to install an online application:
Figure 53. Creating an Object Deck and Phase for an Online Program (Multiple User Mode) Notes:
// MYPROG program name
// DLBL IJSYSPH,'PREPROCESSOR.OUTPUT',0 *-- PREPROCESSOR output
// EXTENT SYSPCH,...... *--
ASSGN SYSPCH,... *-- SYSPCH assignment
// LIBDEF ....... *-- Library definitions
// ASSGN SYSxxx,... *-- Preprocessor workfiles
// DLBL SQLGLOB,....,DISP=(OLD,KEEP) *-- SQLGLOB parm file
// DLBL SQLBIND,....,DISP=(OLD,KEEP) *-- BIND output file
// DLBL BINDWKF,.... *-- BIND work file
// EXEC ARIPRPx,SIZE=AUTO,PARM='USERID=SQLDBA/SQLDBAPW,PREPNAME=MYPROG,*
KEEP,....... ' *-- Invoke DB2 for VSE PREPROCESSOR
*
* MYPROG input here if SYSRDR and SYSIPT assigned to same device
*
/*
CLOSE SYSPCH,00D *-- Close SYSPCH
*
* For ASSEMBLER only, convert to 80 byte input format for
* CICS Translator, dropping the stacker select prefix added
* to SYSPCH above. See notes for details
*
// DLBL IJSYSIN,'PREPROCESSOR.OUTPUT',0 *--} For ASSEMBLER replace
// EXTENT SYSIPT,..... *--} with statements in the
ASSGN SYSIPT,... *--} notes section
*
// DLBL IJSYSPH,'TRANSLATOR.OUTPUT',0 *-- CICS Translator output
// EXTENT SYSPCH,...... *--
ASSGN SYSPCH,... *--
*
// EXEC DFHExP1$,SIZE=400K *-- CICS Translator
CLOSE SYSIPT,00C *--
CLOSE SYSPCH,00D *--
*
// DLBL IJSYSIN,'TRANSLATOR.OUTPUT',0 *-- CICS Translator output
// EXTENT SYSIPT,....... *-- (input to the compiler)
ASSGN SYSIPT,... *--
*
// OPTION CATAL ...... *--
ACTION MAP *--
PHASE MYPROG,* *--
INCLUDE DFHxxxx *-- CICS host language module
// EXEC compiler *-- Compile
INCLUDE ARIRRTED *-- DB2 for VSE Resource
Adapter stub
INCLUDE ..... *-- Include runtime routines
// EXEC LNKEDT *-- Link Edit
CLOSE SYSIPT,00C *-- Reset SYSIPT
/*
/&
Compiler/Translator references and Library definitions
statements identified in the JCL:
// DLBL UIN,'PREPROCESSOR.OUTPUT',0 *-- Output from DB2 for VSE Preprocessor
// EXTENT SYS004,.....
// ASSGN SYS004,...
// DLBL UOUT,'OBJMAINT.OUTPUT',0 *-- Output from strip operation
// EXTENT SYS005,.....
// ASSGN SYS005,..
// EXEC OBJMAINT
./ LIST PARM=JOB
./ BLOCK BLKSIZE=80
./ COPY
/*
// DLBL IJSYSIN,'OBJMAINT.OUTPUT',0 *-- Input to Translator
// EXTENT SYSIPT,.....
// ASSGN SYSIPT,..
To run your application program on another DB2 Server for VSE & VM database manager, you can simply distribute its load module and the DB2 Server for VSE & VM package. (You do not have to distribute the source code and then preprocess and compile it on the other system). Reload the package to all application servers that your package accesses, and send the load module to all DB2 Server for VSE & VM application requesters that your program accesses. You can unload the package to be distributed from the application server into a file, and subsequently reload the file into the new application server. Only the owner of the package or the database administrator can unload or reload the package.
If the package is distributed among application servers that are at different release levels of the system, a run-time error occurs if the package uses a feature that is not available on the application server on which the package was reloaded. To ensure that the load module and the package that you are distributing are meant to be used together, use the preprocessor parameter CTOKEN to place the same consistency token in both the load module and the package. Refer to Preprocessing the Program. If the two tokens do not match, the application server stops the program from running. For information on distributing packages on both like and unlike systems, refer to the DB2 Server for VSE & VM Database Services Utility manual.
If your CICS/VSE application is to run at other DB2 Family application servers, do the following:
For more information on CBND, see Creating a Package Using CBND.
If a bind file is generated after processing, it can be used to create a package in a remote or local application server. This enables the CICS online application program to access a remote DRDA server. To convert the SQL statements in a bind file into a package,
use the CBND CICS transaction. CBND can be used to bind all applications whose bind file was generated by the preprocessor to a remote or local server. To create a package locally, for a FORTRAN application, you still need to run the batch preprocessor. Executing the preprocessor with the BIND option and executing CBND are complementary. The preprocessor creates and stores the bind file in a master or private VSAM file and CBND reads the bind file back into an application server.
If using the CBND command, you must be either the owner of the program whose bind file you are binding to a remote server or a database administrator.
A second level transaction, CB2D, is required for CBND to complete the bind process. The CB2D transaction is invoked internally by CBND through an EXEC CICS START command. One or more CB2D transactions can be started by one CBND transaction based on the number of application servers specified in the CBND DBLIST input parameter. Each CB2D is responsible for connecting to a target database and creating a package. This transaction needs to be defined during installation to fully enable the CBND function.
The CBND transaction has 13 parameters:
>>-CBND----PACKAGE(-+----------------+--+------------+--+---+--->
'-collection_id.-' '-package_id-' '-)-'
>-----+---------------------------------+----------------------->
'- INfile--(--private_file_id--)--'
>-----+--------------------------------------------------------+-><
| .---------------------------------------------------. |
| V | |
+----+-+-NEW-----------------+----------------------+--+-+
| | '-REPLACE--+--------+-' | |
| | +-KEEP---+ | |
| | '-REVOKE-' | |
| +-OWner--(--authorization_name----)------------+ |
| +-QUALifier--(--collection_id----)-------------+ |
| +-+-NOCHECK-+----------------------------------+ |
| | +-CHECK---+ | |
| | '-ERROR---' | |
| | .-,--------------. | |
| | V | | |
| +-DBList--(-----server_name---+---)------------+ |
| +-USERid--(--authorization_name/password----)--+ |
| '-MSGQueue--(--name----)-----------------------' |
'-QRY----------------------------------------------------'
|
Figure 54. CBND Transaction Parameters
| Parameter | Description |
|---|---|
| PACKAGE (positional parameter 1) | This parameter identifies the package to be created and the associated
bind file. The associated bind file must be created by the DB2 Server
for VSE preprocessor and its contents must not be changed in any way.
collection_id.package_id is the name by which the database
manager identifies the package to be created and the associated bind
file. The collection_id portion is optional, and fully
qualifies the package_id and any unqualified objects referenced
within the package.
If the collection_id is not specified, and the user_id is, the collection_id defaults to the user_id. If neither is specified, the collection_id defaults to the connected authorization-id. You must be the owner of the bind file that you want to bind. To bind another user's bind file, you must have DBA authority. |
| REPLACE | This parameter is specified if an existing package is to be replaced by
the bind. If the package does not exist, a new package is created
without an error or warning message.
KEEP causes the existing grants of RUN privilege to remain in effect when the package is bound. However, if the owner of the package is not entitled to grant all privileges embodied in the package, all existing grants of the RUN privilege are revoked. The KEEP and REVOKE parameters apply if the package has previously been created and the owner of the package has granted the RUN privilege on the resulting package to other users. The KEEP and REVOKE parameters are allowed only with REPLACE. If the REVOKE parameter is specified, all existing grants of the RUN privilege are revoked. The KEEP and REVOKE parameters are allowed only with REPLACE. |
| NEW | The NEW parameter is specified if the package to be created does not exist and is to be created. If the package with the same name and owner already exists in the remote application server, CBND fails. |
| OWner | This parameter specifies the authorization_name of the owner of the package being created. The OWner parameter is to be used when you are binding against a remote application server. However, if you specify this parameter when binding against a local DB2 Server for VSE & VM application server, the authorization_name must be the same as the application server authorization ID. |
| QUALifier | This parameter specifies the default collection_id within the
package to resolve unqualified object names in static SQL statements.
The QUALifier parameter is meant to be used when you are binding against a remote application server. If you specify this parameter when binding against a DB2 Server for VSE & VM application server, the collection_id must be the same as the application server authorization ID. |
| NOCHECK | This parameter is specified if you want the application server to check all SQL statements for validity and perform package functions. It will generate a package if no statement-parsing error was found; If you specify the NOCHECK parameter, it overrides the ERROR parameter in the bind file |
| CHECK | This parameter is specified if you want the application server to check all SQL statements for validity and generates error messages if necessary, but does not generate a package; If you specify CHECK parameter, it overrides NOCHECK or ERROR parameter in the bind file. |
| ERROR | This parameter specifies how statement parsing errors are
tolerated. If the ERROR option is specified, then syntactic or semantic
errors detected at the application server side will not stop the creation of
the package. If the ERROR option is not specified in both CBND and the
bind file, the application server will not create the package when those
errors occur.
With the ERROR option, a syntactic error will cause the DB2 for VSE & VM database to generate an Error Section in the package. At run-time, invocation of this statement will yield SQLCODE -525 With the ERROR option, the creation of a package fails only if there was a DRDA protocol error, or a severe error detected on the AS side. |
| QRY | This parameter causes CBND to display the preprocessor options stored in
the header of the bind file. The preprocessor options will be displayed
at the terminal where CBND was invoked. MSGQueue is ignored if QRY is
specified. No package functions will be performed if QRY is
specified.
An example of displayed output is as follows: ARI5418I - THE BIND OPTIONS CURRENTLY IN EFFECT FOR
- PACKAGE SQLDBA.MYPROG ARE:
- NOCHECK
- KEEP
- BLOCK
- ISQL(CS)
- EXPLAIN(NO)
- APPLICATION SERVER DEFAULT DATE
- APPLICATION SERVER DEFAULT TIME
- NOEXIST
- REPLACE
- APOST
- CTOKEN(NO)
- CCSIDS(500)
- CCSIDM(0)
- CCSIDG(0)
- APPLICATION SERVER DEFAULT CHARSUB
- DEFAULT PACKAGE LABEL
|
| INfile | This parameter identifies the 7-character VSAM file name defined to CICS
through FCT or RDO (CICS/ESA R410) which contains the bind file to be loaded
into the database.
If this parameter is omitted, the bind file is assumed to reside in the master VSAM file named SQLBIND. SQLBIND is defined to CICS during installation, it is also used as the DLBL filename which identifies the bind file used for input. If your bind file resides in a private VSAM file, you will then specify the VSAM file name that matches this private VSAM file. To do this, you must make sure that this VSAM file is properly defined to CICS. |
| DBList | This parameter specifies a list of application servers on which the bind
file will be bound.
If this parameter is omitted, the bind file is bound to the default application server. For more information on establishing a default application server, see the DB2 Server for VSE & VM Database Administration manual. |
| USERid | This parameter specifies the userid and password that CBND will use to
execute a CONNECT statement to gain access to each application server where
the package will be created.
If this parameter is omitted, CBND will connect implicitly to the application server where the package will be created. That is, the online resource adapter will establish the userid for this particular CBND transaction. For more information on how the userid is established in the case of an implicit connect, see the DB2 Server for VSE & VM Database Administration manual. |
| MSGQueue | This parameter specifies the name of the temporary storage queue to be used to store the bind error or warning message (if any). If this parameter is omitted, no error or warning message will be stored, CBND will just display a summary report of the bind process on the terminal where CBND was invoked. The summary report contains the bind options used for the bind process, host variables, declarations, and the result of the bind. The user can browse the message queue specified using CEBR when CBND completes. This queue is kept in main storage and is not recoverable. It stays until it is purged by CEBR or if CICS is recycled. The user must determine when they should delete queues that are no longer needed to prevent possible short on temporary storage situations. |
The preprocessor requires the job control statement DLBL SQLGLOB. In addition, when you want the preprocessor to generate a bind file, job control statements DLBL SQLBIND and DLBL BINDWKF are required. These DLBL statements must be provided in either the preprocess job control or the system standard label subarea. The DLBL SQLBIND indicates the VSAM file into which the preprocessor should place the output bind file. The BINDWKF indicates the work file into which the preprocessor should use when performing VSAM I/O against the bind file. The DLBL SQLGLOB contains the CHARNAME and DBCS options which are necessary for bind file creation. See Figure 55. As mentioned earlier, you can suppress SQLBIND output through CHECK and NOBIND parameters of the preprocessor.
Figure 55. DLBL Statements for SQLBIND and SQLGLOB VSAM file
// DLBL SQLBIND,'DB2.BIND.MASTER',,VSAM,CAT=catalog,DISP=(OLD,KEEP) // DLBL BINDWKF,'DB2.BIND.WORKF',,VSAM,CAT=catalog // DLBL SQLGLOB,'DB2.SQLGLOB.MASTER',,VSAM,CAT=catalog,DISP=(OLD,KEEP) |
A user can choose to store the bind file generated by the preprocessor in a master DB2 Server for VSE VSAM bind file, or in his or her private VSAM bind file.
If a user chose to have his application program's bind file stored in the master DB2 Server for VSE VSAM bind file, the user should specify the recommended VSAM dataset name "DB2.BIND.MASTER" on the DLBL SQLBIND job control statement. This master VSAM bind file is defined to the system when DB2 Server for VSE Version 7 Release 1 was installed. Therefore, the user does not need to define or set-up the file. However, if a different cluster name was used to define the master VSAM file, the user should then specify the corresponding dataset name used.
If a user chose to have his application program's bind file stored in a private VSAM bind file, the user must specify the name of his or her private VSAM bind file on the DLBL SQLBIND job control. The user must first define the private VSAM bind file, using the same VSAM characteristics as the master VSAM bind file. For more information on how to define the VSAM cluster for the private bind file, see the DB2 Server for VSE Program Directory.