Add ICF Device Entry (ADDICFDEVE)

The Add Intersystem Communications Function Device Entry (ADDICFDEVE) command adds a program device entry to the specified intersystem communications function (ICF) file.

Parameters

File (FILE)

Specifies the intersystem communications function (ICF) file to which the ICF program device entry is to be added.

This is a required parameter.

Qualifier 1: File

name

Specify the name of the ICF file.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library is used to locate the ICF file. If no library is specified as the current library for the job, QGPL is used.

name

Specify the library where the ICF file is located.

Program device (PGMDEV)

Specifies the name by which the ICF program device entry being added is known. The total number of program device entries that may be added to an ICF file (as specified on the ADDICFDEVE or OVRICFDEVE command) is determined by the Maximum program devices (MAXPGMDEV) parameter on the Create Intersystem Communications Function File (CRTICFF) or Change Intersystem Communications Function File (CHGICFF) command.

The name specified for this parameter is the ICF program device entry with which the user's program communicates. This name is used on device-specific input/output operations to identify the program device and its attributes. Although the user may specify the same remote location name on more than one device entry, each program device name must be unique among the entries for the ICF file. This allows the user to have more than one session to the same remote location, or to have different attribute values for each session to the same remote location.

Note: Refer to the APPC Programming book, SC41-5443 for information on how the system uses the RMTLOCNAME, DEV, LCLLOCNAME, and RMTNETID parameters to select an APPC device description.

This is a required parameter.

character-value

Specify the name of the ICF program device entry being added. This name is used on device-specific input/output operations to identify the program device entry and the attributes. This program device entry name must be unique throughout the program device entries for the ICF file.

Remote location (RMTLOCNAME)

Specifies the name of the remote location with which your program communicates.

This is a required parameter.

*REQUESTER

The name used to refer to the communications device through which the program is started is used. The session that is assigned when the program device is acquired is the same session in which the program start request is received. If the program is not started as a result of a program start request, the acquire operation of the program device fails. The target program uses *REQUESTER as the remote location name in the intersystem communications function (ICF) file to connect to the session that the source program used to send the program start request.

The *REQUESTER value can be specified on only one program device entry and is valid only for a target communication job. If *REQUESTER is specified in any other type of job, a message is sent.

communications-name

Specify the full name of a remote location. The remote location does not need to exist at the time this command is run, but it must exist (be configured on the system as a device description or in the advanced peer-to-peer networking (APPN) function) for this remote location at the time the program acquires the program device. The same remote location name may be specified for many different program device entries. However, only one program device name associated with each asynchronous (ASYNC), SNA upline facility (SNUF), or binary synchronous communication equivalence link (BSCEL) remote location may be added to the file at any one time. This value cannot be specified with CNVTYPE(*SRCPGM).

Communication type (CMNTYPE)

Specifies the communications types that may appear in the prompt display. This parameter is used only for the purpose of prompting. The value specified for this parameter determines the subset of other parameters that are shown (prompted) for the user.

*ALL

All parameters appear in the prompt.

*APPC

Only the advanced program-to-program communications (APPC) parameters appear in the prompt.

*ASYNC

Only the asynchronous communications (ASYNC) parameters appear in the prompt.

*BSCEL

Only the binary synchronous communications equivalence link (BSCEL) parameters appear in the prompt.

*FINANCE

Only the FINANCE parameters appear in the prompt.

*INTRA

Only the INTRA parameters appear in the prompt.

*RETAIL

Only the RETAIL parameters appear in the prompt.

*SNUF

Only the Systems Network Architecture Upline Facility (SNUF) parameters appear in the prompt.

Device (DEV)

Specifies the communications device used in the remote location. This parameter is specified only for APPC, Finance, Retail, SNUF, and INTRA communications.

*LOC

The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.

name

Specify the name of a communications device associated with the remote location. If the device name is not valid for the remote location, an escape message is sent when the program device is acquired. More information on device names is in the APPC Programming book, SC41-5443.

Local location (LCLLOCNAME)

Specifies the local location name.

*LOC

The local location name associated with the remote location is used.

*NETATR

The LCLLOCNAME value specified in the system network attributes is used.

communications-name

Specify the local location name associated with the program device. The local location name is specified only if you want to indicate a different specific local location name for the remote location. If the local location name is not valid, an escape message is sent when the program device is acquired.

Mode (MODE)

Specifies the mode name being used. This parameter applies only to APPC communications.

*NETATR

The mode in the network attributes is used.

BLANK

A mode name consisting of 8 blank characters is used.

communications-name

Specify a mode name for the APPC communication device. If the mode is not valid for any combination of remote location device, local location, and remote network ID, an escape message is sent when the program device is acquired.

Remote network identifier (RMTNETID)

Specifies the remote network identifier used with the remote location. This parameter applies only to the APPC communications.

*LOC

Any remote network identifier for the remote location may be used. If several remote network IDs are associated with the remote location, the system determines which remote network ID is used.

*NETATR

The remote network identifier specified in the network attributes is used.

*NONE

No remote network identifier is used.

communications-name

Specify a remote network identifier to be associated with the program device entry.

Format select (FMTSLT)

Specifies the type of record format selection used for input operations.

*PGM

The program determines record format selections. If an input (read) operation with a record format name is specified, that format is always selected. If a record format is not specified for the input operation, the default format (the first record format in the file) is always selected.

*RECID

The RECID keywords specified in the data description specifications (DDS) for the file are used to do a record selection. If there are no RECID keywords in the DDS, an error message is returned, and the program device is not acquired.

*RMTFMT

The remote format names received from the sending system are used to do a record selection. If the device is not an APPC device and *RMTFMT is specified, a run time error message is sent at the time the program device is acquired.

Application identifier (APPID)

Specifies (in characters) the Virtual Telecommunications Access Method (VTAM) identifier of the Customer Information Control System for Virtual Storage (CICS/VS) or the Information Management System for Virtual Storage (IMS/VS) host subsystem sent with the sign-on message. This parameter applies only to SNUF communications.

*DEVD

The application identifier specified in the device description is used.

*USER

The application program can send messages or a logon to the host. This is valid only when using the 3270 program interface.

name

Specify an application identifier for the VTAM of the CICS/VS or IMS/VS.

Batch activity (BATCH)

Specifies, for both the Customer Information Control System for Virtual Storage(CICS/VS) and the Information Management System for Virtual Storage (IMS/VS), whether this session is used for batch jobs. This parameter applies to SNUF, INTRA, and RETAIL communications.

*NO

Batch jobs do not occur in this session.

*YES

Batch jobs occur and SNUF does not assemble physical records into logical records. If *YES is specified, *NO must be specified for the Message protection (MSGPTC) parameter.

Host type (HOST)

Specifies the host system or remote subsystem with which the local system or subsystem is communicating during this session. This parameter applies only to SNUF communications.

*DEVD

The host system specified in the device description is used.

*CICS

The Customer Information Control System for Virtual Storage is used during this communication session.

*IMS

The Information Management System for Virtual Storage is used during this communication session.

*IMSRTR

The Information Management System for Virtual Storage uses the ready-to-receive option during this communication session.

End session with host (ENDSSNHOST)

Specifies how the Systems Network Architecture upline facility (SNUF) ends the session with the host.

*RSHUTD

SNUF sends a request to turn off command to the host.

*TERMSELF

SNUF sends an end-session command to the host. This value may have to be used if the value *RSHUTD fails to end a session with a non-IBM host.

Special host application (SPCHOSTAPP)

Specifies whether SNUF customizes support for special host applications outside the CICS or IMS application layer.

*DEVD

The special host application specified in the device description is used.

*NONE

SNUF does not customize support for special host applications.

*FLASH

SNUF customizes support for the Federal Reserve Flash application.

Initialize self (INZSELF)

Specifies whether a formatted INIT-SELF is built in place of the unformatted sign-on normally sent by SNUF to the host.

*NO

The unformatted default sign-on provided by SNUF is used.

*YES

The formatted INIT-SELF provided by SNUF is used.

Header processing (HDRPROC)

Specifies, for both the Customer Information Control System for Virtual Storage (CICS/VS) and the Information Management System for Virtual Storage (IMS/VS) whether the received function management headers are passed to the application program. This parameter applies only to SNUF communications.

*SYS

SNUF removes function management headers before passing data to the program.

*USER

SNUF does not remove function management headers before passing data to the program.

Message protection (MSGPTC)

Specifies, for both the Customer Information Control System for Virtual Storage (CICS/VS) and Information Management System for Virtual Storage (IMS/VS), whether message protection is being used for this session. This parameter applies only to SNUF communications.

*YES

Message protection is used. SNUF saves messages until you respond to them, and tries synchronization again if additional errors occur. *YES is valid only when *NO is specified for the Batch activity (BATCH) parameter.

*NO

Message protection is not used.

Emulation device (EMLDEV)

Specifies that this program device entry is used to send and receive 3270 data streams. The emulation device parameter consists of an emulation device type and an emulation device data format. The emulation device data format specifies the format of the type 3270 data stream being sent or received. A 20- or 32-byte common header that contains type 3270 command and data flow information is located at the start of the I/O buffer that is sending or receiving the type 3270 data stream. This parameter applies only to SNUF communications. This parameter can be specified as a list of two values (elements) or as a single value (*NONE).

The emulation device data format specifies the format of the type 3270 data stream being sent or received. A 20- or 32-byte common header that contains type 3270 command and data flow information is located at the start of the I/O buffer that is sending or receiving the type 3270 data stream.

Single values

*NONE

This program device entry is not used to send and receive 3270 data streams.

Element 1: Device type

3278

The data stream is for a 3278, 3277, or 3279 display device.

3284

The data stream is for a 3284 printer device.

3286

The data stream is for a 3286 printer device.

3287

The data stream is for a 3287 printer device.

3288

The data stream is for a 3288 printer device.

3289

The data stream is for a 3289 printer device.

Element 2: Data format

*UNFORMAT

An unformatted 3270 data stream is sent or received. The user application program must translate the data stream into a display or printer image.

*FIELD

A formatted 3270 data stream is sent or received. The formatted 3270 data stream contains a display or printer image that contains field definitions. The field definitions indicate the location and characteristics of the fields. *FIELD is valid only if *NO is specified for the Batch activity (BATCH) parameter.

*NOFIELD

A formatted 3270 data stream is sent or received. The formatted 3270 data stream contains a display or printer image without field definitions. *NOFIELD is valid only if *NO is specified for the BATCH parameter.

*EXTFIELD

A formatted 3270 data stream is sent or received. The formatted 3270 data stream contains a display or printer image followed by field definitions. The field definitions indicate the location and characteristics of fields. *EXTFIELD is valid only if *NO is specified for the BATCH parameter and 3278 is specified as the emulation device type.

Conversation type (CNVTYPE)

Specifies the conversation type for which the application program is designed. This parameter is valid only for (APPC) communications. More information on the APPC communications type can be found in the APPC Programming book, SC41-5443.

*SYS

The system gives the length and general data stream identifier values that precede each section of user data in the APPC device protocol. The application gives the data portion of the general data stream on output operations, and receives only the data portion of the general data stream on input operations. This is the mapped conversation support for LU 6.2 architecture.

*USER

The application program gives the length and general data stream identifier values that precede each section of user data in the APPC device protocol. This is the basic conversation support for LU 6.2 architecture.

*SRCPGM

The target program accepts the conversation type specified by the source program. If this value is specified, RMTLOCNAME(*REQUESTER) must also be specified.

Blocking type (BLOCK)

Specifies whether the system or the user controls how records are combined into blocks when they are sent. This parameter is only for BSCEL communications. With this parameter, you may specify one of the following conditions of record formatting:

• No blocking or deblocking: The record format described in the DDS is the format for both the record and the block.
• User blocking or deblocking: Gives the BSC controls needed to describe the record format of the system.
• System blocking with record separator characters: Specify the record separator character used by the system to determine record boundaries within the block.
• System blocking of fixed-length records: The system uses fixed-length records, and blocks or deblocks accordingly.

If you specify a value other than *NONE or *USER, records are blocked as required by the system for output, and are deblocked on input.

Element 1: Blocking type

*DEVD

The block option specified in the device description is used.

*NONE

Blocking or deblocking is not done by the system.

*ITB

The records are blocked or deblocked based on the location of an intermediate text block (ITB) control character. For input files, a record is delimited by locating the next intermediate text block character. An end-of-text or end-of-transmission block character is used as an intermediate text block character to delimit a block. For output files, an ITB character is added after the record. If it is the last character of the block, the ITB is replaced by an end-of-text or end-of-transmission block character.

*IRS

The records are blocked or deblocked based on the location of an interrecord separator (IRS) character. For input files, a record is delimited by locating the next IRS character. For output files, an IRS character is added following the record.

*NOSEP

No record separator character is contained in the block that is either sent to or received from the device. The system blocks and deblocks the records by using a fixed-length record, as specified in the data description specifications (DDS) format specifications.

*USER

The program supplies the control characters, including record separator characters, BSCEL framing characters, transparency characters, and so forth, that are necessary to send records. More information about the device and binary synchronous communications equivalence link (BSCEL) support characteristics is in the BSC Equivalence Link Programming book, SC41-5445.

*SEP

The records are blocked or deblocked based on the location of a record separator character specified by the user. For input files, a record is delimited by locating the next record separator character. For output files, a record separator character is added after the record.

Element 2: Record separator, if *SEP

X'1E'

Record separator character X'1E' is used.

hexadecimal-value

Specify a unique, 1-byte record separator character. The record separator character may be specified as 2 hexadecimal characters, as in BLOCK(*SEP FD) where X'FD' is the separator character.

The following characters are not not valid as separator characters because these characters are used for BSC control:

Figure: Characters Unavailable for Record Separators

EBCDIC ASCII BSC Control ------ ----- ----------------------------------- X'01' X'01' SOH (start-of-header) X'02' X'02' STX (start-of-text) X'03' X'03' ETX (end-of-text) X'10' X'10' DLE (data-link escape) X'1D' X'1D' IGS (interchange group separator) X'1F' X'1F' ITB (intermediate text block) X'26' X'17' ETB (end-of-transmission block) X'2D' X'05' ENQ (enquiry) X'32' X'16' SYN (synchronization) X'37' X'04' EOT (end-of-transmission) X'3D' X'15' NAK (negative acknowledgment)

Record length (RCDLEN)

Specifies the maximum record length (in bytes) for data being sent and received. This parameter applies only to SNUF and BSCEL communications.

*DEVD

The record length specified in the device description is used. If a record is longer than the specified record length, a run time error occurs at the time the record is sent or received.

1-32767

Specify the maximum allowed record length when this device file is used. If a record is longer than the specified record length, a run time error occurs at the time the record is sent or received. Valid values range from 1 through 32767 bytes for SNUF communications. For BSCEL communications, the maximum record length is 8192 bytes.

Block length (BLKLEN)

Specifies the maximum block length (in bytes) for data being sent. This parameter applies only to BSCEL and SNUF communications.

*DEVD

The block length specified in the device description is used.

1-32767

Specify the maximum block length (in bytes) of records sent when using this device file. The value must be at least the size of the largest record sent. Valid values range from 1 through 32767 for SNUF communications. For BSCEL communications, the maximum block length is 8192 bytes.

Transmit in transparent mode (TRNSPY)

Specifies whether data is sent in transparent text mode. Text transparency allows all 256 EBCDIC character codes to be sent. Use this function when sending packed or binary data fields. This parameter applies only to BSCEL communications.

*DEVD

The text transparency option specified in the device description is used.

*NO

Text transparency is not used.

*YES

Text transparency is used, which allows all 256 EBCDIC character codes to be sent. *YES is valid only when *NONE, *NOSEP, or *USER is specified for the Blocking type (BLOCK) parameter.

Note: Transparency of received data is determined by the data stream; therefore, this parameter is not relevant for received data. If TRNSPY(*YES) is specified with BLOCK(*USER), BSCEL ignores the transparency indicator during write operations. Correct controls must be given with the data to get transparent sending of data. For example, the data-link escape (DLE) and start-of-text (STX) control characters must first be specified; the system provides the remaining control characters required for transparent sending of data.

Compress and decompress data (DTACPR)

Specifies whether blanks in BSCEL data are compressed for output and decompressed for input. This parameter applies only to BSCEL communications.

*DEVD

The data compression option specified in the device description is used.

*NO

No data compression or decompression is used.

*YES

Data is compressed for output and decompressed for input. *YES cannot be specified here if *YES is specified for the Transmit in transparent mode (TRNSPY) parameter.

Truncate trailing blanks (TRUNC)

Specifies whether trailing blanks are removed from output records. This parameter applies only to BSCEL communications.

*DEVD

The trailing blanks option specified in the device description is used.

*NO

Trailing blanks are not removed from output records.

*YES

Trailing blanks are removed from output records. *YES cannot be specified if BLOCK(*NOSEP) is specified for the Blocking type (BLOCK) parameter. If *YES is specified here and *YES is also specified for the Compress and decompress data (DTACPR) parameter, trailing blanks are not removed from output records.

Overflow data (OVRFLWDTA)

Specifies whether overflow data is discarded or retained.

*DISCARD

Overflow data is not kept.

*RETAIN

Overflow data is kept.

Group separator type (GRPSEP)

Specifies a separator for groups of data (for example, data sets and documents). This parameter applies only to BSCEL communications.

*DEVD

The group separator option specified in the device description is used.

*DEV3740

A null record (STXETX) is used as a data group separator.

*EOT

A block is sent that ends with the BSCEL end-of-transmission (EOT) control character used as a data group separator.

*OFCSYS

A block is sent that ends with the BSCEL end-of-information (ETX) control character is used as a data group separator.

Remote BSCEL (RMTBSCEL)

Specifies the type of BSCEL session established with the remote system. This parameter applies only to BSCEL communications.

*DEVD

The RMTBSCEL option specified in the device description is used.

*NO

The remote system cannot recognize BSCEL commands or messages. In most cases, *NO is used when communicating with remote systems such as a 3741 Data Entry Station, an Office System 6, a 5230 Data Collection System, or a System/38.

*YES

The remote system recognizes the BSCEL transaction starting commands, transaction ending commands, and online messages. In most cases, *YES indicates that the remote system is another IBM i, or a System/38, System/36, or System/34 with BSCEL support.

Initial connection (INLCNN)

Specifies the method of making a connection on the line for the session being accessed. This parameter applies only to binary synchronous communications equivalence link (BSCEL) communications.

*CTLD

The initial connection option specified in the controller description is used.

*ANS

The remote system starts the call, and the local system answers the call.

*DIAL

The local system starts the call, and the remote system answers the call.

Examples

Example 1: Using RECID Keywords for Record Selection

ADDICFDEVE   FILE(ICFFILE1)  PGMDEV(BSCEL2)
             RMTLOCNAME(BSCNYC)  FMTSLT(*RECID)

This command adds the program device entry named BSCEL2 with a corresponding remote location named BSCNYC for the ICF file ICFFILE1. The program device is added with the attributes of FMTSLT(*RECID).

Example 2: Using Remote Format Names for Record Selection

ADDICFDEVE   FILE(QGPL/ICFTEST)  PGMDEV(APPC1)
             RMTLOCNAME(*REQUESTER)
             FMTSLT(*RMTFMT)  CNVTYPE(*SYS)

This command adds the program device entry named APPC1 with a remote location name of *REQUESTER for the ICF file ICFTEST in the QGPL library. This program device entry has the FMTSLT(*RMTFMT) and CNVTYPE(*SYS) attributes.

Example 3: Adding a Program Device Entry

ADDICFDEVE   FILE(ICFLIB/TESTFILE)  PGMDEV(JOE)
             RMTLOCNAME(LU0MPLS)

This command adds the program device entry named JOE with remote location named LU0MPLS for the ICF file TESTFILE in library ICFLIB.

Example 4: Adding a Program Device Entry

ADDICFDEVE   FILE(TESTFILE)  PGMDEV(APPC)
             RMTLOCNAME(APPCMPLS)  DEV(MPLSLINE2)

This command adds the program device entry named APPC with a remote location name of APPCMPLS using device MPLSLINE2 to the ICF file TESTFILE.

Error messages

*ESCAPE Messages

CPF7365

Device not added to file &1 in &2.