Initiate a CICS program.

 

call CICSInitiate (ECIPARMS)

ECIPARMS

The address of the CICS External Call Interface (ECI) parameter block.

Description

This function initiates a CICS program. A parameter block structure VARIABLE must be declared in the ESL program using structure variable declaration syntax; the parameter block structure DEFINITION is defined in the ESLCICS.INC include file. The parameter block contains information that identifies the CICS program that should be launched.

The calling ESL program must fill in four fields in the parameter block

•ProgramName,

•UserID,

•CommArea and

•CommAreaLength

before calling this function. The CommArea field must contain the address of the CICS data buffer that will contain the input to and output from the CICS program. This field must be filled in using the ESL ‘handle of’ syntax (which will retrieve the address of another structure that will be used as the CommArea). Since the only ESL variable type on which the handle of syntax is allowed is an ESL structure, the CommArea must always be a structure variable. The CommAreaLength field must be the exact same length and organization as the structure variable used for the CommArea.

The remaining fields within the parameter block may be filled as desired (consult the CICS Universal External Call Interface documentation), except that the following must be left blank:

•CallType

•WindowHandle

•MessagelD

•Qualified

The value returned by the function is a unique integer that identifies the ESLCICS program initiated by the call. The DLL will pass this integer along with the stimulus event when this program terminates. The ESL program may use this to identify the CICS program that has terminated, and must pass it as an argument to the second entry point in the DLL (CICSGetData, described next) to identify the program results you want.

Return Value

A return value of 0 indicates that an error occurred. The ESL program should always check the return value from this function.