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 that is 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 that is 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 that are returned are the same whether the transaction is local or remote.

For more information about these options, see Developing in an intersystem environment.

Options

ABCODE(data-area)

This option returns a 4-character current abend code. Abend codes are documented in Transaction abend codes. If an abend does not occur, the variable is set to blanks.

ABDUMP(data-area)

This option 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 memory dump was produced, or ABCODE contains blanks.

ABOFFSET(data-area)

This option 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)

This option returns an 8-character name of the failing program for the latest abend.

If the abend originally occurred in a DPL server program that is 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, map set or partition set), the name is taken from the program, map set, or partition set that was not loaded.

ACTIVITY(data-area)

This option 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)

This option 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)

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

ALTSCRNWD(data-area)

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

APLKYBD(data-area)

This option 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)

This option 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)

This option returns the 64 character name of the current application that is 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 no application context is associated with the task, then blanks are returned.

APPLID(data-area)

This option returns an 8-character APPLID of the CICS system that owns the transaction.

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

ASRAINTRPT(data-area)

This option 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)

This option 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. 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)

This option 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)

This option 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)

This option 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)

This option 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)

This option returns the type of storage that is 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 that is 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 that is 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 that is 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:

No AEYD, AEYF, AICA, ASRA, or ASRB abend is 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)

This option 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 that of the bridge monitor that issued a START BREXIT naming the bridge exit.

BTRANS(data-area)

This option 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)

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

CMDSEC(data-area)

This option 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)

This option 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)

This option 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)

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

DEFSCRNWD(data-area)

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

DELIMITER(data-area)

This option 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)

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

Following a BMS ROUTE command, it shows that the value that is 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 that is 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 that is obtained is meaningless. If no BMS commands are issued, INVREQ occurs.

DESTID(data-area)

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

DESTIDLENG(data-area)

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

DSSCS(data-area)

This option 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)

This option 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)

This option returns the error message up to a maximum of 500 bytes that is 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)

This option returns a halfword binary value that represents the length of the message that is 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 that is returned is 0.

EWASUPP(data-area)

This option 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)

This option 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 more 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)

This option returns a 4-byte identifier of the principal facility that initiated the transaction that is issuing this command. If this option is specified, and no facility is allocated, 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)

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

GCHARS(data-area)

This option returns a halfword binary graphic character set global identifier (the GCSGID). The value is a number in the range 1 - 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)

This option returns a halfword binary code page global identifier (the CPGID). The value is a number in the range 1 - 65534 representing the EBCDIC or ASCII code page that defines 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)

This option 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)

This option 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)

This option 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)

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

INPARTN(data-area)

This option 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)

This option 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)

This option 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 that is 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)

This option 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)

This option 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)

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

LDCNUM(data-area)

This option returns a 1-byte LDC numeric value of the destination that 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 that is obtained is not significant.

LINKLEVEL(data-area)

This option returns a halfword binary value that represents the program link level in the local system. The topmost link level is 1 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 that is 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 1 is the CICS mirror program DFHMIRS.

LOCALCCSID(data-area)

This option returns the fullword binary Coded Character Set Identifier (CCSID) used for the CICS region. It is the value specified on the LOCALCCSID system initialization parameter.

MAJORVERSION(data-area)

This option returns the fullword binary value that represents the major version of the current application that is associated with the task, which is part of the application context. If no application context is associated with the task, then -1 is returned.

MAPCOLUMN(data-area)

This option 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)

This option 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)

This option 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)

This option 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)

This option returns the fullword binary value that represents the micro version of the current application that is associated with the task, which is part of the application context. If no application context is associated with the task, then -1 is returned.

MINORVERSION(data-area)

This option returns the fullword binary value that represents the minor version of the current application that is associated with the task, which is part of the application context. If no application context is associated with the task, then -1 is returned.

MSRCONTROL(data-area)

This option 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)

This option returns a 1-byte mnemonic code that shows the national language that is 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)

This option 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 that is returned is the termid of the bridge facility.

If the CICS region supports z/OS Communications Server LU aliases, the NETNAME returned by CICS might 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)

This option 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)

This option returns a 1-byte number of the tabs that are 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)

This option 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)

This option returns the 64 character name of the current operation that is associated with the task, which is part of the application context. If there is no application context that is 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)

This option 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 that is 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)

This option returns a 4-byte original abend code in cases of repeated abends.

OUTLINE(data-area)

This option 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)

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

PARTNPAGE(data-area)

This option returns a 2-byte name of the partition that most recently caused page overflow. If no BMS commands are issued, INVREQ occurs.

PARTNS(data-area)

This option 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)

This option 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)

This option 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)

This option 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)

This option 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)

This option 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)

This option returns an 8-character name of the currently running program.

PS(data-area)

This option 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)

This option 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)

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

RESTART(data-area)

This option 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)

This option returns the 8-character name of the program to which control is to be returned when the current program has finished running. The values that are 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 are 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)

This option 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)

This option 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)

This option 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)

This option 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)

This option 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)

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

SYSID(data-area)

This option returns the 4-character name that is 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)

This option 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)

This option 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)

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

TERMCODE(data-area)

This option returns a 2-byte code that gives the type and model number of the terminal that is associated with the task.

The first byte is a code that identifies the terminal type, which is 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)

This option returns a halfword binary terminal priority (0–255).

TEXTKYBD(data-area)

This option 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)

This option 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.

TNADDR(data-area)

Returns, in a 39-character area, the IPv4 or IPv6 address of the TN3270 client. If TNIPFAMILY returns NOTAPPLIC, TNADDR returns blanks.

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

TNIPFAMILY(cvda)

Returns the address format of the TNADDR option. The CVDA values are as follows:

NOTAPPLIC

This value indicates one of the following conditions:

The terminal is not a 3270 device.
TNADDR is not used.
The address cannot be resolved.

IPV4

The TNADDR option contains an IPv4 dotted decimal address.

IPV6

The TNADDR option contains an IPv6 colon hexadecimal address.

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

TNPORT(data-area)

Returns a fullword binary value containing the port number that is used for the TN3270 client connection. If the terminal is not a 3270 device, TNPORT returns zero.

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

TRANPRIORITY(data-area)

This option returns a halfword binary transaction priority (0–255).

TWALENG(data-area)

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

UNATTEND(data-area)

This option 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)

This option 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. For more information about the ASSIGN command for LUTYPE6.1, APPC, and MRO, see the Getting started with intercommunication

USERNAME(data-area)

This option returns a 20-character name of the user, that is obtained from the external security manager (ESM).

USERPRIORITY(data-area)

This option returns a halfword binary operator priority (0–255).

VALIDATION(data-area)

This option 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 that 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 that is invoked by a distributed program link.

Default action: terminate the task abnormally.