You can invoke the Database Services Utility program from an assembler language, PL/I, C, or COBOL program by using the Database Services Utility entry point ARIDBS. (You cannot invoke the Database Services Utility from a FORTRAN program.)
DB2 Server for VSE
If the Database Services Utility program is link-edited with a user program, you must link-edit these modules in addition to those required for a normal DB2 Server for VSE application program:
ARISYSDD ARIDSQLA ARIDDFP
If you use an assembler language CDLOAD instruction in the calling program, you need not link-edit the above modules. (See the following section Using the Database Services Utility from an Assembler Program.)
You need not have an SQL CONNECT statement in the input control card file if the application that invokes the utility has already executed one. All authorization checking is based on the user ID supplied in the last CONNECT statement that was executed by the database manager.
ASSGN, TLBL, and DLBL commands required by the Database Services Utility must be present in the job control, and SIZE=AUTO must be specified on the EXEC command for the main program. The Database Services Utility processes all input control card file records from SYSIPT before returning control to the routine that invoked it.
DB2 Server for VM
The application program must be link-edited with ARIDBS, a member in the ARISQLLD LOADLIB, along with any other modules required for a normal DB2 Server for VM application program.
The application program can execute a CONNECT statement, supply a CONNECT statement in the Database Services Utility control file input, or take advantage of the implicit CONNECT support. All authorization checking is based on the connected user ID.
The FILEDEF commands for the Database Services Utility input control file, the output message file, and any input/output data files referenced by Database Services Utility commands must be executed before the utility is invoked. The utility processes all control file records from SYSIN before returning control to the program that invoked it.
Although the database manager can be run in 24-bit or 31-bit addressing mode, you must run the Database Services Utility in 24-bit mode.
In single user mode, if the database manager is being run in 31-bit mode, the addressing mode is switched to 24-bit mode before the Database Services Utility is started. When you call the Database Services Utility from an application program, the addressing mode is switched to 24-bit mode and the addressing mode of the application program is restored upon return. You must, however, ensure that any parameters passed by the application program to the Database Services Utility do not reside above the 16MB (MB equals 1,048,576 bytes) line.
See the DB2 Server for VSE System Administration or the DB2 Server for VM System Administration manuals for more information on addressing modes.
The Database Services Utility uses the following register content on entry:
When dynamically invoked, all registers except register 15 are restored by the Database Services Utility before to returning by way of register 14 to the invoking program. Register 15 contains the final return code from Database Services Utility processing.
DB2 Server for VM
You can invoke the Database Services Utility program from an assembler language program. You must include the Database Services Utility program in the load module with the invoking program and follow the register conventions described above. The format of the CALL to invoke the utility is:
CALL ARIDBS
DB2 Server for VSE
You can invoke the Database Services Utility program from an assembler program in either of the ways described in the CALL macro description contained in the VSE/Advanced Functions Macro Reference. If you include the Database Services Utility program in the load module with the invoking program, the format of the CALL statement is the same as in DB2 Server for VM.
If you do not include the Database Services Utility program in the load module with the invoking program, use the following sequence of instructions to invoke the Database Services Utility program:
CDLOAD ARIDBS LR 15,1 CALL (15)
When using the above sequence of instructions, do not specify SIZE=AUTO on the EXEC command for the main program.
You can invoke the Database Services Utility program from a C program. ARIDBS must be declared to the compiler as an external entry point. ARIDBS must also be defined as having OS linkage using #pragma linkage (ARIDBS, OS);. The format of the C CALL command is:
ARIDBS(CLTYPEID,PARMSTR);
where CLTYPEID and PARMSTR can be declared as:
static char CLTYPEID[7]="DBSU01 ";
struct{short int PARMLEN;
char PARMDATA [80];
}PARMSTR;
A main program written in COBOL can invoke the Database Services Utility program by using the linkage conventions described for calling assembler programs in the DOS Full American National Standard COBOL Compiler and Library, Version 3, Programmer's Guide. The Database Services Utility entry point name ARIDBS must be used in the COBOL CALL command used to invoke the Database Services Utility program. The format of the COBOL CALL command varies depending on whether the COBOL compiler was generated with single (') or double (") quotes as delineators:
CALL 'ARIDBS' USING CALLTYPEID PARMSTRING.
or
CALL "ARIDBS" USING CALLTYPEID PARMSTRING.
where CALLTYPEID and PARMSTRING can be declared as:
01 CALLTYPEID PIC X(6) VALUE'DBSU01'. 01 PARMSTRING. 49 PARMLEN PIC S9(4) COMP. 49 PARMDATA PIC X(80).
You can invoke the Database Services Utility program from a PL/I program by using the facilities of the IBM PL/I Optimizing Compiler Program Product. ARIDBS must be declared to the compiler as an external entry point with the ASSEMBLER and INTER options. The format of the PL/I CALL command is:
CALL ARIDBS(CLTYPEID,PARMSTR);
where CLTYPEID and PARMSTR can be declared as:
DCL 1 CLTYPEID CHAR(6) INIT('DBSU01');
DCL 1 PARMSTR,
2 PARMLEN BINARY FIXED(15),
2 PARMDATA CHAR(80);
The interface described in this section allows a calling program or EXEC (in VM) to pass Database Services Utility control parameters or a single SQL statement or both. These utility control parameters provide the caller with the means to:
The calling program or EXEC can also pass a single SQL statement to the Database Services Utility for immediate processing by means of the call parameter list. Only SQL statements currently supported by Database Services Utility processing can be supplied. If an invalid parameter or Database Services Utility command is passed in the parameter list, it is processed as an SQL statement, and an error occurs.
Figure 61 shows the control parameters that can be used when invoking the Database Services Utility.
LINEWIDTH(www) or LW(www)PROMPTS(NO) MESSAGES(SQLONLY) MESSAGES(NONE) FORMAT(CL) FORMAT(LO) PAGECTL(NO) ENDLUW(NO) ISOL(CS) ISOL(UR) |
This section lists and describes the Database Services Utility control parameters.
Notes:
The SET LINECOUNT command can override the default lines per page used by Database Services Utility processing.
| DB2 Server for VM Only |
|---|
|
A user-supplied FILEDEF command defining SYSPRINT to the terminal should specify RECFM F or RECFM FB. If RECFM F or RECFM FB is not specified, the first character of each Database Services Utility message file display line is truncated. The default FILEDEF SYSPRINT command issued by the SQLDBSU EXEC defines the Database Services Utility message file record without a printer control character. This default command is: FILEDEF SYSPRINT TERMINAL (RECFM F LRECL 120 |
Only the end of Database Services Utility COMMIT processing is suppressed by this control parameter. Other Database Services Utility COMMIT and ROLLBACK processing is not suppressed. However, when the ENDLUW(NO) control parameter is specified, and ERRORMODE CONTINUE is in effect, all Database Services Utility COMMIT and ROLLBACK processing is suppressed. In a VM system note that the SET ERRORMODE CONTINUE command is in effect when the Database Services Utility input control file is assigned to a terminal or a SET ERRORMODE CONTINUE command is processed. And, in a VSE system, the SET ERRORMODE CONTINUE command is in effect when a SET ERRORMODE CONTINUE command is processed.
| Note: | System-initiated COMMIT or ROLLBACK processing cannot be suppressed by any means. |
If an SQL statement is supplied by means of the call parameter list, the Database Services Utility does not read the (input) control file SYSIPT. Any SQL statement currently supported by Database Services Utility processing can be supplied. This includes all SQL statements except those restricted to use in SQL application programs. One or more of the utility control parameters may precede the SQL statement. Utility commands are not supported in the call parameter list.
If an invalid parameter or a Database Services Utility command is passed in the parameter list, it is processed as an SQL statement, causing an error.
When an SQL statement is supplied in the Database Services Utility parameter list and it is not preceded by the ENDLUW(NO) control parameter, Database Services Utility processing ends the logical unit of work after the command is processed. An SQL COMMIT statement is issued if the command is processed without errors. An SQL ROLLBACK statement is issued if a command error occurs.
If the ENDLUW(NO) control parameter precedes the SQL statement, the Database Services Utility issues neither an SQL COMMIT statement nor an SQL ROLLBACK statement after the SQL statement is processed.
Use control parameters in a calling program or an EXEC when you want to set up the Database Services Utility environment and execute all the commands from one file. Figure 62 shows a REXX EXEC that directs the output messages to the terminal, executes the Database Services Utility, and passes control parameters and an SQL statement to the utility. You do not need to define the input requirements because the SQL statement is in the EXEC.
Figure 62. Using the Database Services Utility Control Parameters in DB2 Server for VM
/* Example DBS Utility Control Parameters in REXX EXEC */ ADDRESS CMS 'FILEDEF ARISQLLD DISK ARISQLLD LOADLIB Q (NOCHANGE' 'FILEDEF SYSPRINT TERMINAL (NOCHANGE RECFM F LRECL 120' 'NUCXLOAD ARIDBS ARIDBS ARISQLLD' 'ARIDBS PROMPTS(NO) FORMAT(LO) ENDLUW(NO) SELECT * FROM DEPARTMENT' ADDRESS EXIT RC |
Database Services Utility control parameters or an SQL statement or both can be supplied using standard program (or in VM, EXEC interface) conventions.
| Note: | All system parameter string restrictions apply to Database Services Utility processing. These restrictions are not overridden by Database Services Utility parameter processing. |
There are two format conventions; they are:
Your EXEC or program must follow these register conventions:
Your EXEC or program Database Services Utility parameter address list is to
follow these conventions:
| Position (per Byte) | Contents |
|---|---|
| 1-4 | Address of command identifier (not checked) |
| 5-8 | Address of PARAMETERSTRING |
| 9-12 | Address of PARAMETERSTRINGEND+1 |
Database Services Utility processing determines whether startup parameters are identified by register 0 by interrogating the contents of register 0 on entry to the Database Services Utility. Register 0 parameter processing is not performed if any of the following conditions occurs:
| Note: | EXEC parameter string restrictions must also be considered. |
The parameter string format is:
| <optional control parameters> <optional SQL statement> |
Your program must follow these register conventions:
Your program Database Services Utility parameter address list must follow
these conventions:
| Position (per Byte) | Contents |
|---|---|
| 1-4 | Address of CALLTYPEID |
| 5-8 | Address of PARAMETERSTRING |
where:
The parameter string format is:
| LL | <optional control parameters> <optional SQL statement> |
where:
Database Services Utility processing determines if startup parameters are identified by register 1 by interrogating the contents of register 1 on entry to the Database Services Utility. Register 1 parameter processing is not performed if any of the following conditions occur:
Your program must follow these register conventions:
Your program Database Services Utility parameter address list must follow
these conventions:
| Position (per Byte) | Contents |
|---|---|
| 1-4 | Address of CALLTYPEID |
| 5-8 | Address of PARAMETERSTRING |
where:
The parameter string format is:
| LL | <optional control parameters> <optional SQL statement> |
where:
Database Services Utility processing determines if startup parameters are identified by register 1 by interrogating the contents of register 1 on entry to the Database Services Utility. Register 1 parameter processing is not performed if any of the following conditions occur:
The sample EXEC in Figure 63 invokes the Database Services Utility against the application server in multiple user mode. The example is written in the REXX language.
Figure 63. Sample REXX EXEC to Invoke the Database Services Utility
/* EXAMPLE DBS UTILITY REXX EXEC */ ARG PARMS ADDRESS CMS 'FILEDEF ARISQLLD DISK ARISQLLD LOADLIB Q (NOCHANGE' 'FILEDEF SYSPRINT TERMINAL (NOCHANGE RECFM F LRECL 120' 'FILEDEF SYSIN TERMINAL (NOCHANGE' 'NUCXLOAD ARIDBS ARIDBS ARISQLLD' 'ARIDBS MESSAGES(SQLONLY) FORMAT(CL)' PARMS ADDRESS EXIT RC |
The EXEC performs the following functions:
If you create the CMS file SQL EXEC fm (where fm is the file mode) containing the sample EXEC in Figure 63, SQL statements can then be run from the CMS command line. Some examples of running one sample EXEC are in Figure 64.
| Note: | DB2 Server for VM user machine must identify the database to be accessed by running the SQLINIT EXEC before running the sample EXEC or a similar EXEC. Also, the VM terminal logical line-editing symbols (character delete, line delete, line end, and escape) must not conflict with the SQL language operators used in the SQL statements entered in the CMS command line. |
Figure 64. CMS Command Line Entries to Run a Sample EXEC
Enter--> sql select creator,tname from system.sysaccess
(SELECT output will be displayed in column format)
Enter--> sql format(lo) select creator,tname from system.sysaccess
(SELECT output will be displayed in list format)
Enter--> sql
When prompted:
Enter--> select creator,tname from system.sysaccess
(SELECT output will be displayed in column format)
When prompted:
Enter--> exit or another SQL statement
|
The following is a general example of the way to link-edit and run a user-written program (VMUCALL) that invokes the Database Services Utility. In Figure 65 the example program is written in COBOL. The user program is run from a user library (USERLOAD LOADLIB A). This example assumes that the user program VMUCALL needs to be compiled first and that the VMUCALL TEXT A file does not exist.
A sample link-edit REXX EXEC is shown in Figure 66. The contents of the user link-edit control file (VMULINK TEXT A) are shown in Figure 67. Note that for the COBOL program, you must also link edit the TEXT file ARIPADR4. Figure 68 shows a sample REXX EXEC for running the user program with multiple user mode.
Figure 65. Sample COBOL Program Calling the Database Services Utility
***************************************************************
* Example COBOL Program Calling the Database Services Utility *
***************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. VMUCALL
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CALLTYPEID PIC X(6) VALUE 'DBSU01'.
01 PARMSTRING.
49 PARMLEN PIC S9(4) COMP VALUE 42.
49 PARMDATA PIC X(42) VALUE
'FORMAT(LO) SELECT * FROM SYSTEM.SYSOPTIONS'.
PROCEDURE DIVISION.
CALL 'ARIDBS' USING CALLTYPEID PARMSTRING.
FINIS.
STOP RUN.
|
Figure 66. Sample EXEC to Link-Edit a User Program with the Database Services Utility
/* Example REXX EXEC to Link-Edit a COBOL program with DBS Utility */ ADDRESS 'COMMAND' 'COBOL2 VMUCALL (APOST' 'FILEDEF SYSLIB DISK VSC2LTXT TXTLIB Y' 'FILEDEF ARISQLLD DISK ARISQLLD LOADLIB Q (RECFM U' 'FILEDEF VMUCALL DISK VMUCALL TEXT A (RECFM F LRECL 80' 'FILEDEF ARIRVSTC DISK ARIRVSTC TEXT Q (RECFM F LRECL 80' 'FILEDEF ARIPADR4 DISK ARIPADR4 TEXT Q (RECFM F LRECL 80' 'FILEDEF SYSLMOD DISK USERLOAD LOADLIB A (RECFM U' 'LKED VMULINK (LET RENT NAME VMUMOD LIST TERM PRINT' EXIT |
Figure 67. Sample User Link-Edit Control File
INCLUDE VMUCALL INCLUDE ARIRVSTC INCLUDE ARIPADR4 <---- For user COBOL program only INCLUDE ARISSQLD(ARIDBS) ENTRY VMUCALL
|
Figure 68. Sample EXEC to Run a User Program Link-Edited with the Database Services Utility
/* Example REXX EXEC to Run a User Program Calling DBS Utility */ ADDRESS 'COMMAND' 'FILEDEF USERLOAD DISK USERLOAD LOADLIB A' 'FILEDEF SYSIN TERMINAL (RECFM F LRECL 120' 'FILEDEF SYSPRINT TERMINAL (RECFM F LRECL 120' 'NUCXLOAD VMUMOD VMUMOD USERLOAD' 'VMUMOD' 'NUCXDROP VMUMOD' EXIT |
The following is a basic example of a user-written COBOL program and the job control statements that call Database Services Utility to run SQL statements:
Figure 69. Sample COBOL Program to Call the Database Services Utility
// JOB CONTROL TO RUN A USER PROGRAM THAT CALLS THE DBS UTILITY
// OPTION CATAL
PHASE COBDBSU,S
// EXEC IGYCRCTL
CBL TRUNC(BIN) APOST
*********************************************
* Example COBOL program calling Database Services Utility *
*********************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. COBDBSU
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CALLTYPEID PIC X(6) VALUE 'DBSU01'.
01 PARMSTRING.
02 PARMLEN PIC S9(4) COMP.
02 PARMDATA PIC X(80).
PROCEDURE DIVISION.
MOVE 49 TO PARMLEN.
MOVE 'ENDLUW(NO) CONNECT SQLDBA IDENTIFIED BY SQLDBAPW;'
TO PARMDATA.
CALL 'ARIDBS' USING CALLTYPEID PARMSTRING.
MOVE 32 TO PARMLEN.
MOVE 'SELECT * FROM SYSTEM.SYSOPTIONS;'
TO PARMDATA.
CALL 'ARIDBS' USING CALLTYPEID PARMSTRING.
FINIS.
STOP RUN.
/*
INCLUDE ARIPRDID
INCLUDE ARIPADR4
INCLUDE ARISYSDD
INCLUDE ARIDSQLA
INCLUDE ARIDDFP
INCLUDE ARITDSSD
// EXEC LNKEDT
// EXEC PGM=COBDBSU
/*
/&
|
The following are basic examples of user-written assembler language programs and the job control statements that invoke the Database Services Utility to run SQL statements. In DB2 Server for VSE these statements run with single user mode.
Figure 70. DB2 Server for VSE Sample Load-and-Invoke Assembler Program for the Database Services Utility
// JOB CONTROL FOR USER PROGRAM THAT CDLOADS AND RUNS THE DBS UTILITY
// OPTION CATAL
PHASE VSELOAD,S
// EXEC ASSEMBLY
VSELOAD CSECT
R0 EQU 0
R1 EQU 1
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
STM R14,R12,12(R13) STORE THE CALLER'S REGISTERS
BALR R12,0 ESTABLISH ADDRESSABILITY
USING *,R12 REGISTER 12 WILL BE BASE REGISTER
LA R15,SAVE GET ADDRESS OF MY SAVE AREA
ST R15,8(R13) STORE FORWARD SAVE AREA POINTER
ST R13,4(R15) STORE BACKWARD SAVE AREA POINTER
LR R13,R15 MAKE MY SAVE AREA CURRENT
CDLOAD ARIDBS DBS ADDRESS RETURNED IN R1
ST R1,DBSADDR SAVE DBS UTILITY ADDRESS
MVI PSTRINGT,C' ' CLEAR PARAMETER AREA
MVC PSTRINGT+1(L'PSTRINGT-1),PSTRINGT CLEAR PARAMETER AREA
MVC PSTRINGT(L'PARMDAT1),PARMDAT1 MOVE FIRST COMMAND
LA R0,L'PSTRINGT LOAD PARAMETER STRING LENGTH
STH R0,PSTRINGL SET PARAMETER STRING LENGTH
LA R1,PARMLIST LOAD PARAMETER LIST ADDRESS
L R15,DBSADDR LOAD DBS ADDRESS
BALR R14,R15 CALL THE DBS UTILITY
MVI PSTRINGT,C' ' CLEAR PARAMETER AREA
MVC PSTRINGT+1(L'PSTRINGT-1),PSTRINGT CLEAR PARAMETER AREA
MVC PSTRINGT(L'PARMDAT2),PARMDAT2 MOVE SECOND COMMAND
LA R1,PARMLIST LOAD PARAMETER LIST ADDRESS
L R15,DBSADDR LOAD DBS ADDRESS
BALR R14,R15 CALL THE DBS UTILITY
L R13,4(R13) GET ADDRESS OF CALLER'S SAVE AREA
L R14,12(R13) RESTORE CALLER'S R14
LM R0,R12,20(R13) RESTORE CALLER'S R0-R12
BR R14 RETURN. R15=DBS RETURN CODE
SAVE DS 18F
DBSADDR DS F DBS ADDRESS SAVE AREA
PARMLIST DS 0F PARAMETER LIST
DC A(CTYPEID) **ADDRESS OF CALL TYPE IDENTIFIER
DC A(PSTRING) **ADDRESS OF PARAMETER STRING
CTYPEID DC CL6'DBSU01'
PSTRING DS 0H PARAMETER LIST
PSTRINGL DS H ** PARAMETER AREA LENGTH
PSTRINGT DS CL250 ** PARAMETER AREA
PARMDAT1 DC C'CONNECT SQLDBS IDENTIFIED BY SQLDBAPW'
PARMDAT2 DC C'FORMAT(LO) SELECT * FROM SYSTEM.SYSOPTIONS'
END VSELOAD
/*
// EXEC LNKEDT
// EXEC ARISQLDS,SIZE=AUTO,PARM='SYSMODE=S,LOGMODE=N,PROGNAME=VSELOAD'
/*
/&
VMULOAD CSECT
R0 EQU 0
R1 EQU 1
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
STM R14,R12,12(R13) STORE THE CALLER'S REGISTERS
BALR R12,0 ESTABLISH ADDRESSABILITY
USING *,R12 REGISTER 12 WILL BE BASE REGISTER
LA R15,SAVE GET ADDRESS OF MY SAVE AREA
ST R15,8(R13) STORE FORWARD SAVE AREA POINTER
ST R13,4(R15) STORE BACKWARD SAVE AREA POINTER
LR R13,R15 MAKE MY SAVE AREA CURRENT
LOAD EP=ARIDBS DBS ADDRESS RETURNED IN R0
ST R0,DBSADDR SAVE DBS ADDRESS
MVI PSTRINGT,C' ' CLEAR PARAMETER AREA
MVC PSTRINGT+1(L'PSTRINGT-1),PSTRINGT CLEAR PARAMETER AREA
MVC PSTRINGT(L'PARMDATA),PARMDATA SET PARAMETER
LA R0,L'PSTRINGT LOAD PARAMETER STRING LENGTH
STH R0,PSTRINGL SET PARAMETER STRING LENGTH
SR R0,R0 CLEAR REGISTER 0 (R1=PARM ADDRESS)
LA R1,PARMLIST LOAD PARAMETER LIST ADDRESS
L R15,DBSADDR LOAD DBS ADDRESS
BALR R14,R15 CALL THE DBS UTILITY
L R13,4(R13) GET ADDRESS OF CALLER'S SAVE AREA
L R14,12(R13) RESTORE CALLER'S R14
LM R0,R12,20(R13) RESTORE CALLER'S R0-R12
BR R14 RETURN. R15=DBS RETURN CODE
SAVE DS 18F
DBSADDR DS F DBS ADDRESS SAVE AREA
PARMLIST DS 0F PARAMETER LIST
DC A(CTYPEID) **ADDRESS OF CALL TYPE IDENTIFIER
DC A(PSTRING) **ADDRESS OF PARAMETER STRING
CTYPEID DC CL6'DBSU01'
PSTRING DS 0H PARAMETER LIST
PSTRINGL DS H ** PARAMETER AREA LENGTH
PSTRINGT DS CL250 ** PARAMETER AREA
PARMDATA DC C'FORMAT(LO) SELECT * FROM SYSTEM.SYSOPTIONS'
END VMULOAD
|
Assuming that the DB2 Server for VM sample program is contained in the CMS file VMULOAD ASSEMBLE A, you can run the program with multiple user mode by entering the commands in Figure 72:
Figure 72. REXX EXEC to Run an Assembler Program That Loads the DBS Utility
/* Example Database Services Utility to Run an ASSEMBLER Program Calling */ /* DBS Utility */ ADDRESS 'COMMAND' 'GLOBAL MACLIB OSMACRO' 'GLOBAL LOADLIB ARISQLLD' <---- Identifies DB2 Server for VM load library 'ASSEMBLE VMULOAD' 'LOAD VMULOAD' 'FILEDEF SYSPRINT TERMINAL (RECFM F LRECL 120' 'START' EXIT |
| Note: | Before attempting to run the user program, identify the application server to be accessed by using the SQLINIT EXEC. |
The following are examples of user-written assembler language programs that invokes the Database Services Utility. In DB2 Server for VSE, the Utility is invoked by means of a CALL macro to process commands in a file defined as SYSIPT. The VSE job control statements to assemble, link-edit, and run the user program with single user mode are shown in the example. In DB2 Server for VM, the Utility in invoked, by means of a CALL macro to process commands in a file defined as SYSIN. All necessary CMS FILEDEF commands must be entered before this program is executed.
Figure 73. DB2 Server for VSE Sample Assembler Program to Call the Database Services Utility
// JOB CONTROL TO RUN A USER PROGRAM THAT CALLS THE DBS UTILITY
// OPTION CATAL
PHASE VSECALL,S
// EXEC ASSEMBLY
VSECALL CSECT
R0 EQU 0
R1 EQU 1
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
STM R14,R12,12(R13) STORE THE CALLER'S REGISTERS
BALR R12,0 ESTABLISH ADDRESSABILITY
USING *,R12 REGISTER 12 WILL BE BASE REGISTER
LA R15,SAVE GET ADDRESS OF MY SAVE AREA
ST R15,8(R13) STORE FORWARD SAVE AREA POINTER
ST R13,4(R15) STORE BACKWARD SAVE AREA POINTER
LR R13,R15 MAKE MY SAVE AREA CURRENT
LA R0,0 CLEAR REGISTER 0
LA R1,0 INDICATE NO PARAMETER LIST PASSED
CALL ARIDBS
L R13,4(R13) GET ADDRESS OF CALLER'S SAVE AREA
L R14,12(R13) RESTORE CALLER'S R14
LM R0,R12,20(R13) RESTORE CALLER'S R0-R12
BR R14 RETURN. R15=DBS RETURN CODE
SAVE DS 18F
END VSECALL
/*
INCLUDE ARISYSDD
INCLUDE ARIDSQLA
INCLUDE ARIDDFP
INCLUDE ARIPRDID
INCLUDE ARITDSSD
// EXEC LNKEDT
// EXEC ARISQLDS,SIZE=AUTO,PARM='SYSMODE=S,LOGMODE=N,PROGNAME=VSECALL'
/*
/&
|
Figure 74. DB2 Server for VM Sample Assembler Program to Call the Database Services Utility
VMUCALL CSECT
R0 EQU 0
R1 EQU 1
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
STM R14,R12,12(R13) STORE THE CALLER'S REGISTERS
BALR R12,0 ESTABLISH ADDRESSABILITY
USING *,R12 REGISTER 12 WILL BE BASE REGISTER
LA R15,SAVE GET ADDRESS OF MY SAVE AREA
ST R15,8(R13) STORE FORWARD SAVE AREA POINTER
ST R13,4(R15) STORE BACKWARD SAVE AREA POINTER
LR R13,R15 MAKE MY SAVE AREA CURRENT
LA R0,0 CLEAR REGISTER 0
LA R1,0 INDICATE NO PARAMETER LIST PASSED
CALL ARIDBS
L R13,4(R13) GET ADDRESS OF CALLER'S SAVE AREA
L R14,12(R13) RESTORE CALLER'S R14
LM R0,R12,20(R13) RESTORE CALLER'S R0-R12
BR R14 RETURN. R15=DBS RETURN CODE
SAVE DS 18F
END VMUCALL
|
With multiple user mode, the Database Services Utility runs as an application program in the user's virtual machine. It cannot run either in the CMS/DOS environment or in CMS subset with multiple user mode.
Use the SQLINIT EXEC to specify the default database that you want to access. For additional information on the SQLINIT EXEC, refer to the DB2 Server for VSE & VM Database Administration manual.
When the Database Services Utility is run with single user mode, the database manager is started by means of the SQLSTART EXEC, which is invoked by the SQLDBSU EXEC. The database manager then loads the Database Services Utility program and transfers control to the program ARIDBS. All startup and initialization parameters cannot be directly supplied by means of the SQLDBSU EXEC. The SQLDBSU EXEC parameters that can be supplied, however, and that are applicable only to running the utility with single user mode are: DBNAME, DCSSID, LOGMODE, and PARMID. These parameters are supplied to the SQLSTART EXEC by the SQLDBSU EXEC when the database manager is started. The SQLDBSU EXEC also supplies the initialization parameter, PROGNAME(ARIDBS), to direct the database manager to execute the Database Services Utility program ARIDBS. The IBM-supplied SQLSTART EXEC and the startup and initialization parameters are described in the DB2 Server for VM System Administration manual.
The sample commands shown below run the Database Services Utility with single user mode and with multiple user mode to perform the following functions:
The CMS file DBSU COMMANDS A contains the following Database Services Utility command input:
CONNECT SQLDBA IDENTIFIED BY SQLDBAPW; UNLOAD DBSPACE(PUBLIC.SAMPLE) OUTFILE(DASD1) RELOAD DBSPACE(PUBLIC.SAMPLE) PURGE INFILE(DASD1) |
To run the utility with single user mode, enter the following commands:
FILEDEF DASD1 DISK DBSUFILE DATA A4 (RECFM VBS BLOCK 2048 SQLDBSU DBNAME(SQLDBA) SYSIN(DBSU COMMANDS A) SYSPRINT(TERMINAL) |
To run the utility with multiple user mode, enter the following commands:
SQLINIT DBNAME(SQLDBA) FILEDEF DASD1 DISK DBSUFILE DATA A4 (RECFM VBS BLOCK 2048 SQLDBSU SYSIN(DBSU COMMANDS A) SYSPRINT(TERMINAL) |
The following syntax diagrams show the format for invoking the Database Services Utility with single or multiple user mode.
| Format:
Multiple User Mode Parameters >>-SQLDBSU------------------------------------------------------>
>-----+--------------------------------------------------------------+>
'-sysIN--(--+-Reader------------------------------------+---)--'
+-Terminal----------------------------------+
'-file_name--+----------------------------+-'
'-file_type--+------------+--'
'-file_mode--'
>-----+-----------------------------------------------------------------+>
'-sysPRint--(--+-Printer-----------------------------------+---)--'
+-Terminal----------------------------------+
'-file_name--+----------------------------+-'
'-file_type--+------------+--'
'-file_mode--'
>--------------------------------------------------------------><
|
| Multiple User Mode Examples:
SQLDBSU SYSIN(T) SYSPRINT(PR) SQLDBSU |
Notes:
The SQLINIT EXEC does not need to be run prior to each SQLDBSU command. You need only to run the SQLINIT EXEC when you want to establish access to a different application server, to vary the method of loading the multiple user mode support system routines, or to change other characteristics of the application requester.
An alternative method for connecting to another application server is to issue the CONNECT command. See CONNECT, for more information about using this command.
| Format:
Single User Mode Parameters >>-SQLDBSU------------------------------------------------------>
>-----+--------------------------------------------------------------+>
'-sysIN--(--+-Reader------------------------------------+---)--'
+-Terminal----------------------------------+
'-file_name--+----------------------------+-'
'-file_type--+------------+--'
'-file_mode--'
>-----+-----------------------------------------------------------------+>
'-sysPRint--(--+-Printer-----------------------------------+---)--'
+-Terminal----------------------------------+
'-file_name--+----------------------------+-'
'-file_type--+------------+--'
'-file_mode--'
>--------------------------------------------------------------><
>>-Dbname----(server_name)---+--------------------+------------->
'-dcssID--(dcss_id)--'
>-----+------------------------+---+----------------------+----><
'-LOGmode--(--+-A-+---)--' '-PARMID--(file_name)--'
+-L-+
+-N-+
'-Y-'
|
| Single User Mode Example: SQLDBSU IN(T) PR(DBSU LIST A) D(SQLDBA) ID(SUF1) LOG(Y) PARMID(SQL1) |
Notes:
The following is a description of the parameters for the Database Services Utility SQLDBSU EXEC.
If you supply this form of the SYSIN parameter, the SQLDBSU EXEC issues the following CMS FILEDEF command for the Database Services Utility control file:
FILEDEF SYSIN DISK file_name file_type file_mode . . .
(RECFM FB LRECL 80 BLOCK 800
FILEDEF SYSIN READER (RECFM F LRECL 80
FILEDEF SYSIN TERMINAL (RECFM F LRECL 80
Notes:
READ FILE file_name file_type file_mode
If you use the READ FILE command, it must be the first command after you issued the EXEC SQLDBSU command. It must not be preceded by any other commands.
FILEDEF SYSIN TERMINAL (RECFM F LRECL 80 LOWCASE
If you issue this FILEDEF command, all the Database Services Utility command and SQL statement keywords must be entered in uppercase.
If you specify this form of the SYSPRINT parameter, the SQLDBSU EXEC issues the following CMS FILEDEF command for the Database Services Utility message file:
FILEDEF SYSPRINT DISK file-name file-type file-mode . . .
(RECFM FBA LRECL 121 BLOCK 1210
| Note: | Position 1 of the Database Services Utility message file (ddname=SYSPRINT) print records contains American Standards Association (ASA) control characters. If the message file is a CMS file and is printed with the CMS PRINT command, the option CC should be specified in the CMS PRINT command. Refer to the VM/ESA: CMS Command Reference manual for a description of the CMS PRINT command. |
If you specify SYSPRINT (Printer), the SQLDBSU EXEC issues the following CMS FILEDEF command for the Database Services Utility message file:
FILEDEF SYSPRINT PRINTER (RECFM FA LRECL 121
If your specify SYSPRINT (Terminal), the SQLDBSU EXEC issues the following CMS FILEDEF command for the Database Services Utility message file:
FILEDEF SYSPRINT TERMINAL (RECFM F LRECL 120
| Note: | The Database Services Utility message file is also assigned to the terminal if the SYSPRINT parameter is not specified, and you did not issue a CMS FILEDEF command for the ddname=SYSPRINT before issuing the SQLDBSU EXEC. |
If you specify this parameter, the SQLSTART EXEC parameters DBNAME(server_name) are specified. The initialization parameters SYSMODE=S, and PROGNAME=ARIDBS are also supplied in the SQLSTART EXEC PARM parameter.
If you omit the DBNAME parameter, the Database Services Utility is run with multiple user mode.
If you specify this parameter, it is supplied to the SQLSTART EXEC. The SQLSTART EXEC then uses the database manager bootstrap routines with the specified dcss-id to load the database manager code.
If you omit this parameter, it is not supplied as an SQLSTART EXEC parameter.
A means maintain the logs and automatically archive the database.
L means maintain the logs and automatically archive the log when the specified level has been reached.
N means do not maintain the logs for recovery.
Y means maintain the logs.
If you specify this parameter, you must also specify the DBNAME parameter. It identifies the value to be used for the database initialization LOGMODE parameter when the database manager is started in single user mode.
If you omit this parameter and you specify the DBNAME parameter, the LOGMODE parameter is not supplied as an initialization parameter in the SQLSTART EXEC.
If you omit this parameter and you specify the DBNAME parameter, the PARMID parameter is not supplied as an initialization parameter in the SQLSTART EXEC.
For more information on the PARMID parameter, see the description of SQLSTART in the DB2 Server for VM System Administration manual.
Notes:
LINEND # LINEDEL OFF CHARDEL OFF ESCAPE 1/2
The SQLDBSU EXEC checks the current settings for these symbols and, if necessary, resets the symbols as described previously. If the symbols are reset, the original symbols are restored during the SQLDBSU EXEC termination processing. The symbols are not reset if SQLDBSU EXEC execution is abnormally terminated. Refer to the VM/ESA: CP Command and Utility Reference for a description of the TERMINAL command and the logical line-editing symbols.
If the Database Services Utility control parameter PAGECTL(NO) is specified, the minimum message file record length is 80. The record format should be fixed or fixed blocked (F or FB).
You can always reference all 80 positions of data records contained in the Database Services Utility control file as data field positions.
If you define DASD CMS files with variable-length spanned records for Database Services Utility command input/output, you must use the file mode number 4.
FILEDEF SYSIN TERMINAL (RECFM F LRECL 80
If you do not specify the SYSIN information in the EXEC parameters, but you define the Database Services Utility control file (ddname=SYSIN) with a CMS FILEDEF command before issuing the SQLDBSU command, the SQLDBSU EXEC uses the user-defined Database Services Utility control file. Specify a logical record length (LRECL) of 80 for a user-defined Database Services Utility control file.
FILEDEF SYSPRINT TERMINAL (RECFM F LRECL 120
If you define the Database Services Utility message file with a CMS FILEDEF command, the minimum logical record length (LRECL) is 81. If you specify the Database Services Utility control parameter as PAGECTL(NO), the minimum message file record length is 80.