INIT call

The Initialize (INIT) call allows an application to receive status codes regarding deadlock occurrences and data availability (by checking each DB PCB).

For GSAM databases, you can use the Initialize (INIT) call to tell IMS that the program can accept a 12-byte record search argument (RSA) when retrieving a record for a large format data set.

Format

Call Name	DB/DC	DBCTL	DCCTL	DB Batch	TM Batch
INIT	X	X	X	X	X

Parameters

i/o pcb

Specifies the I/O PCB for the call. INIT must refer to the I/O PCB. This parameter is an input and output parameter.

aib

Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:

AIBID: Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN: AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1: Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCBbbb.
AIBOALEN: I/O area length. This field must contain the length of the I/O area specified in the call list.

i/o area

Specifies the I/O area in your program that contains the character string or strings indicating which INIT functions are requested. This parameter is an input parameter.

The functions that you can specify include:

DBQUERY
RSA12
STATUS GROUPA
STATUS GROUPB
VERSION

Usage

You can use the call in any application program, including IMS batch in a sharing environment.

Specify the function in your application program with a character string in the I/O area.

For example, use the format LLZZ Character-String, where LL is the length of the character string including the length of the LLZZ portion; ZZ must be binary 0. For PL/I, you must define the LL field as a fullword; the value is the length of the character string including the length of the LLZZ portion, minus 2. If the I/O area is invalid, an AJ status code is returned. The following tables contain sample I/O areas for INIT when it is used with assembler language, COBOL, C language, Pascal, and PL/I.

Determining database availability: INIT DBQUERY

When the INIT call is issued with the DBQUERY character string in the I/O area, the application program can obtain information regarding the availability of data for each PCB.

Application programs that use the language-independent AIB interface or the language-specific interfaces for the assembler, COBOL, C, or Pascal programming languages use a 2-byte LL field to specify the length of the I/O area. The following table shows an example of the INIT call I/O area with the LLZZ length field and DBQUERY specified.

Table 1. INIT DBQUERY example for the AIB, ASMTDLI, CBLTDLI, CTDLI, and PASTDLI interfaces
L	L	Z	Z	Character String
00	0B	00	00	DBQUERY
Note: The LL value of X'0B' is a hexadecimal representation of decimal 11. ZZ fields are binary.

The following table contains a sample I/O area for the INIT call with DBQUERY for PL/I. The PLITDLI interface uses a 4-byte LLLL field for the length of the I/O area.

Table 2. INIT DBQUERY: I/O area example for PLITDLI
L	L	L	L	Z	Z	Character String
00	00	00	0B	00	00	DBQUERY
Note: The LL value of X'0B' is a hexadecimal representation of decimal 11. ZZ fields are binary.

LL or LLLL: A 2-byte field that contains the length of the character string, plus two bytes for LL. For the PLITDLI interface, use the 4-byte field LLLL. When you use the AIB interface (AIBTDLI), PL/I programs require only a 2-byte field.
ZZ: A 2-byte field of binary zeros.

One of the following status codes is returned for each database PCB:

NA: At least one of the databases that can be accessed using this PCB is not available. A call made using this PCB probably results in a BA or BB status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not. An exception is when the database is not available because dynamic allocation failed. In this case, a call results in an AI (unable to open) status code.
In a DCCTL environment, the status code is always NA.
NU: At least one of the databases that can be updated using this PCB is unavailable for update. An ISRT, DLET, or REPL call using this PCB might result in a BA status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not. The database that caused the NU status code might be required only for delete processing. In that case, DLET calls fail, but ISRT and REPL calls succeed.
bb: The data that can be accessed with this PCB can be used for all functions that the PCB allows. DEDBs and MSDBs always have the bb status code.

In addition to data availability status, the name of the database organization of the root segment is returned in the segment name field of the PCB. The segment name field contains one of the following database organizations: DEDB, MSDB, GSAM, HDAM, PHDAM, HIDAM, PHIDAM, HISAM, HSAM, INDEX, SHSAM, or SHISAM.

For a DCCTL environment, the database organization is UNKNOWN.

Important: If you are working with a High Availability Large Database (HALDB), you need to be aware that the feedback on data availability at PSB schedule time only shows the availability of the HALDB master, not of the HALDB partitions. However, the error settings for data unavailability of a HALDB partition are the same as those of a non-HALDB database, namely status code 'BA' or pseudo abend U3303.

Automatic INIT DBQUERY

When the program is initially scheduled, the status code in the database PCBs is initialized as if the INIT DBQUERY call were issued. The application program can therefore determine database availability without issuing the INIT call.

Performance considerations for the INIT call (IMS online only)

For a DCCTL environment, the status code is NA.

For performance reasons, the INIT call should not be issued before the first GU call to the I/O PCB. If the INIT call is issued first, the GU call is not processed as efficiently.

Determining data availability status without abends

To avoid abendu3303, first use INIT STATUS GROUPx (x=A or B). IMS will give you a status code for unavailable databases (or HALDB partitions). Then, use INIT DBQUERY, which will set a status code in each DB PCB. Before attempting any DB call, you can test all PCBs for non-blank status.

Enabling data availability status codes: INIT STATUS GROUPA

The following table contains a sample I/O area for the INIT call for assembler language, COBOL, C language, and Pascal.

Table 3. INIT I/O area examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI
L	L	Z	Z	Character String
00	11	00	00	STATUS GROUPA
Note: The LL value of X'11' is a hexadecimal representation of decimal 17. ZZ fields are binary.

The following table contains a sample I/O area for the INIT call for PL/I.

Table 4. INIT I/O area examples for PLITDLI
L	L	L	L	Z	Z	Character String
00	00	00	11	00	00	STATUS GROUPA
Note: The LL value of X'11' is a hexadecimal representation of decimal 17. ZZ fields are binary.

LL or LLLL: LL is a halfword-length field. For non-PLITDLI calls, LLLL is a fullword-length field for PLITDLI.
ZZ: A 2-byte field of binary zeros.

The value for LLZZ data or LLLLZZ data is always 4 bytes (for LLZZ or LLLLZZ), plus data length.

Recommendation: You should be familiar with data availability.

When the INIT call is issued with the character string STATUS GROUPA in the I/O area, the application program informs IMS that it is prepared to accept status codes regarding data unavailability. IMS then returns a status code rather than a resultant pseudoabend if a subsequent call requires access to unavailable data. The status codes that are returned when IMS encounters unavailable data are BA and BB. Status codes BA and BB both indicate that the call could not be completed because it required access to data that was not available. DEDBs can receive the BA or BB status code.

In response to status code BA, the system backs out only the updates that were done for the current call before it encountered the unavailable data. If changes have been made by a previous call, the application must decide to commit or not commit to these changes. The state of the database is left as it was before the failing call was issued. If the call was a REPL or DLET call, the PCB position is unchanged. If the call is a Get type or ISRT call, the PCB position is unpredictable.

In response to status code BB, the system backs out all database updates that the program made since the last commit point and cancels all nonexpress messages that were sent since the last commit point. The PCB position for all PCBs is at the start of the database.

Enabling deadlock occurrence status codes: INIT STATUS GROUPB

The following table contains a sample I/O area for the INIT call for assembler language, COBOL, C language, and Pascal.

Table 5. INIT I/O area examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI
L	L	Z	Z	Character String
00	11	00	00	STATUS GROUPB
Note: The LL value of X'11' is a hexadecimal representation of decimal 17. ZZ fields are binary.

The following table contains a sample I/O area for the INIT call for PL/I.

Table 6. INIT I/O area examples for PLITDLI
L	L	L	L	Z	Z	Character String
00	00	00	11	00	00	STATUS GROUPB
Note: The LL value of X'11' is a hexadecimal representation of decimal 17. ZZ fields are binary.

LL or LLLL: LL is a halfword-length field. For non-PLITDLI calls, LLLL is a fullword-length field for PLITDLI.
ZZ: A 2-byte field of binary zeros.

The value for LLZZ data or LLLLZZ data is always four bytes (for LLZZ or LLLLZZ), plus data length.

When the INIT call is issued with the character string STATUS GROUPB in the I/O area, the application program informs IMS that it is prepared to accept status codes regarding data unavailability and deadlock occurrences. The status codes for data unavailability are BA and BB, as described under Enabling data availability status codes: INIT STATUS GROUPA.

When a deadlock occurs in batch and the INITSTATUS GROUPB call has been issued, the following occurs:

If no changes were made to the database, the BC status code is returned.
If updates were made to the database, and if a datalog exists and BKO=YES is specified, the BC status code is returned.
If changes were made to the database, and a disklog does not exist or BKO=YES is not specified, a 777 pseudoabend occurs.

When the application program encounters a deadlock occurrence, IMS:

Backs out all database resources (with the exception of GSAM and DB2®) to the last commit point. Although GSAM PCBs can be defined for pure batch or BMP environments, GSAM changes are not backed out. Database resources are backed out for DB2 only when IMS is the sync-point coordinator.
When you use INIT STATUS GROUPB in a pure batch environment, you must specify the DISKLOG and BACKOUT options.
Backs out all output messages to the last commit point.
Requeues all input messages as follows:

Environment

Action

MPP and BMP

All input messages are returned to the message queue. The application program no longer controls its input messages.

IFP

All input messages are returned to IMS Fast Path (IFP) balancing group queues (BALGRP), making them available to any other IFP region on the BALGRP. The IFP that is involved in the deadlock receives the next transaction or message that is available on the BALGRP.

DBCTL

Action is limited to resources that are managed by DBCTL, for example, database updates.
Returns a BC status code to the program in the database PCB.

Determining GSAM databases for large format data sets: INIT RSA12

When you issue the INIT call with the character string RSA12 set in the I/O area, the GSAM application program tells IMS that the program can accept a 12-byte RSA when retrieving a record for a large format data set. The following table contains a sample I/O area for the INIT call with RSA12 for assembler language, COBOL, C language, and Pascal.

Table 7. INIT RAS12: Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI
L	L	Z	Z	Character string
00	09	00	00	RSA12
Note: The LL value of X'09' is a hexadecimal representation of decimal 9. ZZ fields are binary.

The following table contains a sample I/O area for the INIT call with RSA12 for PL/I.

Table 8. INIT RSA12: Example for PLITDLI
L	L	L	L	Z	Z	Character string
00	00	00	09	00	00	RSA12
Note: The LL value of X'09' is a hexadecimal representation of decimal 9. ZZ fields are binary.

LL or LLLL: A 2-byte or 4-byte field that contains the total length of the I/O area. For PL/I, the length of the LLLL field is considered 2 bytes even though it is a 4-byte field. When you use the AIBTDLI interface, the length of the record is equal to the total length of LL + ZZ + character string. For the PLITDLI interface, the length of the record is equal to the total length of LLLL + ZZ + character string, where LLLL is considered 2 bytes.
ZZ: A 2-byte field of binary zeros.

Specify a database version number: INIT VERSION(dbname=version)

When database versioning is enabled, an application program can use the VERSION function to request a version of a database that is different from the version number that is specified for the application program on the PCB or from the default version that is returned by IMS. A version number specified on the INIT VERSION call takes precedence over all other version specifications and defaults.

When the INIT VERSION call is not issued prior to a DL/I to access a database, the version of the database that is returned to the application program is determined by the DBVER keyword of the PCB statement. If the DBVER keyword is not specified, IMS returns either the version of the database that is active in the ACB library or version 0 of the database, as determined by the DBLEVEL keyword in either the PSBGEN statement or the database section of the DFSDFxxx PROCLIB member.

In the I/O area, the VERSION function is specified by using the following format:

Each database name is specified by using alphabetic characters and can be specified only once. Specify only names of physical databases. The names of logical databases are not supported.

Each version is specified as a numeric value from 0 to 2147483647. The number that is specified must match a version number that is defined on a DBD for the named database and stored in the IMS catalog.

Calculate the size that is required for the I/O area by multiplying the number of databases that are specified in the input I/O area by 20.

For example, the following table contains a sample I/O area for the INIT VERSION call for assembler language, COBOL, C language, and Pascal. In the table, the LL value of X'3C' is the hexadecimal representation of decimal 60, the length in bytes that is required to hold the output in the I/O area when three database names are specified on input. The ZZ fields are binary.

Table 9. INIT VERSION: Example format for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI
L	L	Z	Z	Character string
00	3C	00	00	`VERSION (DBa=1,DBb=2,DBc=3)`

The following table contains a sample I/O area for the INIT call with VERSION for PL/I. In the table, the LL value of X'3C' is the hexadecimal representation of decimal 60. The ZZ fields are binary.

Table 10. INIT VERSION: Example format for PLITDLI
L	L	L	L	Z	Z	Character string
00	00	00	3C	00	00	`VERSION (DBa=1,DBb=2,DBc=3)`

LL or LLLL: A 2-byte or 4-byte field that contains the total length of the I/O area. For PL/I, the length of the LLLL field is considered 2 bytes even though it is a 4-byte field. When you use the AIBTDLI interface, the length of the record is equal to the total length of LL + ZZ + character string. For the PLITDLI interface, the length of the record is equal to the total length of LLLL + ZZ + required length for output, where LLLL is considered 2 bytes.
ZZ: A 2-byte field of binary zeros.
Character string: The function specification on input. The length that is specified in the LL or LLLL is the length that is required for the output: 20 bytes for each database that is specified in the input character string.

Restrictions

For function shipping in the CICS® environment, the local and remote CICS must both be DBCTL.

You should be familiar with deadlock occurrences as described in IMS Version 15.2 System Administration.