Obtains values from outside the application program's local environment.

Sintaxe

Condição: INVREQ

Fields ignored in TXSeries for Multiplatforms:

BTRANS

GCHARS

GCODES

MSRCONTROL

OPCLASS

RESTART

UNATTEND

Descrição:

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.

Opções:

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.

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, refer to the TXSeries for Multiplatforms Intercommunication Guide.
• 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.
• NVREQ 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 that regions's name.
• 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 you can see under the directory "Drive:\opt\cics\include".
• Note:
  • This option for ASSIGN API applies only to CICS systems that are using Microsoft^(R) 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 the TXSeries for Multiplatforms Intercommunication Guide.
• 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, refer to the TXSeries for Multiplatforms Intercommunication Guide.

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.
• Nota:
  • 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 local region's name 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 application program's local environment.
• The eight-character program name that is defined in the PD stanza of 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. See the Table 24 for a list of the EIBFN numbers.

  TD

  Transaction started by terminal input.

  U

  Transaction started by the startup or shutdown program lists.

SYSID(data-area)
• Rturns 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.
• See the TXSeries for Multiplatforms Intercommunication Guide for more information about the ASSIGN command for APPC.
• 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.

Condições:

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.

• TXSeries for Multiplatforms Intercommunication Guide
• TXSeries for Multiplatforms Administration Reference