Retrieve information about a terminal or session.
INQUIRE TERMINAL/NETNAME >>-INQUIRE TERMINAL(data-value)--+--------------------+-------->< '-NETNAME(data-area)-'
The following options apply to both the INQUIRE TERMINAL and the INQUIRE NETNAME command.
INQUIRE TERMINAL .---------------------------. V | >>---+-----------------------+-+--------------------------------> +-ACCESSMETHOD(cvda)----+ +-ACQSTATUS(cvda)-------+ +-ALTPAGEHT(data-area)--+ +-ALTPAGEWD(data-area)--+ +-ALTPRINTER(data-area)-+ +-ALTPRTCOPYST(cvda)----+ +-ALTSCRNHT(data-area)--+ +-ALTSCRNWD(data-area)--+ +-ALTSUFFIX(data-area)--+ +-APLKYBDST(cvda)-------+ +-APLTEXTST(cvda)-------+ +-ASCII(cvda)-----------+ +-ATISTATUS(cvda)-------+ +-AUDALARMST(cvda)------+ +-AUTOCONNECT(cvda)-----+ +-BACKTRANSST(cvda)-----+ +-COLORST(cvda)---------+ +-CONSOLE(data-area)----+ +-COPYST(cvda)----------+ +-CORRELID(data-area)---+ +-CREATESESS(cvda)------+ +-DATASTREAM(cvda)------+ +-DEFPAGEHT(data-area)--+ +-DEFPAGEWD(data-area)--+ +-DEFSCRNHT(data-area)--+ +-DEFSCRNWD(data-area)--+ +-DEVICE(cvda)----------+ +-DISCREQST(cvda)-------+ +-DUALCASEST(cvda)------+ +-EXITTRACING(cvda)-----+ +-EXTENDEDDSST(cvda)----+ +-FMHPARMST(cvda)-------+ +-FORMFEEDST(cvda)------+ +-GCHARS(data-area)-----+ +-GCODES(data-area)-----+ +-HFORMST(cvda)---------+ +-HILIGHTST(cvda)-------+ +-KATAKANAST(cvda)------+ +-LIGHTPENST(cvda)------+ +-LINKSYSTEM(data-area)-+ +-MAPNAME(data-area)----+ +-MAPSETNAME(data-area)-+ +-MODENAME(data-area)---+ +-MSRCONTROLST(cvda)----+ '-NATLANG(data-area)----' .-----------------------------. V | >----+-------------------------+-+----------------------------->< +-NATURE(cvda)------------+ +-NEXTTRANSID(data-area)--+ +-NQNAME(data-area)-------+ +-OBFORMATST(cvda)--------+ +-OBOPERIDST(cvda)--------+ +-OPERID(data-area)-------+ +-OUTLINEST(cvda)---------+ +-PAGEHT(data-area)-------+ +-PAGESTATUS(cvda)--------+ +-PAGEWD(data-area)-------+ +-PARTITIONSST(cvda)------+ +-PRINTADAPTST(cvda)------+ +-PRINTER(data-area)------+ +-PROGSYMBOLST(cvda)------+ +-PRTCOPYST(cvda)---------+ +-QUERYST(cvda)-----------+ +-RELREQST(cvda)----------+ +-REMOTENAME(data-area)---+ +-REMOTESYSNET(data-area)-+ +-REMOTESYSTEM(data-area)-+ +-SCRNHT(data-area)-------+ +-SCRNWD(data-area)-------+ +-SECURITY(cvda)----------+ +-SERVSTATUS(cvda)--------+ +-SESSIONTYPE(cvda)-------+ +-SIGNONSTATUS(cvda)------+ +-SOSIST(cvda)------------+ +-TASKID(data-area)-------+ +-TCAMCONTROL(data-area)--+ +-TERMMODEL(data-area)----+ +-TERMPRIORITY(data-area)-+ +-TERMSTATUS(cvda)--------+ +-TEXTKYBDST(cvda)--------+ +-TEXTPRINTST(cvda)-------+ +-TRACING(cvda)-----------+ +-TRANSACTION(data-area)--+ +-TTISTATUS(cvda)---------+ +-UCTRANST(cvda)----------+ +-USERAREA(ptr-ref)-------+ +-USERAREALEN(data-area)--+ +-USERID(data-area)-------+ +-USERNAME(data-area)-----+ +-VALIDATIONST(cvda)------+ +-VFORMST(cvda)-----------+ '-ZCPTRACING(cvda)--------'
Conditions: END, ILLOGIC, NOTAUTH, TERMIDERR
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
The INQUIRE TERMINAL and INQUIRE NETNAME commands both return information about a particular terminal or session installed in a CICS region.
You can use these commands to inquire about any type of terminal resource, including:
You can also use INQUIRE TERMINAL to inquire about an APPC, LUTYPE6.1, or MRO session or, where there are parallel sessions, session group. To get full details about the associated connection, however, you must use an INQUIRE CONNECTION command.
Some of the options in this command return system status information, such as whether the terminal is acquired or not, whether it is in use by a task, and so on. Most options, however, reflect the definition of the terminal or session, modified, possibly, by subsequent SET TERMINAL commands or the information obtained from the hardware in a QUERY.
A terminal is specified by a TERMINAL resource definition and the TYPETERM definition to which it points. Characteristics shared by many terminals, such as screen size and 3270 features, are defined by TYPETERM, and those specific to one terminal, such as the name of the associated printer, are in the TERMINAL definition, which may have been autoinstalled. For a session, the CONNECTION defines shared properties and SESSIONS defines specifics. See the CICS® Resource Definition Guide for more information about TERMINAL, TYPETERM, SESSIONS, and CONNECTION resource definitions.
In most cases, options of this type have the same name--or one recognizably similar--as the option in the resource definition. Where this is not the case, the option descriptions that follow indicate the corresponding resource options.
INQUIRE NETNAME returns the same information as INQUIRE TERMINAL. With INQUIRE TERMINAL, you identify the object of your inquiry by providing its CICS terminal identifier in the TERMINAL option. NETNAME is optional. If you include it, CICS returns the network identifier in the data area you provide.
In an INQUIRE NETNAME command, the roles of TERMINAL and NETNAME are reversed. You identify the terminal about which you are inquiring by supplying its network identifier in NETNAME, and CICS returns the corresponding CICS terminal identifier in TERMINAL if you also include that option. TERMINAL must appear before NETNAME (if present) in an INQUIRE TERMINAL command, and vice versa in an INQUIRE NETNAME command.
All of the other options apply to both commands and return the same information. Not all options apply to all types of terminals, however. In particular, when CICS ships a terminal definition from the owning region to a remote region, an inquiry issued in the owning region (where the definition is of a real terminal) produces more information than an inquiry issued in the remote region, where the definition is a surrogate for the one in the owning region.
In addition to links to local terminals or devices, some terminal definitions refer to remote terminals. A remote terminal is a terminal that is owned by another CICS system. The owning system is called the terminal-owning region (TOR). Note that different terminals may have different TORs. TOR here refers to the owning system for a particular terminal.
The way that the local system is connected to the TOR makes a difference to the information that the REMOTESYSTEM field returns.
If the TOR is directly connected to the local system, the REMOTESYSTEM field usually names the CONNECTION definition for the link. (It can name an indirect connection, but that is an unusual setup). In this case, the netname of the TOR is specified in the link CONNECTION definition.
If a remote terminal is on a system that is not directly linked to the TOR, the REMOTESYSTEM field can name one of two types of connection, as follows:
In both these cases, the LINKSYSTEM field of INQUIRE TERMINAL returns the "real" connection that is the next link towards the TOR. It is determined by looking at the logical chain of connections from the terminal in question to the "real" terminal entry. If the chain is broken (because a connection has not been installed yet, or has been discarded) LINKSYSTEM is not set. For a fuller explanation of the relationship between REMOTESYSTEM, REMOTESYSNET, and LINKSYSTEM, see Remote connections.
You can also browse through the definitions of all the terminals installed in your system by using the browse options (START, NEXT, and END) on INQUIRE TERMINAL or INQUIRE NETNAME commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.
If ALTSUFFIX was not specified in the definition of this terminal, the byte returned contains x'00'. Notice that the value x'00' is not described as null, because this is a character field and, in that context, null refers to the blank character x'40', see Null values for a discussion of null values.
If the console is autoinstalled, or is defined explicitly with a console name, the name is returned in the first 8 bytes, and the last 4 bytes are blank.
Using CORRELID, you can relate the two parts of an MRO, LU6.1, or LU6.2 conversation, and so discover, for example, which program is running a particular function shipping mirror.
The GCHARS option applies only to graphic terminals; for others 0 is returned.
The GCODES option applies only to graphic terminals; for others 0 is returned.
For a physical terminal, this is the name by which this terminal is known to VTAM. For ISC sessions, it is the name by which the session (or session group, if there are parallel sessions) is known to VTAM. For MRO sessions, it is the name used by the connected region to log on to the interregion communication program. For a remote terminal, it is the name by which the terminal is known to the VTAM in the remote region. (For a remote terminal routed from a pre-CICS Transaction Server for z/OS region, NETNAME is blank.)
If the netname is a VTAM LU alias, it is different from the netname component of the NQNAME, which always contains the real netname.
This applies to local terminals only--remote terminals do not have a network-qualified name.
NQNAME, which is supported for problem determination purposes only, is returned for both autoinstalled and RDO-defined resources if it has been supplied by VTAM. However, it is not catalogued for RDO-defined resources and is therefore not available on a restart until that resource logs on again.
If the resource is non-VTAM or a remote terminal, NQNAME is blank. If the resource is a VTAM resource but has not yet received an NQNAME, CICS returns the known netname.
Otherwise this field is blank.
The meanings are:
For a task that has this terminal as its principal facility, this value is combined with the TRACING option value of the transaction the task is executing to determine whether tracing is standard, special, or suppressed.
If the transaction TRACING value is SUPPRESSED, no tracing occurs. Otherwise, tracing is special if either the terminal or the transaction specifies SPECTRACE, standard if both specify STANTRACE.
A TRACING value of STANTRACE is assigned when the terminal is defined. You can specify SPECTRACE only with a SET TERMINAL command or the CICS-supplied CETR transaction.
If there is no signed-on user, the default user ID--as specified in the DFLTUSER system initialization parameter--is returned.