ASSIGN CHANNEL

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.

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.