INIT call

An Initialize (INIT) call allows the application to receive data availability status codes by checking each DB PCB for data availability.

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, the first PCB address in the list passed to the program. This parameter is an input and output parameter.

aib

Specifies the address of the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.

The following 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 that is specified in the call list.

i/o area

Specifies the I/O area to be used for the call. This parameter is an input parameter. The I/O area of an INIT call can contain the character string DBQUERY or VERSION(dbname1=version,dbname2=version).

Usage

The INIT call is valid for all IMS TM application programs.

Performance considerations for the INIT call (IMS online only)

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

To specify the database query subfunction in your application program, specify the character string DBQUERY in the I/O area.

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. The following tables contain sample I/O areas for the INIT call with DBQUERY.

Table 1. INIT I/O area examples for all xxxTDLI interfaces except PLITDLI
L	L	Z	Z	Character String
00	0B	00	00	DBQUERY
Note: The LL and ZZ fields are binary. The LL value X'0B' is a hexadecimal representation of decimal 11.

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

LL or LLLL: A 2-byte field that contains the length of the character string, plus 2 bytes for LL. For the PLITDLI interface, use the 4-byte field LLLL. When you use the AIBTDLI interface, 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 pseudo-abend 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 the PCB allows. DEDBs and MSDBs always have the bb.

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. In DCCTL environments, the name of the database organization is UNKNOWN.

Automatic INIT DBQUERY

When the application program is entered initially, the status code in the database PCBs is initialized as if the INIT DBQUERY call was issued. This enables the application program to determine database availability without issuing the INIT call.

In DCCTL environments, the status code is NA.

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 3. 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 4. 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.