ASSIGN

Request values from outside the local environment of the application program.

ASSIGN

Condition: INVREQ

This command is threadsafe.

Description

The ASSIGN command gets values from outside the local environment of the application program. The data obtained depends on the specified options. You can specify up to 16 options in one ASSIGN command. When you specify multiple options on the ASSIGN command, if any of the specified options fails with the exception condition INVREQ, the other specified options are still populated with the requested information.

For options that apply to terminals or terminal-related data, the reference is always to the principal facility.

If the principal facility is a remote terminal, the data returned is obtained from the local copy of the information; the request is not routed to the system to which the remote terminal is attached.

Transaction routing is, as far as possible, transparent to the ASSIGN command. In general, the values returned are the same whether the transaction is local or remote.

For more details on these options, see Developing in an intersystem environment.

Options

ABCODE(data-area)

Returns a 4-character current abend code. Abend codes are documented in Transaction abend codes. If an abend has not occurred, the variable is set to blanks.

ABDUMP(data-area)

Returns a 1-byte value. X'FF' indicates that an EXEC CICS ABEND ABCODE command was issued without the NODUMP option and that ABCODE contains an abend code. X'00' indicates that either no dump was produced, or ABCODE contains blanks.

ABOFFSET(data-area)

Returns a fullword binary offset in bytes of an abend when the latest abend with a code ASRA, ASRB, or ASRD occurred. If the abend is outside the current program, a value of X'FFFFFFFF' is returned. The data area is set to binary zeros if no ASRA, ASRB, or ASRD abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program.

ABPROGRAM(data-area)

Returns an 8-character name of the failing program for the latest abend.

If the abend originally occurred in a DPL server program running in a remote system, ABPROGRAM returns the DPL server program name.

This field is set to binary zeros if it is not possible to determine the failing program at the time of the abend.

When the latest abend is an APCT (resulting from an unsuccessful attempt to load a program, mapset or partitionset), the name is taken from the program, mapset, or partitionset that was not loaded.

ACTIVITY(data-area)

Returns, if this program is running on behalf of a CICS® business transaction services (BTS) activity, the 16-character name of the activity.

BTS is described in Overview of BTS.

ACTIVITYID(data-area)

Returns, if this program is running on behalf of a BTS activity, the 52-character, CICS-assigned, identifier of the activity-instance.

If a program that is running outside the current process wants to acquire control of this activity-instance, it must specify this identifier on an ACQUIRE ACTIVITYID command.

BTS is described in Overview of BTS.

ALTSCRNHT(data-area)

Returns the alternate screen height defined for the terminal as a halfword binary variable. If the task is not initiated from a terminal, INVREQ occurs.

ALTSCRNWD(data-area)

Returns the alternate screen width defined for the terminal as a halfword binary variable. If the task is not initiated from a terminal, INVREQ occurs.

APLKYBD(data-area)

Returns a 1-byte indicator that shows whether the terminal keyboard has the APL keyboard feature (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

APLTEXT(data-area)

Returns a 1-byte indicator that shows whether the terminal keyboard has the APL text feature (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

APPLICATION(data-area)

Returns the 64 character name of the current application associated with the task. It is part of the application context that is made up of the application name, the platform name, the operation name and the major, minor and micro version number of the application. If there is no application context associated with the task, then blanks are returned.

APPLID(data-area)

Returns an 8-character APPLID of the CICS system that owns the transaction.

If your system is using XRF, the value returned is the generic APPLID. An application program is unaffected by a takeover from the active to the alternate.

ASRAINTRPT(data-area)

Returns an 8-character data-area that contains the ILC (instruction length code) and the PIC (program interrupt code) at the point when the latest abend with a code of AICA, ASRA, ASRB, ASRD, or ASRE occurred. The field contains binary zeros if no AICA, ASRA, ASRB, ASRD, or ASRE abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program. When valid, the contents of the 8 bytes returned are as follows:

ILC (2 bytes binary)
PIC (2 bytes binary)
filler (4 bytes binary, always zero)

ASRAKEY(cvda)

Returns the execution key at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend, if any. CVDA values are as follows:

CICSEXECKEY: This value is returned if the task was running in CICS-key at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend. Note that if CICS subsystem storage protection is not active, all programs run in CICS key.
USEREXECKEY: This value is returned if the task was running in user-key at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend.
NONCICS: This value is returned if the execution key at the time of the last abend was not one of the CICS keys; for example, not key 8 or key 9.
NOTAPPLIC: This value is returned if there was not an AEYD, AEYF, AICA, ASRA, or ASRB abend.

ASRAPSW(data-area)

Returns an 8-byte data area that contains the program status word (PSW) at the point when the latest abend with a code of AICA, ASRA, ASRB, ASRD, or ASRE occurred.

The field contains binary zeros if no AICA, ASRA, ASRB, ASRD, or ASRE abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program.

ASRAPSW16(data-area)

Returns a 16-byte data area that contains the 128-bit program status word (PSW) at the point when the latest abend with a code of AICA, ASRA, ASRB, ASRD, or ASRE occurred.

ASRAREGS(data-area)

Returns the contents of general registers 0 - 15 at the point when the latest AICA, ASRA, ASRB, ASRD, or ASRE abend occurred.

The contents of the registers are returned in the data area (64 bytes long) in the order 0, 1, ..., 14, 15.

The data area is set to binary zeros if no AICA, ASRA, ASRB, ASRD, or ASRE abend occurred during the execution of the issuing transaction, or if the abend originally occurred in a remote DPL server program.

ASRAREGS64(data-area)

Returns the contents of the 64-bit general registers 0 - 15 at the point when the latest AICA, ASRA, ASRB, ASRD, or ASRE abend occurred.

The contents of the registers are returned in the data area (128 bytes long) in the order 0, 1, ..., 14, 15.

ASRASPC(cvda)

Returns the type of space in control at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend, if any. CVDA values are as follows:

SUBSPACE: This value is returned if the task was running in either its own subspace or the common subspace at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend.
BASESPACE: This value is returned if the task was running in the base space at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend. All tasks run in base space if transaction isolation is not active.
NOTAPPLIC: This value is returned if there was not an AEYD, AEYF, AICA, ASRA, or ASRB abend.

ASRASTG(cvda)

Returns the type of storage being addressed at the time of the last AEYD, AEYF, AICA, ASRA, or ASRB abend, if any. The CVDA values are as follows:

CICS

This value is returned if the storage being addressed is CICS-key storage. This can be in one of the CICS dynamic storage areas (CDSA, ECDSA, ETDSA, or GCDSA). This can be in one of the read-only dynamic storage areas (RDSA or ERDSA) when CICS is running with the NOPROTECT option on the RENTPGM system initialization parameter, or when storage protection is not active.

USER

This value is returned if the storage being addressed is user-key storage in one of the user dynamic storage areas (UDSA, EUDSA, or GUDSA).

READONLY

This value is returned if the storage being addressed is read-only storage in one of the read-only dynamic storage areas (RDSA or ERDSA) when CICS is running with the PROTECT option on the RENTPGM system initialization parameter.

NOTAPPLIC

This value is returned in the following conditions:

There is no AEYD, AEYF, AICA, ASRA, or ASRB abend found for this task.
The affected storage in an abend is not managed by CICS.
The ASRA abend is not caused by an 0C4 abend.

BRIDGE(data-area)

Returns the 4-character TRANSID of the bridge monitor transaction that issued a START BREXIT TRANSID command to start the user transaction that issued this command. Blanks are returned in the following situations:

The user transaction was not started by a bridge monitor transaction.
This command was issued by a program started by a distributed program link (DPL) request.

Note: If the START BREXIT command was issued from a bridge exit, the TRANSID returned is the that of the bridge monitor that issued a START BREXIT naming the bridge exit.

BTRANS(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the background transparency capability (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

CHANNEL(data-area)

Returns the 16-character name of the current channel of the program, if one exists; otherwise blanks.

CMDSEC(data-area)

Returns a 1-byte indicator that shows whether command security checking is defined for the current task. (X for yes, blank for no.)

COLOR(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the extended color capability (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

CWALENG(data-area)

Returns a halfword binary field that indicates the length of the common work area (CWA). If no CWA exists, a zero length is returned.

DEFSCRNHT(data-area)

Returns a halfword binary variable that contains the default screen height defined for the terminal. If the task is not initiated from a terminal, INVREQ occurs.

DEFSCRNWD(data-area)

Returns a halfword binary variable that contains the default screen width defined for the terminal. If the task is not initiated from a terminal, INVREQ occurs.

DELIMITER(data-area)

Returns a 1-byte data-link control character for a 3600. Possible values are as follows:

X'80': Input ended with end-of-text (ETX).
X'40': Input ended with end-of-block (ETB).
X'20': Input ended with inter-record separator (IRS).
X'10': Input ended with start of header (SOH).
X'08': Transparent input.

If the task is not initiated from a terminal, INVREQ occurs.

DESTCOUNT(data-area)

Returns a halfword binary field. This option has the following uses:

Following a BMS ROUTE command, it shows that the value required is the number of different terminal types in the route list, and hence the number of overflow control areas that might be required.
Within BMS overflow processing, it shows that the value required is the relative overflow control number of the destination that has encountered overflow. If this option is specified when overflow processing is not in effect, the value obtained is meaningless. If no BMS commands have been issued, INVREQ occurs.

DESTID(data-area)

Returns an 8-byte identifier of the outboard destination, padded with blanks on the right to eight characters. If this option is specified before a batch data interchange command is issued in the task, INVREQ occurs.

DESTIDLENG(data-area)

Returns a halfword binary length of the destination identifier obtained by DESTID. If this option is specified before a batch data interchange command is issued in the task, INVREQ occurs.

DSSCS(data-area)

Returns a 1-byte indicator that shows whether the principal facility is a basic SCS data stream device (X'FF') or not (X'00').

If the task is not initiated from a terminal, INVREQ occurs.

DS3270(data-area)

Returns a 1-byte indicator that shows whether the principal facility is a 3270 data stream device (X'FF') or not (X'00').

If the task is not initiated from a terminal, INVREQ occurs.

ERRORMSG(data-area)

Returns the error message up to a maximum of 500 bytes that is currently referenced in the transaction abend control block for the CICS task. Following a failure of a DPL request, the message is that returned from the remote system. For messages shorter than 500 bytes the message is padded with nulls.

If no message is present, the 500 byte area contains nulls.

ERRORMSGLEN(data-area)

Returns a halfword binary value representing the length of the message returned for ERRORMSG. If the message referenced in the transaction abend control block exceeds 500 bytes, the message is truncated and the length is set to 500.

If no message is present the length returned is 0.

EWASUPP(data-area)

Returns a 1-byte indicator that shows whether Erase Write Alternative is supported (X'FF') or not (X'00').

If the task is not initiated from a terminal, INVREQ occurs.

EXTDS(data-area)

Returns a 1-byte indicator that shows whether the terminal accepts the 3270 extended data stream, (X'FF') or not (X'00'). Extended data stream capability is required for a terminal that supports the query feature, color, extended highlighting, programmed symbols or validation. A terminal that accepts the query structured field command also has this indicator set. If extended data stream is on, the device supports the write structured field COMMAND and Outbound Query Structured field.

For guidance information about query structured fields, see the IBM 3270 Data Stream Programmers Reference.

If the task is not initiated from a terminal, INVREQ occurs.

FACILITY(data-area)

Returns a 4-byte identifier of the principal facility that initiated the transaction issuing this command. If this option is specified, and there is no allocated facility, INVREQ occurs.

Note: You can use the QNAME option to get the name of the transient data intrapartition queue if the transaction was initiated by expiry of a transient data trigger level.

FCI(data-area)

Returns a 1-byte facility control indicator. For more information, see Codes returned by ASSIGN. This indicates the type of facility associated with the transaction; for example, X'01' indicates a terminal or logical unit. The obtained value is always returned.

GCHARS(data-area)

Returns a halfword binary graphic character set global identifier (the GCSGID). The value is a number in the range 1 through 65534 representing the set of graphic characters that can be input or output at the terminal. If the task is not initiated from a terminal, INVREQ occurs.

GCODES(data-area)

Returns a halfword binary code page global identifier (the CPGID). The value is a number in the range 1 through 65534 representing the EBCDIC or ASCII code page defining the code points for the characters that can be input or output at the terminal. If the task is not initiated from a terminal, INVREQ occurs.

GMMI(data-area)

Returns a 1-byte indicator that shows whether a good morning message applies to the terminal associated with the running transaction (X'FF') or not (X'00'). If this option is specified and the current task is not associated with a terminal, the INVREQ condition occurs.

HILIGHT(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the extended highlight capability (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

INITPARM(data-area)

Returns the 60-character data-area that contains any initialization parameters that are specified for the program on the INITPARM system initialization parameter. The values are only returned if the name of the program that issues the command matches a program name that is specified on the INITPARM system initialization parameter. If there are no parameters for the program, the area is not updated and its contents are undefined. Use INITPARMLEN with INITPARM to determine whether a parameter was specified or not; the value that is returned by ASSIGN INITPARM alone cannot be used to indicate whether a system initialization parameter was specified.

INITPARMLEN(data-area)

Returns a halfword binary length of the INITPARM. If there is no parameter for it, INITPARMLEN contains binary zeros.

INPARTN(data-area)

Returns the 1- or 2-character name of the most recent input partition. If no map is yet positioned, or if BMS routing is in effect, or if the task is not initiated from a terminal, INVREQ occurs.

INPUTMSGLEN(data-area)

Returns a halfword binary length of the terminal input string, in bytes. If there is no terminal input data, a length of zero is returned.

INVOKINGPROG(data-area)

Returns the 8-character name of the application program that used the LINK or XCTL command to link or transfer control to the current program:

If you issue the ASSIGN INVOKINGPROG command in a remote program that was invoked by a distributed program link (DPL) command, CICS returns the name of the program that issued the DPL command.
If you issue the ASSIGN INVOKINGPROG command in an application program at the highest level, CICS returns eight blanks.
If you issue the ASSIGN INVOKINGPROG command in a user-replaceable program, a Bridge Exit program or a program list table program, CICS returns eight blanks.
If you issue the ASSIGN INVOKINGPROG command from a global user exit, task-related exit, or application program linked to from such an exit, CICS returns the name of the most recent invoking program that was not a global user exit or task-related user exit.

KATAKANA(data-area)

Returns a 1-byte indicator that shows whether the principal facility supports Katakana (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

LANGINUSE(data-area)

Returns a 3-byte mnemonic code that shows the language in use. The 3-byte mnemonic has a 1:1 correspondence with the 1-byte NATLANGINUSE option. See National language codes for possible values of the code.

LDCMNEM(data-area)

Returns a 2-byte logical device code (LDC) mnemonic of the destination that has encountered overflow. If this option is specified when overflow processing is not in effect, the value obtained not significant. If no BMS commands have been issued, INVREQ occurs.

LDCNUM(data-area)

Returns a 1-byte LDC numeric value of the destination that has encountered overflow. This indicates the type of the LDC, such as printer or console. If this option is specified when overflow processing is not in effect, the value obtained is not significant.

LINKLEVEL(data-area)

Returns a halfword binary value representing the program link level in the local system. The topmost link level is level one and for each EXEC CICS LINK the link level is incremented by one. The link level is not incremented for a language CALL statement. If a program is the target of a DPL request, the link level returned is that within the CICS region it is executing and not the wider distributed transaction. If a program is DPLed to, then link level one will be the CICS mirror program DFHMIRS.

MAJORVERSION(data-area)

Returns the fullword binary value representing the major version of the current application associated with the task, which is part of the application context. If there is no application context associated with the task, then -1 is returned.

MAPCOLUMN(data-area)

Returns a halfword binary number of the column on the display that contains the origin of the most recently positioned map. If no map is yet positioned, or if BMS routing is in effect, or if the task is not initiated from a terminal, INVREQ occurs.

MAPHEIGHT(data-area)

Returns a halfword binary height of the most recently positioned map. If no map is yet positioned, or if BMS routing is in effect, or if the task is not initiated from a terminal, INVREQ occurs.

MAPLINE(data-area)

Returns a halfword binary number of the line on the display that contains the origin of the most recently positioned map. If no map is yet positioned, or if BMS routing is in effect, or if the task is not initiated from a terminal, INVREQ occurs.

MAPWIDTH(data-area)

Returns a halfword binary width of the most recently positioned map. If no map is yet positioned, or if BMS routing is in effect, or if the task is not initiated from a terminal, INVREQ occurs.

MICROVERSION(data-area)

Returns the fullword binary value representing the micro version of the current application associated with the task, which is part of the application context. If there is no application context associated with the task, then -1 is returned.

MINORVERSION(data-area)

Returns the fullword binary value representing the minor version of the current application associated with the task, which is part of the application context. If there is no application context associated with the task, then -1 is returned.

MSRCONTROL(data-area)

Returns a 1-byte indicator that shows whether the terminal supports magnetic slot reader (MSR) control (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

NATLANGINUSE(data-area)

Returns a 1-byte mnemonic code that shows the national language associated with the USERID for the current task (which could be the default USERID). Refer to the SIGNON command for an explanation of how this value is derived. (NATLANGINUSE does not show the system default language as specified on the NATLANG system initialization parameter.)

See National language codes for possible values of the code.

NETNAME(data-area)

Returns the 8-character name of the logical unit in the z/OS® Communications Server network. If the task is not initiated from a terminal, INVREQ occurs. If the principal facility is not a local terminal, CICS no longer returns a null string but the netname of the remote terminal.

If this command was issued by a user transaction that was started by a 3270 bridge transaction, the value returned is the termid of the bridge facility.

If the CICS region supports z/OS Communications Server LU aliases, the NETNAME returned by CICS could be an LU alias, either dynamically allocated by z/OS Communications Server or predefined on the LUALIAS parameter of a CDRSC definition.

NEXTTRANSID(data-area)

Returns the 4-character next transaction identifier as set by SET NEXTTRANSID or RETURN TRANSID. It returns blanks if there are no more transactions.

NUMTAB(data-area)

Returns a 1-byte number of the tabs required to position the print element in the correct passbook area of the 2980. If the task is not initiated from a terminal, INVREQ occurs.

OPCLASS(data-area)

Returns, in a 24-bit string, the operator class used by BMS for routing terminal messages, as defined in the CICS segment of the External Security Manager.

OPERATION(data-area)

Returns the 64 character name of the current operation associated with the task, which is part of the application context. If there is no application context associated with the task, then blanks are returned.

OPERKEYS(data-area)

This option is accepted for compatibility with previous releases. If specified, a 64-bit null string is returned.

OPID(data-area)

Returns the 3-character operator identification. This is used by BMS for routing terminal messages, as defined in the CICS segment of the External Security Manager.

If the task is initiated from a remote terminal, the OPID returned by this command is not necessarily that associated with the user that is signed on at the remote terminal. If you want to know the OPID of the signed on user, use the INQUIRE TERMINAL system programming command.

The OPID can also be different from the OPID of the user currently signed on, if it was changed with the SET TERMINAL command.

OPSECURITY(data-area)

This option is accepted for compatibility with previous releases. If specified, a 24-bit null string is returned.

ORGABCODE(data-area)

Returns a 4-byte original abend code in cases of repeated abends.

OUTLINE(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the field outlining capability (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

PAGENUM(data-area)

Returns a halfword binary current page number for the destination that has encountered an overflow. If this option is specified when overflow processing is not in effect, the value obtained is meaningless. If no BMS commands have been issued, INVREQ occurs.

PARTNPAGE(data-area)

Returns a 2-byte name of the partition that most recently caused page overflow. If no BMS commands have been issued, INVREQ occurs.

PARTNS(data-area)

Returns a 1-byte indicator that shows whether the terminal supports partitions (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

PARTNSET(data-area)

Returns the name (1–6 characters) of the application partition set. A blank value is returned if there is no application partition set. If the task is not initiated from a terminal, INVREQ occurs.

PLATFORM(data-area)

Returns the 64 character name of the platform associated with the task, which is part of the application context. If there is no application context associated with the task, then blanks are returned.

PRINSYSID(data-area)

Returns the 4-character name by which the other system is known in the local system; that is, the CONNECTION definition that defines the other system. For a single-session APPC device defined by a terminal definition, the returned value is the terminal identifier.

This only applies when the principal facility is one of the following:

An MRO session to another CICS system
An LU6.1 session to another CICS or IMS system
An APPC session to another CICS system, or to another APPC system or device

If the principal facility is not an MRO, LU6.1, or APPC session, or if the task has no principal facility, INVREQ occurs.

Note: Special considerations apply generally when transaction routing. In particular an ASSIGN PRINSYSID command cannot be used in a routed transaction to find the name of the terminal-owning region. For more information, see CICS transaction routing.

PROCESS(data-area)

Returns, if this program is running on behalf of a CICS business transaction services (BTS) activity, the 36-character name of the BTS process that contains the activity.

BTS is described in Overview of BTS.

PROCESSTYPE(data-area)

Returns, if this program is running on behalf of a BTS activity, the 8-character process type of the BTS process that contains the activity.

BTS is described in Overview of BTS.

PROGRAM(data-area)

Returns an 8-character name of the currently running program.

PS(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the programmed symbols capability (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

QNAME(data-area)

Returns a 4-character name of the transient data intrapartition queue that caused this task to be initiated by reaching its trigger level. If the task is not initiated by automatic transaction initiation (ATI), INVREQ occurs.

RESSEC(data-area)

Returns a 1-byte indicator that shows whether resource security checking is defined for the transaction running. (X for yes, blank for no.)

RESTART(data-area)

Returns a 1-byte indicator that shows whether a restart of the task (X'FF'), or a normal start of the task (X'00'), has occurred.

RETURNPROG(data-area)

Returns the 8-character name of the program to which control is to be returned when the current program has finished running. The values returned depend on how the current program was given control, as follows:

If the current program was invoked by a LINK command, including a distributed program link, RETURNPROG returns the same name as INVOKINGPROG.
If the current program was invoked by an XCTL command, RETURNPROG returns the name of the application program in the chain that last issued a LINK command.
If the program that invoked the current program with an XCTL command is at the highest level, CICS returns eight blanks.
If the ASSIGN RETURNPROG command is issued in the program at the top level, CICS returns eight blanks.
If the ASSIGN RETURNPROG command is issued in a user-replaceable module, or a program list table program, CICS returns eight blanks.
If the ASSIGN RETURNPROG command is issued in a global user exit, task-related exit, or application program linked to from such an exit, CICS returns the name of the program that control is returned to when all intermediate global user exit and task-related user exit programs have completed.

Example:

Program A links to program B
Program B links to program C
Program C uses XCTL to transfer control to program D 
Program D issues an ASSIGN RETURNPROG command, and CICS returns the name of Program B.

SCRNHT(data-area)

Returns a halfword binary variable that contains the height of the 3270 screen defined for the current task. If the task is not initiated from a terminal, INVREQ occurs.

SCRNWD(data-area)

Returns a halfword binary variable that contains the width of the 3270 screen defined for the current task. If the task is not initiated from a terminal, INVREQ occurs.

SIGDATA(data-area)

Returns a 4-byte character string that contains the inbound signal data received from a logical unit. If the task is not initiated from a terminal, INVREQ occurs.

SOSI(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the mixed EBCDIC/DBCS fields capability (X'FF') or not (X'00'). The DBCS subfields within an EBCDIC field are delimited by SO (shift-out) and SI (shift-in) characters. If the task is not initiated from a terminal, INVREQ occurs.

STARTCODE(data-area)

Returns a 2-character value that indicates how the transaction that issued the request was started. Possible values are as follows:

Code: Transaction started by
D: A distributed program link (DPL) request that did not specify the SYNCONRETURN option. The task cannot issue I/O requests against its principal facility, or any sync point requests.
DS: A distributed program link (DPL) request, as in code D, that did specify the SYNCONRETURN option. The task can issue sync point requests.
QD: Transient data trigger level.
S: START command that did not pass data in the FROM option. It might or might not have passed a channel.
SD: START command that passed data in the FROM option.
SZ: FEPI START command.
TD: Terminal input or permanent transid.
U: User-attached task.

STATIONID(data-area)

Returns a 1-byte station identifier of a 2980. If the task is not initiated from a terminal, INVREQ occurs.

SYSID(data-area)

Returns the 4-character name given to the local CICS system. This value can be specified in the SYSID option of a file control, interval control, temporary storage, or transient data command, in which case the resource to be accessed is assumed to be on the local system.

TASKPRIORITY(data-area)

Returns a halfword binary filed that indicates the current priority of the issuing task (0–255). When the task is first attached, this is the sum of the user, terminal, and transaction priorities. This value can be changed during execution by a CHANGE TASK command.

TCTUALENG(data-area)

Returns a halfword binary length of the terminal control table user area (TCTUA). If no TCTUA exists, a zero length is returned.

TELLERID(data-area)

Returns a 1-byte teller identifier of a 2980. If the task is not initiated from a terminal, INVREQ occurs.

TERMCODE(data-area)

Returns a 2-byte code giving the type and model number of the terminal associated with the task.

The first byte is a code identifying the terminal type, derived from the TERMINAL resource. For a description of the resource attributes, see TERMINAL attributes . The second byte is a single-character model number as specified in the TERMMODEL attribute.

The meanings of the type codes are given in Codes returned by ASSIGN.

TERMPRIORITY(data-area)

Returns a halfword binary terminal priority (0–255).

TEXTKYBD(data-area)

Returns a 1-byte indicator that shows whether the principal facility supports TEXTKYBD (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

TEXTPRINT(data-area)

Returns a 1-byte indicator that shows whether the principal facility supports TEXTPRINT (X'FF') or not (X'00'). If the task is not initiated from a terminal, INVREQ occurs.

TRANPRIORITY(data-area)

Returns a halfword binary transaction priority (0–255).

TWALENG(data-area)

Returns a halfword binary length of the transaction work area (TWA). If no TWA exists, a zero length is returned.

UNATTEND(data-area)

Returns a 1-byte indicator that shows whether the mode of operation of the terminal is unattended, that is to say that no person is attending the terminal. These indicators are X'FF' for unattended and X'00' for attended. If the task is not initiated from a terminal, INVREQ occurs.

USERID(data-area)

Returns an 8-byte user ID of the signed-on user. If no user is explicitly signed on, CICS returns the default user ID. Special considerations apply if you are using an intercommunication environment. See the Getting started with intercommunication for more information about the ASSIGN command for LUTYPE6.1, APPC, and MRO.

USERNAME(data-area)

Returns a 20-character name of the user obtained from the external security manager (ESM).

USERPRIORITY(data-area)

Returns a halfword binary operator priority (0–255).

VALIDATION(data-area)

Returns a 1-byte indicator that shows whether the terminal is defined as having the validation capability (X'FF') or not (X'00'). Validation capability consists of the mandatory fill, mandatory enter, and trigger attributes. If the task is not initiated from a terminal, INVREQ occurs.

Conditions

The ASSIGN command always returns the exception condition INVREQ under CECI or in a REXX program. Even though CECI or the REXX program might return the information you requested correctly, it also attempts to get information from other options, some of which are invalid.

16 INVREQ

RESP2 values:

2: No BMS command has yet been issued, BMS routing is in effect, or no map has yet been positioned.
3: No batch data interchange (BDI) command has yet been issued.
4: The task is not initiated by automatic transaction initiation (ATI).
5: The task is not associated with a terminal; or the task has no principal facility; or the principal facility is not an MRO, LU6.1, or APPC session.
6: A CICS BTS request was issued from outside the CICS BTS environment. Therefore, the transaction is not running on behalf of a BTS activity.
200: Command syntax options are not allowed in a server program invoked by a distributed program link.

Default action: terminate the task abnormally.