XCTL example

The example opposite uses the older GETMAIN macro to acquire memory outside the CSECT, but within the Address Space, which is populated with the information to be passed to the routine invoked by XCTL. (The more modern STORAGE macro would be preferred over GETMAIN, these days.)

XCTL restores all registers from 2 to 12 inclusive, so that their contents on entry to NEXTPGM is as they were on entry to UTILPGM, which ensures integrity when NEXTPGM ends.

Example of XCTL use

UTILPGM CSECT 0 BASR R12,0 USING *,R12 . . . . . . . . GETMAIN VU,A=PARMADDR,LA=PARMSIZE Obtain external memory L R1,PARMADDR R1 = parameter address MVC 0(L'P2,R1),P2 Populate the parameter field XCTL (2,12),EP=NEXTRTN . . . . . . . . P2 DC CL60'ADDRESS' Parameter for NEXTRTN PARMADDR DC AL4(*-*) PARMSIZE DC AL4(60)

NOTE on CICS/TS Programming

The macros discussed so far; LINK, LOAD, and XCTL, relate to z/OS Services and should not be confused with similarly named CICS/TS Application Programming Interface (API) commands described in the "CICS Transaction Server for z/OS Application Programming Reference" manual which describes LINK, LOAD and XCTL commands. Equally, when coding CICS programs, the z/OS macros must not be used.