ADDRESS
Obtain access to CICS® storage areas.
Note for dynamic transaction routing: Using ADDRESS with CWA could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See Affinity for more information about transaction affinities.
Description
- The access control environment element (ACEE)
- The communication area available to the invoked program (COMMAREA)
- The common work area (CWA)
- The EXEC interface block (EIB)
- The terminal control table user area (TCTUA)
- The transaction work area (TWA)
In assembler language, no more than four options may be specified in one ADDRESS command.
Options
- ACEE(ptr-ref)
- returns
a pointer to the access control environment element, the control block
that is generated by an external security manager (ESM) when the user signs on. If the user
is not signed on, the address of the CICS DFLTUSER's
ACEE is returned. If an ACEE does not exist, CICS sets the pointer reference to the null
value, X'FF000000'.
For information on how to map the ACEE data area, see the mapping macro IHAACEE supplied in SYS1.MACLIB.
Note: Take care when addressing an ACEE in a server program invoked by a distributed program link. The ACEE address returned depends on the link security and may not be the same as the address of the user signed on at the local system. - COMMAREA(ptr-ref)
- returns
a pointer reference, set to the address of the communication area
(COMMAREA) available to the currently executing program. COMMAREA
is used to pass information between application programs. If the COMMAREA
does not exist, the pointer reference is set to the null value, X'FF000000'.
In C, you must use ADDRESS COMMAREA to get the address of the communication area, because this is not passed as an argument to a C main function.
- CWA(ptr-ref)
- returns a pointer reference, set to the address of the common work area (CWA). This area makes information available to applications running in a single CICS system. If a CWA does not exist, CICS sets the pointer reference to the null value, X'FF000000'.
- EIB(ptr-ref)
- returns
a pointer reference set to the address of the EXEC interface block
(EIB). You must use this option to get addressability to the EIB in
application routines other than the first invoked by CICS (where addressability to the EIB is provided
automatically). If the application program is translated with SYSEIB
in the XOPTS parameter list, this option returns the address of the
system EIB.
If TASKDATALOC(ANY) is defined on the transaction definition, the address of the data may be above or below the 16MB line.
If TASKDATALOC(BELOW) is defined on the transaction definition, and the data resides above the 16MB line, the data is copied below the 16MB line, and the address of this copy is returned.
C functions must use ADDRESS EIB to get the address of the EXEC interface block, because this address is not passed as an argument to a C main function. You must code an ADDRESS EIB statement at the beginning of each application if you want access to the EIB, or if you are using a command that includes the RESP or RESP2 option.
- TCTUA(ptr-ref)
- returns a pointer
reference, set to the address of the terminal control table user area (TCTUA) for the principal
facility, not that for any alternate facility that may have been allocated. This area is used for
passing information between application programs, but only if the same terminal is associated with
the application programs involved. If a TCTUA does not exist, the pointer reference is set to the
null value, X'FF000000'.
If system initialization parameter TCTUALOC=ANY is specified, the address of the data can be above or below the 16MB line. Any program that uses the returned address must be link edited AMODE(31); otherwise, unpredictable results might occur.
If system initialization parameter TCTUALOC=BELOW is specified, the address returned references storage below the 16MB line.
- TWA(ptr-ref)
- returns
a pointer reference, set to the address of the transaction work area
(TWA). This area is used for passing information between application
programs, but only if they are in the same task. If a TWA does not
exist, the pointer reference is set to the null value, X'FF000000'.
If TASKDATALOC(ANY) is defined on the transaction definition, the address of the data may be above or below the 16MB line.
If TASKDATALOC(BELOW) is defined on the transaction definition, and the data resides above the 16MB line, the data is copied below the 16MB line, and the address of this copy is returned.