Starting a SESAM/SQL UTM application

Connection module parameters

DBCON require various parameters in order to fulfill its functions. The DBH name and the configuration name are important connection module parameters. They assign the application program linked to the connection module to a DBH and a configuration. Beyond that, there are various other DBCON configuration parameters

Connection modules for UTM applications that work with an independent DBH (DBCON) are generally parameterized through the application program's configuration file (see section “The configuration file”).

The user enters the connection module parameters in the configuration file and assigns them before the application program linked with the connection module is started. The parameters are then transferred to the connection module in the course of the start procedure.

All parameters are DBCON parameters.

The connection module parameters that apply to UTM application are listed below in alphabetical order:

CCSN=ccs-name	Coded character set with which the user program works.
ccs-name:	Name of the coded character set as defined in BS2000 (system component XHCS) or *NONE if no coded character set is to be sepcified for the user program. Default: *NONE If a coded character set was specified for the database (CODE- TABLE ccs_name clause in the CREATE CATALOG or ALTER CATALOG statement), the CCS name of the database must match the CCS name of the user program when the user program accesses the database. User program accesses with CCSN=*NONE or accesses by user programs from SESAM/SQL < V5.0 are rejected with SQLSTATE. This check does not take place for the utility statements CREATE/ALTER CATALOG, CREATE/REFRESH REPLICATION and RECOVER CATALOG [SPACE]. If no CCSN was specified for the database, this check does not take place either.
CNF=k	Name of the configuration in which the application program is to operate
k	A..Z, 0..9, ? Default: ?
DIAG-DUMP=(diag)	Criterion for the generation of a diagnostic dump.
diag:	{SQLSTATE=state|STATUS=status} state: SQLSTATE with class and subclass (5 bytes);  status: CALL DML status with subnumber (4 bytes) SQLSTATE can be partially qualified by entering “***” for the  subclass. CALL DML status can be partially qualified by entering “**” for the  subnumber. The first time the relevant error message is issued (SQLSTATE or  CALL DML status), a user task dump will be output (see the  “ Database Operation” manual)
ISOL-LEVEL= level	Default value for the isolation level of SQL transactions. Only effective in SQL applications.
level:	{READ-UNCOMMITTED | READ-COMMITTED | REPEATABLE- READ | SERIALIZABLE} Default: SERIALIZABLE Valid for all transactions of the ESQL application program if the isolation level was not specified by the appropriate SQL statement in the program. This parameter is only evaluated by TIAM and UTM applications.
NAM=x	Name of the DBH with which the application program is to work
x:	A..Z, 0..9, ? Default: ?
NOTYPE	The message “SESAMxx not available ...” is suppressed
NOUNT	If a long-running search query was interrupted by SESAM/SQL, nostatus is reported to the CALL DML program unit. If neither UNT nor NOUNT is specified, then the default is NOUNT. This only refers to CALL DML statements.
NVT	The application can only run locally and it can only communicate with the DBH entered in the NAM parameter. This also applies when SESDCN is loaded.
PREFETCH-BUFFER=buffersize	Size in KB of the buffer used for the prefetch. Value range: 0 <= buffersize <= 4096 This parameter is only evaluated by TIAM and UTM applications.
PRIO-CHECK=t	Interval in seconds between two consecutive checks of the BS2000 task priority of the application program. 10 <= t <= 3600 Default: 300
PRIO-CHECK=OFF	The check of the BS2000 task priority of the application program will be deactivated following the first check.
PUF= p	Maximum message length of DCAM or UTM applications in bytes 1 <= p <= 64000 Default: 4096 A message may be: the request (statement) of an application program to a SESAM/SQL DBH the response of a SESAM/SQL DBH to the application program Since the length of SQL messages is difficult to estimate, we recommend you choose the value 64000 for p for applications with SQL statements.
TRACE,TYPE= type	Logging of the call or message trace is activated when the application program starts.
type:	{CALL|MSG|(CALL|MSG)}  [,OUTPUT={SYSOUT|SYSLST|(SYSOUT|SYSLST)}] Default for  output (OUTPUT): SYSLST Refer to the “ Database Operation” manual for further information on  call and message tracing.
TOTAL-APPL=a	Maximum number of SESAM/SQL user applications in the configuration (this only applies to applications that do not operate in distributed mode) 1 <= a <= 128 Default: 64
TOTAL-USERS=u	Maximum number of SESAM/SQL user in the configuration (this only applies to applications that do not operate in distributed mode) 1 <= u <= 16000 Default: 128
UNT	Status 16 is passed to the CALL DML program unit if a long-running search query was interrupted by SESAM/SQL. Only effective for CALL DML statements!
UTMVG={JA | YES}	A DB process is assigned to just one UTM conversation. System resources are allocated to a conversation and not to a user. They cannot be utilized by the next conversation. SESAM/SQL automatically releases the resources when a conversation is concluded.openUTM conversation stacking means that DB conversations can be stacked without restrictions. Calls to SESAM/SQL (SQL or CALL DML statements) are not allowed in the conversation exit.UTMVG=YES must be set if database calls are to be issued in the first part of a UTM sign-on conversation.
UTMVG={NEIN | NO}	A DB conversation can cover several UTM conversations. The system resources are allocated to a user and not to a conversation. Therefore DB conversations cannot be stacked. SQL resources are bound to a UTM conversation and are automatically released at the end of the conversation.  The CALL DML resources of a dialog conversation can be re-used in a subsequent dialog conversation. CALL DML calls are allowed in the conversation exits. SQL calls are never allowed in the conversation exit. Database calls are not allowed in the first part of a UTM sign-on conversation. If a further SESAM/SQL UTM conversation is opened, although the previous one is still open, openUTM will issue a corresponding error message. The default is UTMVG=NO.

Special start parameters can be specified in a CALL DML application program. In openUTM applications, they are restricted to UNT and NOUNT (see the “ CALL-DM Applications” manual); NAM, NOTYPE and TRACE are not allowed.

Application start parameters

AT load time, the UTM application requires start parameters for UTM, SESAM/SQL and, where appropriate, for the FHS formatting system.

The UTM start parameters are entered as follows:

[.UTM] START startparameter[,...]

The UTM start parameters are described in the openUTM “ Generating and Handling Applications” manual.

The SESAM/SQL start parameters are specified in the configuration file. If the configuration file is empty, default values are used to parameterize the connection module.

If the FHS formatting system is used the start parameters must be specified as follows:

.FHS startparameter

The syntax and the meaning of the start parameters are described in the “ FHS (BS2000)” manual.

Example: starting a UTM application with ESQL-COBOL

Before starting a UTM application with ESQL-COBOL program units, you must allocate the SESAM/SQL module library. We recommend you dynamically load the required runtime systems at the UTM application start time.

Add the following statements to the start procedure of the UTM applications:

/ADD-FILE-LINK LINK-NAME=SESAMOML, FILE-NAME= sesam-modlib	1.
.
.
/CONNECT-SESAM-CONFIGURATION TO-FILE= global-configuration-file, -
/ CONFIGURATION-LINK= link-name	2.
or
/ADD-FILE-LINK LINK-NAME=SESCONF,FILE-NAME= file-name	3.
/START-PROGRAM FROM-FILE=*MODULE(LIBRARY= userlib ,ELEMENT= element-name -	4.
/ ,RUN-MODE=ADVANCED -
/ (ALTERNATE-LIBRARIES =YES) -
/ )
.UTM utm-startparameters	5.
.FHS fhs-startparameters	6.
.UTM END	7.
.
.

 

1. Allocates the SESAM/SQL module library.

2. Allocates the configuration file.

3. Calls the DBL dynamic linking loader to start the UTM application.

4. Starts the UTM application

5. Specifies UTM start parameters. You will find a description of the individual start parameters in the openUTM “ Generating and Handling Applications” manual.

6. Specifies the start parameters for the FHS formatting system. You will find a description of the individual start parameters in the “ FHS (BS2000)”manual.

7. Terminates the entry of the UTM start parameters.