Obtains values from outside the local
environment of the application program.
Syntax
ASSIGN
.-----------------------------.
V |
>>-ASSIGN----+-------------------------+-+---------------------->
+-ABCODE(data-area)-------+
+-APPLID(data-area)-------+
+-BTRANS(data-area)-------+
+-CHANNEL(data-area)------+
+-COLOR(data-area)--------+
+-CWALENG(data-area)------+
+-EXTDS(data-area)--------+
+-FACILITY(data-area)-----+
+-FCI(data-area)----------+
+-GCHARS(data-area)-------+
+-GCODES(data-area)-------+
+-HILIGHT(data-area)------+
+-KATAKANA(data-area)-----+
+-MAPCOLUMN(data-area)----+
+-MAPHEIGHT(data-area)----+
+-MAPLINE(data-area)------+
+-MAPWIDTH(data-area)-----+
+-MSRCONTROL(data-area)---+
+-NETNAME(data-area)------+
+-NEXTTRANSID(data-area)--+
+-ODBCHNDLLIST(data-area)-+
+-ODBCLISTLEN(data-area)--+
'-OPCLASS(data-area)------'
.---------------------------.
V |
>----+-----------------------+-+-------------------------------><
+-OPERKEYS(data-area)---+
+-OPID(data-area)-------+
+-OPSECURITY(data-area)-+
+-OUTLINE(data-area)----+
+-PRINSYSID(data-area)--+
+-PROGRAM(data-area)----+
+-PS(data-area)---------+
+-QNAME(data-area)------+
+-RESTART(data-area)----+
+-SCRNHT(data-area)-----+
+-SCRNWD(data-area)-----+
+-SIGDATA(data-area)----+
+-SOSI(data-area)-------+
+-STARTCODE(data-area)--+
+-SYSID(data-area)------+
+-TCTUALENG(data-area)--+
+-TERMCODE(data-area)---+
+-TWALENG(data-area)----+
+-UNATTEND(data-area)---+
+-USERID(data-area)-----+
'-VALIDATION(data-area)-'
Condition: INVREQ
Fields ignored in TXSeries for Multiplatforms:
- BTRANS
- GCHARS
- GCODES
- MSRCONTROL
- OPCLASS
- RESTART
- UNATTEND
Description
ASSIGN obtains values from
outside the local application program environment. The data that is
obtained depends on the specified options. You can specify up to 16
options in one ASSIGN command.
Where any of the following options
apply to terminals or terminal-related data, the reference is always
to the principal facility.
If the principal facility is a remote
terminal, CICS® obtains the data from the local copy of
the information; CICS does not route the request to the region
to which the remote terminal is attached.
Transaction routing
is as far as possible transparent to the ASSIGN command. In general, CICS returns
the same values whether the transaction is local or remote.
Some
of the ASSIGN options are not meaningful to TXSeries for Multiplatforms and
cause CICS to return default (not necessarily null)
values. For further information, see the descriptions of the options
concerned.
Options
- ABCODE(data-area)
- Returns
a four-byte string that represents the current abnormal termination
code. If an abnormal termination has not occurred, CICS sets
the data-area to blanks.
Note: Abend codes are documented
in TXSeries for Multiplatforms Messages
and Codes.
- APPLID(data-area)
- Returns
an eight-byte string that gives the name of the region.
- BTRANS(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default X'00', which is a one-byte
indicator showing that the terminal is defined as not having background
transparency capability.
If the task is not initiated from a terminal,
INVREQ occurs. INVREQ also occurs if an attempt is made to issue an
ASSIGN command with this option from a remotely linked-to program.
- CHANNEL(data-area)
- Returns the 16-character name of the program's current channel,
if one exist. It is otherwise blank.
- COLOR(data-area)
- Returns
a one-byte indicator that shows whether the terminal is defined as
having the extended color capability (X'FF') or not (X'00').
Extended color capability is defined by the Terminal Definition attribute Foreground.
If
the task is not initiated from a terminal, INVREQ occurs. INVREQ also
occurs if an attempt is made to issue an ASSIGN command with this
option from a remotely linked-to program.
- CWALENG(data-area)
- Returns
a 16-bit binary field that indicates the length of the Common Work
Area (CWA). If no CWA exists, CICS returns a zero length.
- EXTDS(data-area)
- Returns
a one-byte indicator that shows whether the terminal is defined as
having the extended data stream capability (X'FF') or not
(X'00'). If the task is not initiated from a terminal, INVREQ
occurs. INVREQ also occurs if an attempt is made to issue an ASSIGN
command with this option from a remotely linked-to program.
- FACILITY(data-area)
- Returns
a four-byte field that contains either the identifier of the facility
that initiated the transaction or, in the case of a transaction whose
principal facility is an advanced program-to-program communications
(APPC) conversation,
the conversation identifier. If you specify this option and no allocated
facility exists, INVREQ occurs. INVREQ also occurs if an attempt is
made to issue an ASSIGN command with this option from a remotely linked-to
program. (An APPC conversation allows a program to send data to, and
receive data from, a program that is running in a remote system. Programming
that uses APPC conversations is called Distributed Transaction Programming
(DTP). For guidance information about DTP, see Distributed transaction processing (DTP).)
Note: Always use the QNAME option to get the name
of the transient data intrapartition queue whose trigger level caused
the transaction to be initiated.
- FCI(data-area)
- Returns
a one-byte field that contains the facility control indicator. This
indicates the type of facility that is associated with the transaction;
for example, X'01' indicates a terminal or logical unit. CICS always
returns the obtained value.
CICS returns
the following facility control indicator codes (listed here both as
bit patterns and as hexadecimal values):
Code |
Meaning |
0000 0000 X'00' |
START without data |
0000 0001 X'01' |
Terminal or APPC task |
0000 1000 X'08' |
Triggered task |
0001 0000 X'10' |
START with data |
An INVREQ occurs if an attempt is made to issue an ASSIGN
command with this option from a remotely linked-to program.
- GCHARS(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default zero, which is a 16-bit binary field
that shows that no Graphic byte Set Global Identifier (GCSGID) exists.
If the task is not initiated from a terminal, INVREQ occurs.
INVREQ also occurs if an attempt is made to issue an ASSIGN command
with this option from a remotely linked-to program.
The term Codes
Graphic byte Set Identifier is commonly used when referring to
GCHARS and GCODES as a pair.
- GCODES(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default zero, which is a 16-bit binary field
that shows that no Code Page Global Identifier (CPGID) exists. If
the task is not initiated from a terminal, INVREQ occurs. INVREQ also
occurs if an attempt is made to issue an ASSIGN command with this
option from a remotely linked-to program.
The term Codes Graphic
byte Set Identifier is commonly used when referring to GCHARS
and GCODES as a pair.
- HILIGHT(data-area)
- Returns
a one-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. INVREQ
also occurs if an attempt is made to issue an ASSIGN command with
this option from a remotely linked-to program.
- KATAKANA(data-area)
- Returns
a one-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. INVREQ also occurs if
an attempt is made to issue an ASSIGN command with this option from
a remotely linked-to program.
- MAPCOLUMN(data-area)
- Returns
a 16-bit binary field that indicates the number of the column on the
display that contains the origin of the most recently positioned map.
If no map has yet been positioned, or if the task is not initiated
from a terminal, INVREQ occurs. INVREQ also occurs if an attempt is
made to issue an ASSIGN command with this option from a remotely linked-to
program.
- MAPHEIGHT(data-area)
- Returns
a 16-bit binary field that indicates the height of the most recently
positioned map. If no map has yet been positioned, or if the task
is not initiated from a terminal, INVREQ occurs. INVREQ also occurs
if an attempt is made to issue an ASSIGN command with this option
from a remotely linked-to program.
- MAPLINE(data-area)
- Returns
a 16-bit binary field that indicates the number of the line on the
display that contains the origin of the most recently positioned map.
If no map has yet been positioned, or if the task is not initiated
from a terminal, INVREQ occurs. INVREQ also occurs if an attempt is
made to issue an ASSIGN command with this option from a remotely linked-to
program.
- MAPWIDTH(data-area)
- Returns
a 16-bit binary field that indicates the width of the most recently
positioned map. If no map has yet been positioned, or if the task
is not initiated from a terminal, INVREQ occurs. INVREQ also occurs
if an attempt is made to issue an ASSIGN command with this option
from a remotely linked-to program.
- MSRCONTROL(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default X'00', which is a one-byte
indicator that shows that the terminal does not support magnetic slot
reader (MSR) control. If the task is not initiated from a terminal,
INVREQ occurs. INVREQ also occurs if an attempt is made to issue an
ASSIGN command with this option from a remotely linked-to program.
- NETNAME(data-area)
- Returns
an eight-byte string that represents the network logical unit name
of the principal facility. When the principal facility is a cicsterm or cicsteld session,
the returned netname is the name that was specified when the session
was started or the name that was generated by the autoinstall process.
When the principal facility is a conversation, the returned netname
is the name of the remote system; if the remote system is another
region, the netname is the name of that region. The terms application
identifier (applid), netname, and LU name are used interchangeably
in CICS. If the task has no principal facility,
INVREQ occurs.
- NEXTTRANSID(data-area)
- Returns
a four-byte string that contains the next transaction identifier as
set by RETURN TRANSID. It returns blanks if no next transaction exists.
INVREQ occurs if an attempt is made to issue an ASSIGN command with
this option from a remotely linked-to program.
- ODBCHNDLLIST(data-area)
- Returns
a fixed-length, 240-byte data area that contains a list of available
ODBC connection handles for an application server. Each connection
handle is stored in a structure (ODBC_ConnArray) that contains a half
word XAD Connection ID (the user-assigned unique ID for this connection),
a half word type of ODBC handle (which implies the handles basic length),
and the ODBC handle itself.
For more information about the ODBC_ConnArray
structure, refer to the header file
cics_odbc.h,
which is under the "Drive:\opt\cics\include" directory.
Note: This
option for ASSIGN API applies only to CICS systems
that are using Microsoft SQL Server on Windows and using an XA-enabled environment.
In other environment and database connections, this option returns
NULL.
- ODBCLISTLEN(data-area)
- Returns
a half-word length of the ODBCHNDLLIST data-area. If no ODBC handles
were returned, ODBCHNDLLEN contains zero.
Note: This option for ASSIGN
API applies only to CICS systems that are using Microsoft SQL Server on Windows and
using an XA-enabled environment. In other environment and database
connections, this option returns zero.
- OPCLASS(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default X'000000', which is a three-byte
string that indicates that no operator class used by BMS for routing
terminal messages. If the task is not initiated from a terminal, INVREQ
occurs. INVREQ also occurs if an attempt is made to issue an ASSIGN
command with this option from a remotely linked-to program.
- OPERKEYS(data-area)
- Returns
an eight-byte string that indicates the transaction security key that
is associated with the current terminal user, as defined in the TSLKeylist attribute
in the User Definitions (UD).
The returned value is a 64-bit mask that allows for a security key
in the range 1 through 64. Special considerations apply if you are
using an intercommunication environment.
For more information
about transaction routing, see Transaction routing.If
the task is not initiated from a terminal, INVREQ occurs. INVREQ also
occurs if an attempt is made to issue an ASSIGN command with this
option from a remotely linked-to program.
- OPID(data-area)
- Returns,
in a three-byte area, the operator identification that is specified
in the OPID field on the User Definitions (UD) entry for
the user that is signed on to the terminal that initiated the transaction.
If the task if started from another region, the OPID of the UD entry
for the user that is associated with the incoming request is returned.
For information about how a user ID is determined for inbound requests,
see Link security and user security compared.
- OPSECURITY(data-area)
- Returns
a three-byte string that indicates the transaction security key, which
is copied from the TSLKeylist attribute in the UD. If the task
is not initiated from a terminal, INVREQ occurs. INVREQ also occurs
if an attempt is made to issue an ASSIGN command with this option
from a remotely linked-to program.
Note: OPSECURITY returns only
the lowest 24 bits of the value that is returned by OPERKEYS, and
is supported for compatibility but not recommended. OPERKEYS returns
a 64-bit mask.
- OUTLINE(data-area)
- Returns
a one-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. INVREQ
also occurs if an attempt is made to issue an ASSIGN command with
this option from a remotely linked-to program.
- PRINSYSID(data-area)
- Returns
a four-byte string that represents the name of the local region for
the remote region. If the principal facility is not an APPC session,
or if the task has no principal facility, INVREQ occurs.
- PROGRAM(data-area)
- Obtains
values from outside the local environment of the application program.
The eight-character program name that is defined in the PD.stanza
of local region the running transaction is returned with
this option.
- PS(data-area)
- Returns
a one-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. INVREQ
also occurs if an attempt is made to issue an ASSIGN command with
this option from a remotely linked-to program.
- QNAME(data-area)
- Returns
a four-byte string that represents the 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. INVREQ also occurs if an attempt
is made to issue an ASSIGN command with this option from a remotely
linked-to program.
- RESTART(data-area)
- (This
option is ignored TXSeries for Multiplatforms.)
It always returns the default X'00', which is a one-byte
indicator that shows a normal start of the task.
- SCRNHT(data-area)
- Returns
a 16-bit binary field that indicates the number of rows for the terminal
screen that are defined for the current transaction. If the task is
not initiated from a terminal, INVREQ occurs. INVREQ also occurs if
an attempt is made to issue an ASSIGN command with this option from
a remotely linked-to program.
- SCRNWD(data-area)
- Returns
a 16-bit binary field that indicates the number of columns for the
terminal screen that are defined for the current transaction. If the
task is not initiated from a terminal, INVREQ occurs. INVREQ also
occurs if an attempt is made to issue an ASSIGN command with this
option from a remotely linked-to program.
- SIGDATA(data-area)
- Returns
a four-byte field that reflects any signal status that is received
from an APPC partner program. The value is X'00010001' if
the APPC partner program has set signal status, or X'00000000' if
it has not. If the task is not initiated from a principal facility,
INVREQ occurs. INVREQ also occurs if an attempt is made to issue an
ASSIGN command with this option from a remotely linked-to program.
- SOSI(data-area)
- Returns
a one-byte indicator that shows whether the terminal is defined as
having the mixed Single-Byte Character Set (SBCS) and Double-Byte
Character Set (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) bytes; the DBCS subfields within an ASCII field
are not. If the task is not initiated from a terminal, INVREQ occurs.
INVREQ also occurs if an attempt is made to issue an ASSIGN command
with this option from a remotely linked-to program.
- STARTCODE(data-area)
- Returns
a two-byte string that indicates how the current transaction was started.
It can have the following values:
- D
- A distributed program link (DPL) request. The program cannot issue
I/O requests against its principal facility, nor can it issue any
syncpoint requests.
- DS
- A distributed program link (DPL) request, as in code D, with the
exception that the program can issue syncpoint requests.
- QD
- Transaction started by transient data trigger level.
- S
- Transaction started by START command (no data).
- SD
- Transaction started by START command (with data).
- SZ
- Transaction started by FEPI. For a list of the EIBFN numbers,
see Table 2.
- TD
- Transaction started by terminal input.
- U
- Transaction started by the startup or shutdown program lists.
- SYSID(data-area)
- Returns
a four-byte string that represents the name that is given to the local
region. You can specify this value in the SYSID option of a file control,
interval control, program control, temporary storage, or transient
data command, in which case CICS assumes that the resource
that is to be accessed is on the local region.
- TCTUALENG(data-area)
- Returns
a 16-bit binary field that indicates the length of the Terminal User
Area (TCTUA). If no Terminal User Area exists, CICS returns
zero. INVREQ occurs if an attempt is made to issue an ASSIGN command
with this option from a remotely linked-to program.
- TERMCODE(data-area)
- Returns
a two-byte string that indicates the type and model number of the
terminal and connection that is associated with the task.
The
first byte is a code that identifies the terminal type, as specified
by the TermType attribute in the WD. The second byte is a single-byte
model number, as specified by the TermSubType attribute in
the WD.
For locally attached terminals, CICS returns
the following terminal type code (listed here as both a bit pattern
and a hexadecimal value).
Code |
Meaning |
1001 0001 X'91' |
3277 remote |
The terminal type for a DTP back-end program is X'0C'
Other
values can be returned for remotely attached terminals. INVREQ occurs
if the task is not initiated from a terminal or if it is not a DTP
back-end program. INVREQ also occurs if an attempt is made to issue
an ASSIGN command with this option from a remotely linked-to program.
- TWALENG(data-area)
- Returns
a 16-bit binary field that indicates the length of the Transaction
Work Area (TWA). If no TWA exists, CICS returns
zero.
- UNATTEND(data-area)
- (This
option is ignored in TXSeries for Multiplatforms.)
It always returns the default X'00', which is a one-byte
indicator that shows that the mode of operation of the terminal is
not unattended. If the task is not initiated from a terminal, INVREQ
occurs. INVREQ also occurs if an attempt is made to issue an ASSIGN
command with this option from a remotely linked-to program.
- USERID(data-area)
- Returns
an eight-byte string that indicates the user ID of the user that is
signed on. This option returns a blank string when no user identifier
exists. Special considerations apply if you are using an intercommunication
environment. For more information about the ASSIGN command for APPC,
see Using the assign command in the application-owning region.
If
the task is not initiated from a terminal, INVREQ occurs.
- VALIDATION(data-area)
- Returns
a one-byte indicator that shows whether the terminal is defined as
having the validation capability, which consists of the mandatory
fill, mandatory enter, and trigger attributes (X'FF') or
not (X'00'). If the task is not initiated from a terminal,
INVREQ occurs. INVREQ also occurs if an attempt is made to issue an
ASSIGN command with this option from a remotely linked-to program.
Conditions
- INVREQ
- Occurs
for the following conditions, depending on the options that are specified
on the ASSIGN command. Where an option can cause the INVREQ condition,
this is indicated in the description of that option.
- The task does not have a signed-on user.
- No Basic Mapping Support (BMS) map has yet been positioned.
- The task is not initiated by Automatic Transaction Initiation
(ATI).
- The command is run in the Application-owning Region (AOR) for
a routed transaction.
- The task is not associated with a terminal.
- An attempt was made to issue an ASSIGN command with a restricted
option from a remotely linked-to program.
- OPID was specified, but the task was not initiated from a terminal.
Default action: Terminates the task abnormally.