Language specific entry points

In your application program written in assembler language, C, COBOL, Pascal, or PL/I, control is passed from IMS through an entry point.

Your entry point must refer to the PCBs in the order in which they have been defined in the PSB. When you code each DL/I call, you must provide the PCB you want to use for that call. In all cases except CICS® online, the list of PCBs that the program can access is passed to the program at its entry point. For CICS online, you must first schedule a PSB as described in the topic "System Service Call: PCB" in IMS Version 15.2 Application Programming APIs.

Application interfaces that use the AIB structure (AIBTDLI or CEETDLI), such as Java™ application interfaces, use the PCB name rather than the PCB structure and do not require the PCB list to be passed at entry to the application.

In a CICS online program, you do not obtain the address of the PCBs through an entry statement, but through the user interface block (UIB).

Leave the value blank if the application has been enabled for the IBM® Language Environment®® for z/OS® & VM.

Assembler language entry point

You can use any name for the entry statement to an assembler language DL/I program. When IMS passes control to the application program, register 1 contains the address of a variable-length fullword parameter list. Each word in the list contains the address of a PCB. Save the content of register 1 before you overwrite it. IMS sets the high-order byte of the last fullword in the list to X'80' to indicate the end of the list. Use standard z/OS linkage conventions with forward and backward chaining.

C language entry point

When IMS passes control to your program, it passes the addresses, in the form of pointers, for each of the PCBs that your program uses. The usual argc and argv arguments are not available to a program that is invoked by IMS. The IMS parameter list is made accessible by using the __pcblist macro. You can directly reference the PCBs by __pcblist[0], __pcblist[1], or you can define macros to give these more meaningful names. Note that I/O PCBs must be cast to get the proper type:

(IO_PCB_TYPE *)(__pcblist[0])

The entry statement for a C language program is the main statement.

#pragma runopts(env(IMS),plist(IMS))
#include <ims.h>
 
main()
{
⋮
}

The env option specifies the operating environment in which your C language program is to run. For example, if your C language program is invoked under IMS and uses IMS facilities, specify env(IMS). The plist option specifies the format of the invocation parameters that is received by your C language program when it is invoked. When your program is invoked by a system support services program, the format of the parameters passed to your main program must be converted into the C language format: argv, argc, and envp. To do this conversion, you must specify the format of the parameter list that is received by your C language program. The ims.h include file contains declarations for PCB masks.

You can finish in three ways:

End the main procedure without an explicit return statement.
Execute a return statement from main.
Execute an exit or an abort call from anywhere, or alternatively issue a longjmp back to main, and then do a normal return.

One C language program can pass control to another by using the system function. The normal rules for passing parameters apply; in this case, the argc and argv arguments can be used to pass information. The initial __pcblist is made available to the invoked program.

COBOL entry point

The procedure statement must refer to the I/O PCB first, then to any alternate PCB it uses, and finally to the DB PCBs it uses. The alternate PCBs and DB PCBs must be listed in the order in which they are defined in the PSB.

PROCEDURE DIVISION USING PCB-NAME-1 [,...,PCB-NAME-N]

In previous versions of IMS, USING might be coded on the entry statement to reference PCBs. However, IMS continues to accept such coding on the entry statement.

Recommendation: Use the procedure statement rather than the entry statement to reference the PCBs.

Pascal entry point

The entry point must be declared as a REENTRANT procedure. When IMS passes control to a Pascal procedure, the first address in the parameter list is reserved for Pascal's use, and the other addresses are the PCBs the program uses. The PCB types must be defined before this entry statement. The IMS interface routine PASTDLI must be declared with the GENERIC directive.

procedure ANYNAME(var SAVE: INTEGER;
                  var pcb1-name: pcb1-name-type[;
                  ...
                  var pcbn-name: pcbn-name-type]); REENTRANT;
procedure ANYNAME;
(* Any local declarations *)
  procedure PASTDLI; GENERIC;
begin
  (* Code for ANYNAME *)
end;

PL/I entry point

The entry statement must appear as the first executable statement in the program. When IMS passes control to your program, it passes the addresses of each of the PCBs your program uses in the form of pointers. When you code the entry statement, make sure you code the parameters of this statement as pointers to the PCBs, and not the PCB names.

anyname: PROCEDURE (pcb1_ptr [,..., pcbn_ptr]) OPTIONS (MAIN);
⋮
RETURN;

The entry statement can be any valid PL/I name.

CEETDLI, AIBTDLI, and AERTDLI interface considerations

The following considerations apply for CEETDLI, AIBTDLI, and AERTDLI.

The considerations for CEETDLI are:

For PL/I programs, the CEETDLI entry point is defined in the CEEIBMAW include file. Alternatively, you can declare it yourself, but it must be declared as an assembler language entry (DCL CEETDLI OPTIONS(ASM);).
For C language application programs, you must specify env(IMS) and plist(IMS); these specifications enable the application program to accept the PCB list of arguments. The CEETDLI function is defined in <leawi.h>; the CTDLI function is defined in <ims.h>.

The considerations for AIBTDLI are:

When using the AIBTDLI interface for C/MVS, Enterprise COBOL, or PL/I language application programs, the language run-time options for suppressing abend interception (that is, NOSPIE and NOSTAE) must be specified. However, for Language Environment-conforming application programs, the NOSPIE and NOSTAE restriction is removed.
The AIBTDLI entry point for PL/I programs must be declared as an assembler language entry (DCL AIBTDLI OPTIONS(ASM);).
For C language applications, you must specify env(IMS) and plist(IMS); these specifications enable the application program to accept the PCB list of arguments.

The considerations for AERTDLI are:

When using the AERTDLI interface for C/MVS, COBOL, or PL/I language application programs, the language run-time options for suppressing abend interception (that is, NOSPIE and NOSTAE) must be specified. However, for Language Environment-conforming application programs, the NOSPIE and NOSTAE restriction is removed.
The AERTDLI entry point for PL/I programs must be declared as an assembler language entry (DCL AERTDLI OPTIONS(ASM);).
For C language applications, you must specify env(IMS) and plis(IMS). These specifications enable the application program to accept the PCB list of arguments.
AERTDLI must receive control with 31 bit addressability.