Job variables for controlling requests and programs

SESAM/SQL allows job variables to be used in a DBH session to control requests and programs. The software product JV (BS2000) Job Variables must be installed for this purpose (see the “ JV (BS2000)” manual). If JV is not available, the creation and definition of job variables are refused without warning.

To indicate the readiness of the DBH for communication, you can use job variables to document the following statuses:

• the beginning of the DBH session

• the end of the DBH session

• errors during the DBH session

• current status of the DBH session

• WA-LOG and TA-LOG status

• creation of a replication.
  If the replication is located in a BS2000 user ID that is not the same as the DBH user ID, an attempt is made to create the job variable also in the replication ID or use a job variable already created under this name. SESAM/SQL can only create the job variable in the replication ID when the DBH user ID is entered as a co-owner for the job variable. If the job variable cannot be created in the replication ID, or if it is not created there, it is created in the DBH user ID.

The overview given below indicates the times at which the SESAM/SQL DBH sets the job variables.

The DBH always creates job variables as shared job variables (USER-ACCESS=*ALL-USERS). If other attributes are to be used, the job variables must be suitably set up manually by the database administrator beforehand.

Time	Job variable name	Job-variable contents
Between the start and end of the DBH session	SESAM.SESDBH.cn c means: configuration name (see "CONFIGURATION-NAME") n means: DBH name (see "DBH-NAME")	Date YYYY-MM-DD Time hh:mm:ss DBH-STARTED DBH_NORMAL_END| DBH_ABNORMAL_END| DBH_ENDED_WITH_WARNINGS TA-LOG ACTIVE | NOT ACTIVE System error: CC XX/YY/ZZ | IW xxx Termination: IW xx Message: yyyyyyy Where: CC XX/YY/ZZ: Consistency Check with number, weight and subnumber IW xxx: The interrupt weight yyyyyyyy: The message code (see the “ Messages” manual)
The first update in the DBH session, or when the session is ended correctly	SICHERUNGSINFORMATION.cn	Status of the files SESAMcn.TA-LOG1 SESAMcn.TA-LOG2 SESAMcn.WA-LOG SESLKcn.TA-LOG1 SESLKcn.TA-LOG2 SESLKcn.WA-LOG Status of the transaction management files: o.k. Restart UTM information
When creating a replication	user-id.SESAM. replication.NEXT-REPL-LOG	The oldest CATLOG and DALOG file required for the first REFRESH REPLICATION (see the “ Core manual”)

Table 6: Job variables

The job variable SESAM.SESDBH. cn does not contain “System error: IW xx” any more for STXIT events of class ABEND and TERM, rather it contains “Termination: IW xx” (xx: STXIT interrupt weight) because these STXIT events are not system errors. You will find the meanings of the STXIT interrupt weights in the manual “ Executive Macros” in the description of the STXIT macro. If an internal transaction restart (e.g. due to a logging bottleneck) cannot be executed and the session must be terminated, then the job variable SESAM.SESDBH. cn contains “Message: yyyyyyy” (yyyyyyy: message code) where the corresponding message contains the cause of the failed restart.

If necessary, you can use predefined macros to change names and explanatory texts in the job variables. The predefined macros are in the SEZTXT.ASS source file which is shipped as part of the SIPANY.SESAM-SQL.<ver>.SPEZ library.

The SEZTXT.ASS source file contains the following macros:

JOBV      name[,[len][,MONJV]]

This macro declares a job variable called name.

name len MONJV

The name of the job variable (maximum length: 54 characters) The length of the job-variable name's suffix This defines the job variable as a monitoring job variable. In this case the text is not stored until position 128 (i.e. after the system part) in the job variable.

TEXT       text

This macro generates contents in the form of a text for the job variable called name.

text	A text string consisting of any characters (C'...') or hexadecimal characters (X'...') and with a maximum length of 54 characters. Several text strings can refer to a single job variable.

INSRT       len

This macro generates an insert with a length of length for the job variable called name. As a result, a text of the specified length is subsequently inserted dynamically. The macro can be specified several times for a single job variable.

len       The length of the insert (maximum length: 256 characters)

You can change the name of the job variable in the JOBV macro, and you can change the name of the text string in the TEXT macro. The entries in the INSRT macro cannot be changed. Note that the total length of all texts and inserts for a job variable cannot be more than 256 characters. After each change, you have to assemble the source file and enter it in the SESAM/SQL module library under the module name SEZTXT.ASS. You will find the source module in the SESAM/SQL library with special elements.