State data access XPI functions

The state data access functions allow you to inquire on and set certain system data in the AP domain.

The INQ_APPLICATION_DATA call

The INQ_APPLICATION_DATA call enables you to inquire on application system data in the AP domain.

INQ_APPLICATION_DATA

  DFHAPIQX [CALL,]
     [CLEAR,]
     [IN,
     FUNCTION(INQ_APPLICATION_DATA),]
     [OUT,
     [ACEE(name4 | (Rn) | * ),]     [DSA(name4 | (Rn) | * ),]
     [EIB(name4 | (Rn) | * ),]
     [RSA(name4 | (Rn) | * ),]
     [SYSEIB(name4 | (Rn) | * ),]
     [TCTUA(name4 | (Rn) | * ),]
     [TCTUASIZE(name4 | * ),]
     [TWA(name4 | (Rn) | * ),]
     [TWASIZE(name4 | (Rn) | * ),]
     RESPONSE (name1 | * ),
     REASON (name1 | * )]

Start of changeThis command is threadsafe.End of change

ACEE(name4 | (Rn | * )
returns the address of the access control environment element (ACEE).
name4
The name of a fullword area that is to receive the address of the ACEE.
(Rn)
A register that is to receive the ACEE address.
*
The parameter list itself, in name APIQ_ACEE, is used to hold the address.
DSA(name4 | (Rn | * )
returns the head of the chain of dynamic storage used by application programs to make them reentrant (for example, for assembler programs, the DFHEISTG storage).
name4
The name of a 4-byte area that is to receive the address of the head of the dynamic storage chain.
(Rn)
A register that is to receive the DSA address.
*
The parameter list itself, in name APIQ_DSA, is used to hold the address.
EIB(name4 | (Rn) | *)
returns the address of the EXEC interface block (EIB) for the current task.
name4
The name of a fullword area that is to receive the address of the EIB.
(Rn)
A register that is to receive the address of the EIB.
*
The parameter list itself, in name APIQ_EIB, is used to hold the address.
RSA(name4 | (Rn | * )
returns the address of the register save area for the current task.
name4
The name of a fullword area that is to receive the address of the register save area.
(Rn)
A register that is to receive the address of the register save area.
*
The parameter list itself, name APIQ_RSA, is used to hold the address.
SYSEIB(name4 | (Rn) | *)
returns the address of the system EXEC interface block of the current task.
name4
The name of a fullword area that is to receive the address of the system EXEC interface block.
(Rn)
A register that is to receive the address of the system EXEC interface block.
*
The parameter list itself, name APIQ_SYSEIB, is used to hold the address.
TCTUA(name4 | (Rn) | *)
returns the address of the terminal control table user area (TCTUA) for the current task.
name4
The name of a fullword area that is to receive the address of the TCTUA.
(Rn)
A register that is to receive the address of the TCTUA.
*
The parameter list itself, name APIQ_TCTUA, is used to hold the address.
TCTUASIZE(name4 | (Rn) | *)
returns the length in bytes of the TCTUA for the current task.
name4
The name of a 4-byte area that is to receive the length in bytes of the TCTUA.
(Rn)
A register that is to receive the length of the TCTUA.
*
The parameter list itself, name APIQ_TCTUASIZE, is used to hold the length of the TCTUA.
TWA(name4 | (Rn) | *)
returns the address of the transaction work area.
name4
The name of a fullword area that is to receive the address of the TWA.
(Rn)
A register that is to receive the address of the TWA.
*
The parameter list itself, name APIQ_TWA, is used to hold the address of the TWA.
TWASIZE(name4 | (Rn) | *)
returns the length, in bytes, of the transaction work area (TWA).
name4
The name of a 4-byte area that is to receive the length, in bytes, of the TWA.
(Rn)
A register that is to receive the length of the TWA.
*
The parameter list itself, name APIQ_TWASIZE, is used to hold the length of the TWA.

RESPONSE and REASON values for INQ_APPLICATION_DATA:

RESPONSE REASON
OK None
EXCEPTION DPL_PROGRAM
NO_TRANSACTION_ENVIRONMENT
TRANSACTION_DOMAIN_ERROR
DISASTER ABEND
LOOP
INQ_FAILED
INVALID INVALID_FUNCTION
KERNERROR None
PURGED None

The INQUIRE_SYSTEM call

The INQUIRE_SYSTEM call gives you access to CICS® system data in the AP domain.

INQUIRE_SYSTEM

  DFHSAIQX [CALL,]
     [CLEAR,]
     [IN,
     FUNCTION(INQUIRE_SYSTEM),
     [GMMTEXT(name4),]]
     [OUT,
     [CICSREL(name4 | *),]
     [CICSSTATUS(ACTIVE | FINALQUIESCE |
                      FIRSTQUIESCE| INITIALIZING),]
     [CICSSYS(name1 | *),]
     [CICTSLEVEL(name6 | *),]
     [CWA(name4 | (Rn) | *),]
     [CWALENGTH(name2 | *),]
     [DATE(name4|*),]
     [DTRPRGRM(name8 | *),]
     [GMMLENGTH(name2 | *),]
     [GMMTRANID(name4 | *),]
     [INITSTATUS(FIRSTINIT | INITCOMPLETE | SECONDINIT |
                      THIRDINIT),]
     [JOBNAME(name8 | *),]
     [OPREL(name2 | *),]
     [OPSYS(name1 | *),]
     [OSLEVEL(name4 | *),]
     [PLTPI(name2 | *),]
     [SDTRAN(name4 | *),]
     [SECURITYMGR(EXTSECURITY | NOSECURITY),]
     [SHUTSTATUS(CONTROLSHUT | NOTSHUTDOWN | SHUTDOWN),]
     [STARTUP(COLDSTART | EMERGENCY | WARMSTART),]
     [STARTUPDATE(name4| *),]
     [TERMURM(name8 | *),]
     [TIMEOFDAY(name4| *),]
     [XRFSTATUS(NOXRF | PRIMARY | TAKEOVER),]
     RESPONSE (name1 | * ),
     REASON (name1 | * )]

Start of changeThis command is threadsafe.End of change

CICSREL(name4 | *)
returns the level number of the CICS code under which the CICS region is running.
name4
The name of a 4-byte location that is to receive the level number characters as hexadecimal values.
CICSSTATUS(ACTIVE|FINALQUIESE|FIRSTQUIESCE|INITIALIZING)
returns the status of the CICS region.
ACTIVE
The CICS region is active and ready to receive work.
FINALQUIESCE
The CICS region is shutting down, and is in the final stage of quiescing.
FIRSTQUIESCE
The CICS region is shutting down, and is in the first stage of quiescing.
INITIALIZING
The CICS region is initializing.
CICSSYS(name1 | *)
returns the operating system for which the running CICS has been built.
name1
The name of a 1-byte area that is to receive the hexadecimal character of the operating system. A value of "X" represents MVS/ESA.
CICSTSLEVEL(name6 | *)
returns the release of CICS Transaction Server under which CICS is running.
name6
The name of a 6-byte area that is to receive the release characters as hexadecimal values.
CWA(name4 | (Rn) | *)
returns the address of the common work area.
name4
The name of a 4-byte field that is to receive the address of the CWA.
(Rn)
A register to receive the address of the CWA.
CWALENGTH(name2 | *)
returns the length in bytes of the CWA.
name2
The name of a 2-byte field that is to receive the length of the CWA.
DATE(name4 | *)
returns today’s date in packed-decimal form--4-bytes 0Cyyddds, where:
name4
The name of a 4-byte location that is to receive the date.
DTRPRGRM(name8 | *)
returns the name of the dynamic routing program.
name8
The name of an 8-byte area that is to receive the name of the dynamic routing program.
GMMLENGTH(name2 | *)
returns the length in bytes of the "good morning" message.
name2
The name of a 2-byte area that is to receive the length of the good morning message.
GMMTEXT(name4)
specifies the address of an area of storage, at least 244 bytes in length and owned by the caller, into which CICS is to return the good morning message.
name4
The address of an area of storage that is to receive the good morning message.
Note:
The GMMTEXT parameter must follow the IN statement as an input parameter.
GMMTRANID(name4 | *)
returns the transaction identifier of the CICS good morning transaction.
name4
The name of a 4-byte area that is to receive the CICS good morning transaction id.
INITSTATUS(FIRSTINIT|INITCOMPLETE|SECONDINIT|THIRDINIT)
returns a value indicating the stage reached during CICS initialization.
FIRSTINIT
The first stage of CICS initialization.
INITCOMPLETE
CICS initialization is complete.
SECONDINIT
The second stage of CICS initialization. This stage corresponds to the period when first phase PLTPI programs are run; that is those programs in a PLT that are defined before the DFHDELIM statement.
THIRDINIT
The third stage of CICS initialization. This stage corresponds to the period when second phase PLTPI programs are run; that is those programs in a PLT that are defined after the DFHDELIM statement.
JOBNAME(name8 | *)
returns the 8-character MVS™ job name under which the CICS region is running.
name8
The name of a 8-byte area that is to receive the MVS job name.
OPREL(name2 | *)
returns the last 2 digits of the level number of the MVS element of OS/390®, under which the CICS region is running.
name2
The name of a 2-byte area that is to receive, as a half-word binary value, the level number of the MVS element of OS/390. For example, OS/390 Release 3 MVS is represented by 03.
Note:
This field is supported for compatibility purposes only. The information is derived from the last two numbers held in the MVS CVTPRODN field. For example, CVTPRODN holds SP5.2.2 for MVS/ESA SP Version 5 Release 2.2 (in which case OPREL returns 22), and SP6.0.3 for OS/390 Release 3. You are recommended to use the OSLEVEL field for the full version and release number of the OS/390 product.
OPSYS(name1 | *)
returns the type of operating system on which the CICS regions is running.
name1
The name of a 1-byte area that is to receive the hexadecimal character of the operating system on which CICS is running. A value of "X" represents MVS/ESA.
OSLEVEL(name4 | *)
is the version, release, and modification level of the OS/390 product on which CICS is running.
name1
The name of a 4-byte area that is to receive the version and release number of OS/390 on which CICS is running. A value of "0240" represents OS/390 Release 4.
PLTPI(name2 | *)
returns the suffix that identifies the program list table (PLT) containing the list of programs to be run during CICS initialization--the program list table post initialization (PLTPI) list.
name2
The name of a 2-byte area that is to receive the suffix.
SDTRAN(name4 | *)
returns the name of the "shutdown assist" transaction to be run at the beginning of normal or immediate shutdown. The shutdown assist transaction is described in topic The shutdown assist utility program, DFHCESD.
name4
The name of a 4-byte area to receive the name.
SECURITYMGR(EXTSECURITY|NOSECURITY)
returns a value indicating whether security is active.
EXTSECURITY
CICS is using an external security manager (for example, RACF®).
NOSECURITY
Security is not in use in the CICS region--SEC=NO is specified as a system initialization parameter.
SHUTSTATUS(CONTROLSHUT|NOTSHUTDOWN|SHUTDOWN)
returns the shutdown status of the CICS region.
CONTROLSHUT
CICS is performing a controlled shutdown; that is, a normal shutdown with a warm keypoint.
NOTSHUTDOWN
CICS is not in shutdown mode.
SHUTDOWN
CICS is performing an immediate shutdown.
STARTUP(COLDSTART|EMERGENCY|WARMSTART)
returns the type of startup the CICS region performed.
COLDSTART
CICS performed a cold start, either because this was explicitly specified on the system initialization parameter, or because CICS forced a cold start because of the state of the global catalog.
EMERGENCY
CICS performed an emergency restart because the previous run did not shut down normally with a warm keypoint.
WARMSTART
CICS performed a warm restart following the normal shutdown of the previous run.
STARTUPDATE(name4 | *)
returns the start-up-date of this CICS region, in packed decimal form (4-bytes 00yydddc where yy=years, ddd=days, c is the sign).
name4
The name of a 4-byte location that is to receive the startup date of this CICS system.
TERMURM(name8 | *)
returns the name of the autoinstall user program for terminals.
name8
The name of an 8-byte area that is to receive the name of the autoinstall user program for terminals.
TIMEOFDAY(name4 | *)
returns the current time-of-day in packed decimal form (4-bytes hhmmsstc where hh=hours, mm=minutes, ss=seconds, t=tenths of a second, and c is the sign).
name4
The name of a 4-byte location that is to receive the time.
XRFSTATUS(NOXRF|PRIMARY|TAKEOVER)
returns the XRF status of the CICS region.
NOXRF
CICS was started with the system initialization parameter XRF=NO specified. XRF is not active.
PRIMARY
The CICS region was started as an active CICS in an XRF environment.
TAKEOVER
The CICS region was started as an alternate CICS, with the START=STANDBY system initialization parameter.

RESPONSE and REASON values for INQUIRE_SYSTEM

RESPONSE REASON
OK None
INVALID INVALID_FUNCTION
EXCEPTION LENGTH_ERROR
UNKNOWN_DATA
DISASTER INQ_FAILED
PURGED None

The SET_SYSTEM call

The SET_SYSTEM call allows you to set CICS system data values in the AP domain.

SET_SYSTEM

  DFHSAIQX [CALL,]
     [CLEAR,]
     [IN,
     FUNCTION(SET_SYSTEM),
     [DTRPRGRM(name8 | string | 'string'),]
     [GMMLENGTH(name2 | (Rn) | expression),]
     [GMMTEXT(name8 | (Rn)),]]
     [OUT,
     RESPONSE (name1 | * ),
     REASON (name1 | * )]

Start of changeThis command is threadsafe.End of change

DTRPRGRM(name8 | string | 'string')
specifies the name of the dynamic routing program.
name8
The name of an 8-byte area that contains the name of the dynamic routing program.
string
A string of character, without intervening blanks, that defines the name of the dynamic routing program being set.
‘string’
A string of character without intervening blanks. If you want to document a name (label) in your program, use this form.
GMMLENGTH(name2 | (Rn))
specifies the length of the new "good morning" message supplied by the GMMTEXT parameter.
name2
The name of a 2-byte area that contains, as a half-word binary value, the length of the new good morning message.
(Rn)
A register that contains the length of the new good morning message.
GMMTEXT(name4 | (Rn))
specifies the new good morning message.
name4
The name of a 4-byte location that contains the address of a storage area (up to a maximum of 246 bytes long) that contains the good morning message.
(Rn)
A register that contains the address of a storage area (up to a maximum of 246 bytes long) that contains the good morning message.

RESPONSE and REASON values for SET_SYSTEM:

RESPONSE REASON
OK None
INVALID INVALID_FUNCTION
EXCEPTION AKP_SIZE_ERROR
NO_KEYPOINT
DISASTER SET_FAILED
PURGED None

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]