Specifying language-specific entry points

IMS™ gives control to an application program through an entry point. Use the correct format for coding entry statements in assembler language, C language, COBOL, Pascal, and PL/I.

Your entry point must refer to the program communication blocks (PCBs) in the order in which they are defined in the PSB.

IMS passes the PCB pointers to a PL/I program differently than it passes them to an assembler language, C language, COBOL, Java™, or Pascal program. In addition, Pascal requires that IMS pass an integer before passing the PCB pointers. IMS uses the LANG keyword or the PSBGEN statement of PSBGEN to determine the type of program to which it is passing control. Therefore, you must be sure that the language specified during PSBGEN is consistent with the language of the program.

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

When you code each DL/I call, you must provide the PCB you want to use for that call. For all IMS TM application programs, the list of PCBs the program can access is passed to the program at its entry point.

Assembler language

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 parameter list address before you overwrite the contents of register 1. 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

When IMS passes control to your program, it passes the addresses, in the form of pointers, for each of the PCBs your program uses. The usual argc and argv arguments are not available to a program 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. 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 received by your C language program when it is invoked. When your program is invoked by a system support services program such as IMS, 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 received by your C language program. The ims.h include file contains declarations for PCB masks.

You can finish program execution 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 alternately 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. For example, when using the system function, the argc and argv arguments can be used to pass information. The initial __pcblist is made available to the invoked program.

COBOL

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 the PCB-NAME-1 [,...,PCB-NAME-N]

On previous versions of IMS, the using keyword 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

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

The entry statement can be any valid PL/I name and 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;

CCETDLI and AIBTDLI interface considerations

The CCETDLI considerations 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 applications, you must specify env(IMS) and plist(IMS); these specifications enable the application to accept the PCB list of arguments. The CEETDLI function is defined in <leawi.h>; the CTDLI function is defined in <ims.h>.

The AIBTDLI considerations are:

When using the AIBTDLI interface for C/MVS™, COBOL, or PL/I language applications, the language run-time options for suppressing abend interception (that is, NOSPIE and NOSTAE) must be specified. However, for Language Environment®-conforming applications, 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 to accept the PCB list of arguments.