IMS Application Calls

The following list describes some of the calls that IMS application programs can use.

get unique (GU)

The GU (get unique) call retrieves a specific segment or path of segments from a database. At the same time, the GU call establishes a position in a database from which additional segments can be processed in a forward direction.

get next (GN)

The GN (get next) call retrieves the next segment or path of segments from the database. The get next call normally moves forward in the hierarchy of a database from the current position, but can be modified to start at an earlier position than the current position in the database through a command code. However, its normal function is to move forward from a given segment to the next required segment in a database.

get hold unique (GHU) and get hold next (GHN)

GHU (get hold unique) and GHN (get hold next) calls indicate the intent of the user to issue a subsequent delete or replace call. A GHU or GHN call must be issued to retrieve the segment before issuing a delete or replace call.

insert (ISRT)

The ISRT (insert) call inserts a segment or a path of segments into a database. It is used to initially load segments in databases and to add segments in existing databases.

To control where occurrences of a segment type are inserted into a database, the user normally defines a unique sequence field in each segment. When a unique sequence field is defined in a root segment type, the sequence field of each occurrence of the root segment type must contain a unique value (except for HDAM and PHDAM). When defined for a dependent segment type, the sequence field of each occurrence under a given physical parent usually contains a unique value. If no sequence field is defined, a new occurrence is inserted after the last existing one.

delete (DLET)

The DLET (delete) call deletes a segment from a database. When a segment is deleted from a DL/I database, its dependents, if any, are also deleted.

replace (REPL)

The REPL (replace) call replaces the data in the data portion of a segment or path of segments in a database. Sequence fields cannot be changed with a replace call.

system service calls

In addition to the calls described previously, which are used to manipulate the data, there are a number of system service calls provided to allow the application to make use of other facilities provided by IMS. These system service calls are described in Table 14-5 on page 237 and Table 14-6 on page 238.

Table 14-5. Summary of IMS DB Application System Service Calls

Function Code	Meaning and Use
APSB	Allocate PSB; allocates a PSB for an ODBA application program
CHKP (Basic)	Basic checkpoint; prepares for recovery
CHKP (Symbolic)	Symbolic checkpoint; prepares for recovery
GMSG	Get message; retrieves a message from the AO exit routine
ICMD	Issue command; issues an IMS command and retrieves the first command response segment
INIT	Initialize; application receives data availability and deadlock occurrence status codes
INQY	Inquiry; returns information and status codes about I/O or alternate PCB destination type, location, and session status
LOG[a]	Log; writes a message to the system log
PCB[a]	Specifies and schedules another PCB
RCMD	Retrieve command; retrieves the second and subsequent command response segments resulting from an ICMD call
ROLB	Roll back; eliminates database updates
ROLL	Roll; eliminates database updates; abend
ROLS	Roll back to SETS; backs out database changes to SETS points
SETS	Set synchronization point; establishes as many as nine intermediate sync (backout) points
SETU	SET unconditional
SYNC	Synchronization; releases locked resources
TERM	Terminate; releases a PSB so another can be scheduled; commits database changes
XRST	Extended restart; works with symbolic checkpoint to restart application program

^[a] indicates a blank. All calls must be four characters.

Table 14-6. Summary of IMS TM System Service Calls

Function Code	Meaning and Use
APSB	Allocate PSB; allocates a PSB for use in CPI-C driven application programs
CHKP (Basic)	Basic checkpoint; for recovery purposes
CHKP (Symbolic)	Symbolic checkpoint; for recovery purposes
DPSB	Deallocate PSB; frees a PSB in use by a CPI-C driven application program
GMSG	Get message; retrieves a message from the AO exit routine
ICMD	Issue command; issues an IMS command and retrieves the first command response segment
INIT	Initialize; application receives data availability status codes
INQY	Inquiry; retrieves information about output destinations, session status, execution environment, and the PCB address
LOG[a]	Log; writes a message to the system log
RCMD	Retrieve command; retrieves the second and subsequent command response segments resulting from an ICMD call
ROLB	Rollback; backs out messages sent by the application program
ROLL	Roll; backs out output messages and terminates the conversation
ROLS	Roll back to SETS; returns message queue positions to sync points set by the SETS or SETU call
SETS	Set synchronization point; sets intermediate sync (backout) points
SETU	SET unconditional; sets intermediate sync (backout) points
SYNC	Synchronization; requests commit point processing
XRST	Restart; works with symbolic CHKP to restart application program failure

^[a] indicates a blank. All calls must be four characters in length.

Definition:

Current position is where IMS starts its search for the segments that you specify in the calls. Before you issue the first call to the database, the current position is the place immediately before the first root segment occurrence in the database. This means that if you issue an unqualified GN call, IMS retrieves the first root segment occurrence. It is the next segment occurrence in the hierarchy that is defined by the DB PCB that you referenced.