Database Procedure Blocks

Writing Database Procedures › Coding Database Procedures › Database Procedure Blocks

Database Procedure Blocks

The following tables show the format of the database procedure blocks.

Procedure Control Block

This is the first block of information passed to both area and record procedures. It contains information that reflects the general conditions under which the database procedure is being invoked. Total length is 20 bytes.

Item	Usage	Length	Description
Entry Level	Alphanumeric	4 bytes	Level at which the procedure is invoked: REC or AREA
Entry Time	Alphanumeric	4 bytes	The time the procedure is invoked: BFOR, AFTR, or ERR
Major Code	Alphanumeric	2 bytes	Major DML code of the DML command for which the procedure is being invoked (that is, 12 for STORE, or 03 for FIND, and so forth)
IDBMSCOM Code	Binary	2 bytes	IDBMSCOM code of the DML command for which the procedure is being invoked (that is, 14 for FIND NEXT WITHIN SET, or 15 for FIND NEXT WITHIN AREA, and so forth)
Cancel Indicator	Binary	2 bytes	Zero indicates that the DML command should be performed; nonzero requests cancellation of the DML command. The initial value of zero can be reset by a BEFORE procedure.
Record Indicator	Binary	1 byte	Indicates whether record is present in the Record Occurrence Block 0 - record is not present 1 - record is present
Filler	Alphanumeric	1 byte	Reserved
User Item	Binary	4 bytes	For user storage, as needed (normally, an address); initialized to zero. This value is preserved across calls to the procedure.

Application Control Block

This is the second block of information passed to both area and record procedures. It contains information that reflects the status of the application program at procedure execution time. Total length is 236 bytes.

Item	Usage	Length	Description
Subschema Name	Alphanumeric	8 bytes	Name of subschema being used
Program Name	Alphanumeric	8 bytes	Name of application program
Error-Status Indicator	Alphanumeric	4 bytes	Major DML code (first two bytes) of the command for which the procedure is being invoked, and the minor error-status code (second two bytes)
Database Key	Binary	4 bytes	The database key that is current of run unit
Record Name	Alphanumeric	18 bytes	Name of record type that is current of run unit
Area Name	Alphanumeric	18 bytes	Name of area to which current of run unit is assigned
Filler	Alphanumeric	18 bytes	Reserved for future use
Error-Set Name	Alphanumeric	18 bytes	Name of error-set type, if applicable
Error-Record Name	Alphanumeric	18 bytes	Name of error-record type, if applicable
Error-Area Name	Alphanumeric	18 bytes	Name of error area, if applicable
IDBMSCOM Array	Alphanumeric	100 bytes	System IDBMSCOM array for passing function information
Direct Db-key	Binary	4 bytes	Item used by application program to specify a database key for storing a record in DIRECT storage mode

Application Program Information Block

This is the third block of information passed to both area and record procedures. It contains information (if any) passed between the application program and database procedure. Total length is determined by user.

Item	Usage	Length	Description
Application Program Information	DBA-defined	DBA-defined	Information passed from application program using a BIND PROCEDURE statement; if not used, this field must be defined as a 4-byte alphanumeric item

Area Control Block

This is the fourth block of information passed to area procedures. It contains information about the area for which the procedure is being invoked. Total length is 28 bytes.

Item	Usage	Length	Description
Area Name	Alphanumeric	18 bytes	Name of area for which DML command is being invoked
Filler	Alphanumeric	2 bytes
Low Page	Binary	4 bytes	Number of lowest page in area
High Page	Binary	4 bytes	Number of highest page in area

CA IDMS Statistics Block

This is the fifth block of information passed to area procedures. It contains runtime statistics for the application program (same statistics obtained by the DML command ACCEPT IDMS-STATISTICS). Total length is 100 bytes.

Item	Usage	Length	Description
Date	Alphanumeric	8 bytes	Today's date in the format mm/dd/yy
Time	Alphanumeric	8 bytes	The time of the last occurrence of BIND RUN-UNIT, FINISH, or run-unit abort; in the format hhmmsshh
Pages Read	Binary	4 bytes	Total pages read by application program
Pages Written	Binary	4 bytes	Total pages written by application program
Pages Requested	Binary	4 bytes	Total pages requested by application program
CALC Records	Binary	4 bytes	Total CALC records stored with no overflow
CALC Overflow	Binary	4 bytes	Total CALC records that overflowed
VIA Records	Binary	4 bytes	Total VIA records stored with no overflow
VIA Overflow	Binary	4 bytes	Total VIA records that overflowed from target page
Records Requested	Binary	4 bytes	Total number of records accessed by the DBMS
Records Current	Binary	4 bytes	Total number of records established as current of run unit
Calls to CA IDMS/DB	Binary	4 bytes	Total calls made for DBMS services
Fragments Stored	Binary	4 bytes	Total variable length record fragments
Records Relocated	Binary	4 bytes	Total records relocated
Locks Requested1	Binary	4 bytes	Total number of record locks requested
Select Locks Held2	Binary	4 bytes	Number of shared locks now held
Update Locks Held2	Binary	4 bytes	Number of exclusive locks now held
Run Unit Id2	Binary	4 bytes	LID: Local Identification number of transaction for journaling purposes; incremented by one and carried across central versions until the journal is reinitialized
Task Id2	Binary	4 bytes	Identification number of central version task; reinitialized for each central version run and incremented by 1, beginning at 2 (0 and 1 are reserved for system)
Local Identification2	Alphanumeric	8 bytes	Identification code of batch or TP program to facilitate location of dumps and elements in the central version log
Filler	Alphanumeric	8 bytes	Reserved

1. As a lock is released, this value is not decremented

2. Applies to central version only

Record Control Block

This is the fourth block of information passed to record procedures. It contains information regarding the record type for which the procedure is being invoked. Total length is 56 bytes.

Item	Usage	Length	Description
Record Name	Alphanumeric	18 bytes	Name of record type for which DML command is being invoked
Area Name	Alphanumeric	18 bytes	Name of area to which record is assigned
Record ID	Binary	2 bytes	Identification number of record type for which DML command is being invoked
Record Length	Binary	2 bytes	Length (data only), in bytes, of record
Control Length	Binary	2 bytes	Length (data only), in bytes, of record up to and including the last CALC or sort-control field
Maximum Length	Binary	2 bytes	Actual length of fixed-length record or maximum length of variable-length record, in bytes
Database Key	Binary	4 bytes	Database key of record
Low Page	Binary	4 bytes	Number of lowest page on which records of this type can exist
High Page	Binary	4 bytes	Number of highest page on which records of this type can exist

Record Occurrence Block

This is the fifth block of information passed to record procedures. It is used to pass the actual record occurrence for which the procedure is invoked. There are situations in which the record occurrence is not available to be passed to the procedure. Total length is defined in the record type's schema description.

Item	Usage	Length	Description
Record Occurrence	As defined in schema	As defined in schema	Actual record that is the target of the DML command

Whenever possible, the record occurrence for which the procedure is being invoked is passed, but under some conditions the DBMS may not have immediate access to this data. In all cases, the fifth parameter is passed to the procedure, but its validity is not guaranteed under all scenarios. The following table indicates the availability of the record occurrence block data relative to procedure call times:

DML Verb	Procedure Call Times BEFORE	Procedure Call Times AFTER	Procedure Call Times ON ERROR
CONNECT	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain
DISCONNECT	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain
ERASE	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain	Present if last good verb was an OBTAIN, STORE, or MODIFY for target record type, else uncertain
FIND	Unavailable unless access is CALC, then calckey fields are available	Available if FIND executed as part of OBTAIN else unavailable. If access is CALC, calckey fields are available	Unavailable unless access is CALC, then calckey fields are available
GET	Available if GET executed as part of an OBTAIN, else unavailable	Available	Available if GET executed as part of an OBTAIN, else uncertain
MODIFY	Available, contains data passed from user program	Available, contains data passed from user program	Available, contains data passed from user program
STORE	Available, contains data passed from user program	Available, contains data passed from user program	Available, contains data passed from user program